Frappe Agent Interpreter Agent Skill

Frappe Code Interpreter Agent

Transforms vague or incomplete Frappe/ERPNext development requests into clear, actionable technical specifications mapped to the full 61-skill catalog.

Purpose: Bridge the gap between "what the user wants" and "what needs to be built"

When to Use This Agent

USER REQUEST ANALYSIS
|
+-- Request is vague/incomplete
|   "Make the invoice do something when submitted"
|   --> USE THIS AGENT
|
+-- Request lacks technical specifics
|   "Add approval before order confirmation"
|   --> USE THIS AGENT
|
+-- Multiple implementation paths possible
|   "Automate inventory updates"
|   --> USE THIS AGENT
|
+-- Request has clear technical specs already
|   "Create Server Script on validate for Sales Invoice"
|   --> Skip agent, use relevant frappe-* skills directly

Interpretation Workflow

STEP 1: EXTRACT INTENT
  - What is the business problem?
  - What should happen? When? To what data?
  - Who should be affected (roles/users)?

STEP 2: IDENTIFY TRIGGER CONTEXT
  - Document lifecycle event? (save/submit/cancel)
  - User action? (button click, field change)
  - Time-based? (daily, hourly, cron)
  - External event? (webhook, API call)

STEP 3: DETERMINE MECHANISM
  - Client Script, Server Script, or Controller?
  - Hooks configuration needed?
  - Custom app required?
  - v16 extend_doctype_class applicable?

STEP 4: GENERATE SPECIFICATION
  - DocType(s), event/trigger, mechanism, data flow
  - Error handling requirements
  - Version compatibility (v14/v15/v16)

STEP 5: MAP TO SKILLS
  - List required frappe-* skills from full catalog
  - Note dependencies between skills

See references/workflow.md for detailed steps.

Mechanism Selection Matrix

| Requirement Pattern | Mechanism | Custom App? |

|---------------------|-----------|:-----------:|

| "Auto-calculate on form" | Client Script + Server Script | No |

| "Validate before save" | Server Script (validate) | No |

| "Send notification after submit" | Server Script (on_submit) | No |

| "Add button to form" | Client Script | No |

| "Scheduled report/sync" | hooks.py scheduler_events | Yes |

| "Filter list per user" | Server Script (Permission Query) | No |

| "Custom REST API" | Server Script (API) or @frappe.whitelist() | Depends |

| "Complex transaction with rollback" | Controller | Yes |

| "External library needed (requests)" | Controller | Yes |

| "Approval workflow" | Built-in Workflow + optional Server Script | No |

| "Print format customization" | Jinja template (Print Format) | No |

| "Custom report" | Script Report or Query Report | Depends |

| "Background processing" | frappe.enqueue() | Yes |

| "File upload handling" | Controller + File hooks | Yes |

| "Cache invalidation" | Cache API + hooks | Yes |

| "Website/portal page" | Web template + routing | Yes |

| "UI component (dashboard, etc.)" | Page or Custom Page | Yes |

Clarifying Questions Framework

1. WHAT Questions

• What DocType(s) are involved?
• What data needs to change?
• What should the outcome be?

2. WHEN Questions

• On form load? On field change? Before/after save?
• Before/after submit? On a schedule? Button click?

3. WHO Questions

• All users? Specific roles? Document owner only?

4. WHERE Questions

• In the form (UI)? Database only? Report? External system?

5. ERROR Questions

• Block the operation? Show warning? Log silently?

6. VERSION Questions (v16 considerations)

• Target single version or multi-version compatibility?
• Can we use extend_doctype_class (v16) or need doc_events (v14+)?
• Type annotations desired? (v16 best practice)

Output Specification Template

ALWAYS generate specifications in this format:

## Technical Specification

### Summary
[One sentence describing what will be built]

### Business Requirement
[Original user request, clarified]

### Implementation

| Aspect | Value |
|--------|-------|
| **DocType(s)** | [List] |
| **Trigger** | [Event/action] |
| **Mechanism** | [Client Script / Server Script / Controller / etc.] |
| **Version** | [v14 / v15 / v16 / all] |

