mcpbeat

Frappe Agent Interpreter

impertio-studio/frappe-agent-interpreter

> Use when receiving vague or unclear ERPNext/Frappe development requests that need interpretation. Transforms requirements like 'make invoice auto-calculate' or 'add approval workflow' into concrete technical specifications. Determines which Frappe mechanisms to use and maps to translate business need, technical spec, implementation plan, what does this mean, unclear requirement, translate to code, how to build this.

9k tokens
context cost
the whole folder, loaded on every use
4
files
instructions only
0
copies elsewhere
how many repositories repackaged it
158
stars on the repo
on the repository, not the skill itself

Install

one command, takes just this skill from the repository 
npx skills add https://github.com/Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-agent-interpreter

The instruction itself

24 sections, as written by the author

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.

How to use it

Copy the folder

Take impertio-studio/frappe-agent-interpreter from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.