A methodology for creating comprehensive, deterministic skill and agent packages for open source projects using Claude AI
This document describes a proven methodology for developing AI skill packages that enable Claude instances to generate flawless code for specific frameworks or technologies. This approach was developed and validated during the creation of the ERPNext/Frappe Skills Package project.
The methodology emphasizes:
- Deep research before development
- Deterministic, verifiable content
- One-shot execution without iterations
- English-only skills (Claude reads English, responds in any language)
- Version control integration
┌─────────────────────────────────────────────────────────────────────────┐
│ SKILL PACKAGE DEVELOPMENT │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Phase 1 Phase 2 Phase 3 Phase 4 │
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │ DEEP │ → │PRELIM│ → │ REQ │ → │MASTER│ │
│ │RESRCH│ │RESRCH│ │DEFINE│ │ PLAN │ │
│ └──────┘ └──────┘ └──────┘ └──────┘ │
│ │
│ Phase 5 Phase 6 Phase 7 │
│ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │TOPIC │ → │SKILL │ → │VALID │ │
│ │RESRCH│ │CREATE│ │+PUSH │ │
│ └──────┘ └──────┘ └──────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Gain comprehensive understanding of the target technology/framework before any planning begins.
- Explore official documentation extensively
- Identify all major mechanisms/APIs/patterns
- Discover edge cases and version differences
- Find common pitfalls and anti-patterns
- Gather real-world examples
Raw knowledge and insights (may be informal notes or conversation)
"You cannot create deterministic skills for something you don't deeply understand."
We started by exploring all scripting mechanisms in ERPNext/Frappe:
- Client Scripts (JavaScript)
- Server Scripts (Python sandbox)
- Document Controllers
- hooks.py configuration
- Jinja templates
- Scheduler/Background jobs
- Whitelisted API methods
This revealed critical insights like the Server Script sandbox blocking all imports - a fundamental limitation that would affect all code generation.
Consolidate deep research into a structured reference document that serves as the foundation for all subsequent work.
- Organize findings into logical sections
- Document syntax patterns with examples
- Create decision matrices (when to use what)
- Note version differences explicitly
- List sources and verification status
vooronderzoek.md or preliminary-research.md - A comprehensive reference document
# [Technology] Preliminary Research
## 1. Overview
Brief description of the technology landscape
## 2. Mechanism A
### Syntax
### Use Cases
### Version Differences
### Anti-patterns
## 3. Mechanism B
[repeat structure]
## N. Decision Matrix
When to use which mechanism
## Sources
- Official documentation links
- GitHub source code references
- Community resources (dated 2023+)"The preliminary research document becomes the single source of truth for all skill development."
Define what the skill package must achieve and establish quality criteria.
- Identify target users (other Claude instances, developers)
- Define skill categories needed
- Establish constraints (line limits, structure requirements)
- Set quality guarantees
- Determine language requirements (bilingual, etc.)
Clear requirements document or section in masterplan
- What problems should the skills solve?
- What should a Claude instance be able to do after loading these skills?
- What quality guarantees do we provide?
- What are the structural constraints (Anthropic conventions)?
- What languages/versions must be supported?
- Skills must be deterministic (no assumptions)
- SKILL.md files must stay under 500 lines
- All skills in English only (Claude reads English, responds in any language)
- Version-explicit for ERPNext v14, v15, and v16
- Follow official Anthropic skill-creator conventions
- One-shot execution (no proof-of-concepts)
Create a comprehensive, phased execution plan with prompts for each step.
- Break work into logical phases
- Define dependencies between phases
- Create ready-to-use prompts for each phase
- Establish exit criteria per phase
- Plan for phase splitting when complexity exceeds thresholds
masterplan.md - Detailed execution plan
# [Project] Masterplan
## Vision & Goals
## Architecture Overview
## Complete Skill/Agent Index
## Phase 1: [Name]
### Goal
### Steps with Prompts
### Exit Criteria
### Dependencies
## Phase 2: [Name]
[repeat structure]
## Quality Guarantees
## AppendicesSplit a phase when:
- More than 700 lines of research content
- More than 5 reference files required
- More than 8-10 distinct sections
- Estimated execution exceeds conversation limits
"The masterplan should be detailed enough that each phase can be executed in a separate conversation without loss of context."
Before creating each skill, conduct focused research on that specific topic.
- Verify preliminary research against current documentation
- Deepen understanding of specific APIs/methods
- Gather additional examples
- Document version-specific behaviors
- Identify anti-patterns specific to this topic
research-[topic].md - Detailed research document per skill topic
# Research: [Topic]
## 1. Overview
## 2. Core Concepts
## 3. API Reference
## 4. Examples
## 5. Version Differences (v14 vs v15)
## 6. Anti-patterns
## 7. Best Practices
## 8. Sources
### For Skill Creation
- Key sections to include in SKILL.md
- Reference files needed
- Decision trees to create"Never create a skill based on assumptions. Always verify against official documentation and source code."
Transform research into actionable, deterministic skills following platform conventions.
- Create SKILL.md with quick reference and decision trees
- Create reference files (methods.md, examples.md, anti-patterns.md, etc.)
- Validate structure and line counts
- Create all language versions
- Package into distributable format
Complete skill packages (.skill files or folder structures)
skill-name/
├── SKILL.md # Main file (<500 lines)
│ ├── YAML frontmatter
│ ├── Quick Reference
│ ├── Decision Trees
│ ├── Essential Patterns
│ └── Links to references
└── references/
├── methods.md # Complete API signatures
├── events.md # Event listings
├── examples.md # Working code examples
└── anti-patterns.md # What NOT to do
- Lean: Stay under 500 lines
- Deterministic: "ALWAYS do X" not "consider doing X"
- Decision-oriented: Include decision trees for common choices
- Reference-linked: Detailed info in reference files
"A skill should enable another Claude instance to generate correct code on the first attempt, without needing clarification."
Ensure quality and preserve all work in version control.
- Validate YAML frontmatter
- Check line counts
- Verify all language versions are complete
- Package skills
- Commit with descriptive messages
- Push to GitHub
- Verify repository state
- Validated skill packages
- Updated GitHub repository
Phase [number]: [action] [subject]
Examples:
- Phase 4.3: Add frappe-impl-controllers skill
- Phase 2.8.1: Add hooks event documentation
- Phase 1.2: Complete server scripts research
- All files validated
- SKILL.md in folder root (Anthropic convention)
- Files in correct repository location
- Commit with descriptive message
- Push to GitHub
- Verify files in repository
- UPDATE ROADMAP.md ← CRITICAL!
- Add changelog entry with date and description
- Update status table (percentages, checkmarks)
- Update "Next Steps" section
"Every completed phase must be pushed to version control. Work that isn't committed doesn't exist."
"ROADMAP.md is the single source of truth for project status. If it's not updated, the next session won't know where we left off."
project-root/
├── README.md
├── SKILL.md # Main project skill (if applicable)
├── docs/
│ ├── masterplan/
│ │ ├── masterplan.md # Main plan
│ │ ├── vooronderzoek.md # Preliminary research
│ │ └── amendments/ # Plan adjustments
│ ├── research/ # Topic research documents
│ └── reference/ # Quick reference docs
├── skills/
│ ├── syntax/ # Syntax skills
│ ├── implementation/ # Implementation skills
│ ├── error-handling/ # Error handling skills
│ └── agents/ # Intelligent agents
└── memory/ # Project memory exports
| Type | Pattern | Example |
|---|---|---|
| Research | research-[topic].md |
research-client-scripts.md |
| Skill | erpnext-syntax-[topic]-[lang].skill |
frappe-syntax-hooks-NL.skill |
| Amendment | masterplan-aanpassing-fase-[x].md |
masterplan-aanpassing-fase-2_6.md |
Never start creating skills without thorough research. Assumptions lead to incorrect or incomplete skills.
Plan thoroughly so each phase can be executed correctly the first time. No "we'll fix it later" mentality.
Skills must provide clear, unambiguous guidance. Avoid phrases like:
- ❌ "You might want to consider..."
- ❌ "It's often good practice to..."
- ✅ "ALWAYS use X when Y"
- ✅ "NEVER do X because Y"
Always document which versions of the target technology are supported and note any differences.
Research → Verify → Document → Verify → Create → Validate
Commit and push after every completed phase. This ensures:
- Work is never lost
- Progress is trackable
- Collaboration is possible
- Rollback is available
A common mistake is tracking project status in multiple places:
- Claude Project Instructions
- ROADMAP.md
- README.md
- Conversation context
This leads to:
- Inconsistency: Different sources show different status
- Maintenance burden: Must update multiple places
- Confusion: Which source is correct?
ROADMAP.md is the ONLY place for project status tracking.
| What | Where | Update Frequency |
|---|---|---|
| Current phase & progress | ROADMAP.md | After EVERY phase |
| Methodology & workflows | WAY_OF_WORK.md | When process changes |
| Technical lessons | LESSONS.md | When discoveries made |
| Open tasks | GitHub Issues | As needed |
| Project instructions | Claude Project | Only for HOW, never for WHERE |
Claude's filesystem resets between sessions. The only persistent state is GitHub. If ROADMAP.md isn't updated:
- Next session starts without knowing current progress
- Risk of duplicate work
- Lost context about what was completed
-
Never hardcode status in Claude Project Instructions
- Instructions should describe HOW to work, not WHERE we are
- Reference ROADMAP.md for current status
-
ROADMAP.md update is MANDATORY after each phase
- Add changelog entry with date
- Update status percentages
- Update "Next Steps" section
-
Session start protocol
- Always fetch ROADMAP.md first
- Check changelog for last completed work
- Confirm current phase before proceeding
# ROADMAP - [Project Name]
> **📍 This is the SINGLE SOURCE OF TRUTH for project status.**
> **Last update**: [date]
> **Current phase**: [phase]
## Quick Status
[Table with categories, completed, remaining, total]
## Next Steps
[Immediate priorities]
## Phase Overview
[Detailed phase breakdown with status]
## Changelog
[Reverse chronological log of completed work]Monitor these thresholds:
| Metric | Threshold | Action |
|---|---|---|
| Research lines | >700 | Split into sub-phases |
| Reference files | >5 | Consider splitting |
| Sections | >8-10 | Split by logical grouping |
| Conversation length | Near limit | Split remaining work |
- Identify logical division points
- Create amendment document
- Update masterplan
- Ensure sub-phases are independent (no circular dependencies)
- Document the split rationale
Handle interrupted sessions (crashes, disconnects) gracefully and resume work without duplication or loss.
Claude's filesystem resets between sessions. When a session is interrupted mid-phase:
- Some files may have been pushed to GitHub
- Others may be lost
- Context about progress is lost
When starting a session that might be a continuation of interrupted work:
# Check recent commits
curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
"https://api.github.com/repos/[org]/[repo]/commits?per_page=5"
# Check specific directories for recent files
curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
"https://api.github.com/repos/[org]/[repo]/contents/skills/source/[category]"The changelog section in ROADMAP.md contains the most recent completed work:
curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
-H "Accept: application/vnd.github.raw" \
"https://api.github.com/repos/[org]/[repo]/contents/ROADMAP.md"Look for:
- Last changelog entry date
- Last completed phase/step
- Files mentioned as created
Compare:
- What ROADMAP says was completed
- What files actually exist in the repository
- What the user says they were working on
Always ask the user before resuming:
"I see that Phase X.Y was partially completed. The following files
are already pushed:
- file1.md ✅
- file2.md ✅
The following appear to be missing:
- file3.md ❌
Should I continue from [specific step]?"
To minimize recovery complexity:
- Push each file immediately after creation
- Update ROADMAP.md changelog after each significant step
- Use atomic commits (one logical change per commit)
"GitHub is the source of truth. Always scan repository state before assuming you need to start fresh."
- Web Search: For current documentation verification
- Project Knowledge Search: For accessing project documents
- File Creation/Editing: For document creation
- Bash Tools: For validation scripts, line counts
- GitHub API: For version control operations
quick_validate.py- YAML frontmatter validationpackage_skill.py- Skill packagingwc -l- Line count verification
- Official documentation (highest priority)
- GitHub source code
- Community resources (recent only, 2023+)
-
Sandbox Limitations Matter: We discovered that Frappe Server Scripts block all imports - this fundamental limitation affected all code generation guidance.
-
Phase Splitting is Normal: Complex topics like hooks.py and custom apps required splitting into multiple sub-phases. Plan for this.
-
Memory Helps Continuity: Using Claude's memory feature to store project context greatly improved consistency across conversations.
-
English-Only Skills: Skills are instructions FOR Claude, not for end users. Claude reads English and responds in ANY language. Creating bilingual skills doubles maintenance without functional benefit. See "Key Lesson: English-Only Skills" section below.
-
GitHub Integration is Essential: Pushing after each phase prevents work loss and enables collaboration.
-
Single Source of Truth for Status: Never track project status in multiple places. ROADMAP.md is the only place for status - Claude Project Instructions should describe HOW to work, not WHERE we are. Duplicate tracking leads to inconsistency and confusion.
I want to create a comprehensive skill package for [TECHNOLOGY] that will
enable Claude instances to generate correct [TECHNOLOGY] code.
Let's start with deep research:
1. What are all the major mechanisms/APIs in [TECHNOLOGY]?
2. What are common pitfalls and anti-patterns?
3. What version differences exist?
Document your findings - this will become our preliminary research.
Based on our research, let's define requirements:
1. What skills do we need? (syntax, implementation, error handling, agents?)
2. What languages should we support?
3. What quality guarantees do we want to provide?
Then create a detailed masterplan with phases and prompts.
Execute Phase [X.Y]: [Name]
Follow the masterplan prompt. After completion:
1. Validate all outputs
2. Commit: "Phase [X.Y]: [description]"
3. Push to GitHub
4. Verify repository state
This methodology transforms the challenge of creating comprehensive AI skill packages into a manageable, systematic process. By emphasizing research, planning, and version control, it ensures that the resulting skills are:
- Accurate: Based on verified information
- Deterministic: Providing clear guidance
- Complete: Covering all relevant aspects
- Maintainable: Organized and version-controlled
The key insight is that skills are only as good as the research behind them. Invest time in understanding the technology deeply before attempting to codify that knowledge into skills.
This methodology was developed during the ERPNext/Frappe Skills Package project by the OpenAEC Foundation, January 2025.
Original assumption: Create bilingual (NL + EN) skills for accessibility.
Discovery: Anthropic's own skills are ALL English-only. Analysis revealed:
- Skill instructions are for Claude, not end users
- Claude can read English instructions and respond in ANY language
- Bilingual skills double maintenance without functional benefit
- Anthropic's
package_skill.pyexpects simple folder structure
Recommendation: Always create English-only skills unless you have a very specific reason to deviate.
Before choosing your directory structure, test with Anthropic's official tooling:
# Validate skill structure
python quick_validate.py path/to/skill-folder
# Package skill
python package_skill.py path/to/skill-folder output/Critical requirement: SKILL.md must be DIRECTLY in the skill folder root, not in subfolders.
✅ CORRECT:
skill-name/
├── SKILL.md ← Direct in root
└── references/
❌ WRONG:
skill-name/
├── EN/
│ └── SKILL.md ← In subfolder - will FAIL
└── NL/
└── SKILL.md
Updated: January 2026 - Added Session Recovery Protocol, Project Status Tracking principles, English-only clarifications, v16 compatibility