### Data Flow
1. [Step 1]
2. [Step 2]

### Error Handling
[Strategy]

### Required Skills
- [ ] frappe-skill-name - for [purpose]

### Validation Criteria
[How to verify it works]

Complete Skill Catalog (61 skills)

Syntax Layer (11 skills)

| Skill | Use For |

|-------|---------|

| frappe-syntax-clientscripts | Client Script JS syntax |

| frappe-syntax-serverscripts | Server Script Python sandbox syntax |

| frappe-syntax-controllers | Controller class syntax |

| frappe-syntax-hooks | hooks.py configuration syntax |

| frappe-syntax-hooks-events | Document event hook syntax |

| frappe-syntax-whitelisted | @frappe.whitelist() syntax |

| frappe-syntax-jinja | Jinja template syntax |

| frappe-syntax-scheduler | Scheduler/enqueue syntax |

| frappe-syntax-customapp | App structure syntax |

| frappe-syntax-doctypes | DocType JSON definition syntax |

| frappe-syntax-reports | Report definition syntax |

Core Layer (7 skills)

| Skill | Use For |

|-------|---------|

| frappe-core-database | Database operations, ORM, raw SQL |

| frappe-core-permissions | Permission system, roles, rules |

| frappe-core-api | REST API, resource API |

| frappe-core-workflow | Workflow engine, states, transitions |

| frappe-core-notifications | Email, push, system notifications |

| frappe-core-files | File upload, attachment, storage |

| frappe-core-cache | Redis cache, cache invalidation |

Implementation Layer (12 skills)

| Skill | Use For |

|-------|---------|

| frappe-impl-clientscripts | Client Script implementation patterns |

| frappe-impl-serverscripts | Server Script implementation patterns |

| frappe-impl-controllers | Controller implementation patterns |

| frappe-impl-hooks | Hook implementation patterns |

| frappe-impl-whitelisted | Whitelisted method patterns |

| frappe-impl-jinja | Jinja template patterns |

| frappe-impl-scheduler | Scheduled task/background job patterns |

| frappe-impl-customapp | Custom app development workflow |

| frappe-impl-reports | Report building patterns |

| frappe-impl-workflow | Workflow implementation patterns |

| frappe-impl-website | Website/portal development |

| frappe-impl-ui-components | UI component patterns |

| frappe-impl-integrations | External system integration |

Error Layer (7 skills)

| Skill | Use For |

|-------|---------|

| frappe-errors-clientscripts | Client Script error patterns |

| frappe-errors-serverscripts | Server Script error patterns |

| frappe-errors-controllers | Controller error patterns |

| frappe-errors-hooks | Hook error patterns |

| frappe-errors-api | API error patterns |

| frappe-errors-permissions | Permission error patterns |

| frappe-errors-database | Database error patterns |

Ops Layer (8 skills)

| Skill | Use For |

|-------|---------|

| frappe-ops-bench | Bench CLI commands |

| frappe-ops-deployment | Production deployment |

| frappe-ops-backup | Backup and restore |

| frappe-ops-performance | Performance tuning |

| frappe-ops-upgrades | Version upgrade procedures |

| frappe-ops-cloud | Cloud hosting (FC, AWS, etc.) |

| frappe-ops-app-lifecycle | App versioning and releases |

| frappe-ops-frontend-build | Frontend asset building |

Testing Layer (2 skills)

| Skill | Use For |

|-------|---------|

| frappe-testing-unit | Unit and integration tests |

| frappe-testing-cicd | CI/CD pipeline setup |

Agent Layer (5 skills)

| Skill | Use For |

|-------|---------|

| frappe-agent-interpreter | THIS SKILL - requirement interpretation |

| frappe-agent-validator | Code validation before deployment |

| frappe-agent-debugger | Debugging Frappe issues |

| frappe-agent-migrator | Data migration planning |

| frappe-agent-architect | Architecture decision-making |

Skill Dependencies Map

| Mechanism | Required Skills |

|-----------|----------------|

| Client Script | frappe-syntax-clientscripts, frappe-impl-clientscripts, frappe-errors-clientscripts |

| Server Script (Doc Event) | frappe-syntax-serverscripts, frappe-impl-serverscripts, frappe-errors-serverscripts |

| Server Script (API) | frappe-syntax-serverscripts, frappe-core-api, frappe-errors-api |

| Server Script (Scheduler) | frappe-syntax-serverscripts, frappe-syntax-scheduler, frappe-impl-scheduler |

| Server Script (Permission) | frappe-syntax-serverscripts, frappe-core-permissions, frappe-errors-permissions |

| Controller | frappe-syntax-controllers, frappe-impl-controllers, frappe-errors-controllers |

| Hooks | frappe-syntax-hooks, frappe-impl-hooks, frappe-errors-hooks |

| Custom App | frappe-syntax-customapp, frappe-impl-customapp, frappe-ops-bench |

| Jinja Template | frappe-syntax-jinja, frappe-impl-jinja |

| Database Operations | frappe-core-database, frappe-errors-database |

| Whitelisted Method | frappe-syntax-whitelisted, frappe-impl-whitelisted |

| Workflow | frappe-core-workflow, frappe-impl-workflow |

| Reports | frappe-syntax-reports, frappe-impl-reports |

| Website/Portal | frappe-impl-website, frappe-syntax-jinja |

| Integration | frappe-impl-integrations, frappe-impl-customapp |

| Background Jobs | frappe-impl-scheduler, frappe-syntax-scheduler |

| Testing | frappe-testing-unit, frappe-testing-cicd |

| Deployment | frappe-ops-deployment, frappe-ops-bench |

Common Pattern Recognition

| User Phrase | Mechanism | Key Skills |

|-------------|-----------|------------|

| "auto-calculate", "automatically fill" | Client Script + Server Script | frappe-impl-clientscripts, frappe-impl-serverscripts |

| "validate", "check before save" | Server Script (validate) | frappe-impl-serverscripts |

| "prevent", "block", "don't allow" | Server Script + frappe.throw() | frappe-errors-serverscripts |

| "send email", "notify" | Server Script or Notification | frappe-core-notifications |

| "sync", "integrate", "API" | Controller (custom app) | frappe-impl-integrations |

| "every day", "schedule" | Scheduler or hooks.py | frappe-impl-scheduler |

| "only see their own" | Permission Query | frappe-core-permissions |

| "approval", "authorize" | Built-in Workflow | frappe-core-workflow, frappe-impl-workflow |

| "add button", "custom action" | Client Script | frappe-impl-clientscripts |

| "print format", "PDF" | Jinja Template | frappe-impl-jinja |

| "report", "dashboard" | Script/Query Report | frappe-impl-reports |

| "deploy", "go live" | Deployment workflow | frappe-ops-deployment |

| "test", "CI" | Testing framework | frappe-testing-unit |

| "cache", "performance" | Cache + optimization | frappe-core-cache, frappe-ops-performance |

Version Awareness

ALWAYS consider version compatibility:

| Feature | v14 | v15 | v16 |

|---------|:---:|:---:|:---:|

| Server Script sandbox | Yes | Yes | Yes |

| extend_doctype_class | No | No | Yes |

| Chrome PDF rendering | No | No | Yes |

| Data masking | No | No | Yes |

| UUID naming rule | No | No | Yes |

| Type annotations (best practice) | No | No | Yes |

| Scheduler tick (seconds) | 240 | 60 | 60 |

| job_id dedup | No | Yes | Yes |

Agent Output Checklist

Before completing interpretation, ALWAYS verify:

• [ ] Business requirement is clear and unambiguous
• [ ] Trigger/event is identified
• [ ] Mechanism is selected with justification
• [ ] DocType(s) are specified
• [ ] Data flow is documented
• [ ] Error handling approach is defined
• [ ] Version compatibility is noted (v14/v15/v16)
• [ ] Required frappe-* skills are listed from full catalog
• [ ] Validation criteria are defined
• [ ] v16 considerations noted (extend_doctype_class, type annotations)

See references/checklists.md for detailed checklists.

See references/examples.md for interpretation examples.