create-skill

<essential_principles> ## How Skills Work Skills are modular, filesystem-based capabilities that provide domain expertise on demand. This skill teaches how to create effective skills. ### 1. Skills Are Prompts All prompting best practices apply. Be clear, be direct, use XML structure. Assume Claude is smart - only add context Claude doesn't have. ### 2. SKILL.md Is Always Loaded When a skill is invoked, Claude reads SKILL.md. Use this guarantee: - Essential principles go in SKILL.md (can't be skipped) - Workflow-specific content goes in workflows/ - Reusable knowledge goes in references/ ### 3. Router Pattern for Complex Skills ``` skill-name/ ├── SKILL.md # Router + principles ├── workflows/ # Step-by-step procedures (FOLLOW) ├── references/ # Domain knowledge (READ) ├── templates/ # Output structures (COPY + FILL) └── scripts/ # Reusable code (EXECUTE) ``` SKILL.md asks "what do you want to do?" → routes to workflow → workflow specifies which references to read. **When to use each folder:** - **workflows/** - Multi-step procedures Claude follows - **references/** - Domain knowledge Claude reads for context - **templates/** - Consistent output structures Claude copies and fills (plans, specs, configs) - **scripts/** - Executable code Claude runs as-is (deploy, setup, API calls) ### 4. Pure XML Structure No markdown headings (#, ##, ###) in skill body. Use semantic XML tags: ```xml <objective>...</objective> <process>...</process> <success_criteria>...</success_criteria> ``` Keep markdown formatting within content (bold, lists, code blocks). ### 5. Progressive Disclosure SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed for the current workflow. </essential_principles> <routing> ## Understanding User Intent Based on the user's message, route directly to the appropriate workflow: **Creating new skills:** - Domain expertise (exhaustive knowledge base) → **Use `create-domain-expertise` skill instead** (separate skill with batched subagent orchestration) - Task-execution skill (does specific things) → workflows/create-new-skill.md **Working with existing skills:** - Audit, review, check → workflows/audit-skill.md - Verify content is current → workflows/verify-skill.md - Add workflow → workflows/add-workflow.md - Add reference → workflows/add-reference.md - Add template → workflows/add-template.md - Add script → workflows/add-script.md - Upgrade to router pattern → workflows/upgrade-to-router.md **Need help deciding:** - General guidance → workflows/get-guidance.md **If user intent is unclear, ask minimal clarifying questions:** - "Create a MIDI skill" → "Task-execution skill (does MIDI tasks) or domain expertise (complete MIDI knowledge base)?" - "Work on my skill" → "Which skill? What do you want to do with it?" - Ask one clarifying question round at a time, then wait for the user's actual response before asking another. - Never fabricate or simulate user responses while clarifying (for example, fake `[User]` markers or imagined answers). Then proceed directly to the workflow. </routing> <quick_reference> ## Skill Structure Quick Reference **Skill directories:** - Global: `~/.agents/skills/{skill-name}/` - Project-local: `.agents/skills/{skill-name}/` **Simple skill (single file):** ```yaml --- name: skill-name description: What it does and when to use it. --- <objective>What this skill does</objective> <quick_start>Immediate actionable guidance</quick_start> <process>Step-by-step procedure</process> <success_criteria>How to know it worked</success_criteria> ``` **Complex skill (router pattern):** ``` SKILL.md: <essential_principles> - Always applies <intake> - Question to ask <routing> - Maps answers to workflows workflows/: <required_reading> - Which refs to load <process> - Steps <success_criteria> - Done when... references/: Domain knowledge, patterns, examples templates/: Output structures Claude copies and fills (plans, specs, configs, documents) scripts/: Executable code Claude runs as-is (deploy, setup, API calls, data processing) ``` </quick_reference> <reference_index> ## Domain Knowledge All in `references/`: **Structure:** recommended-structure.md, skill-structure.md **Principles:** core-principles.md, be-clear-and-direct.md, use-xml-tags.md **Patterns:** common-patterns.md, workflows-and-validation.md **Assets:** using-templates.md, using-scripts.md **Advanced:** executable-code.md, api-security.md, iteration-and-testing.md **GSD-specific:** gsd-skill-ecosystem.md </reference_index> <workflows_index> ## Workflows All in `workflows/`: | Workflow | Purpose | |----------|---------| | create-new-skill.md | Build a task-execution skill from scratch | | audit-skill.md | Analyze skill against best practices | | verify-skill.md | Check if content is still accurate | | add-workflow.md | Add a workflow to existing skill | | add-reference.md | Add a reference to existing skill | | add-template.md | Add a template to existing skill | | add-script.md | Add a script to existing skill | | upgrade-to-router.md | Convert simple skill to router pattern | | get-guidance.md | Help decide what kind of skill to build | </workflows_index> <yaml_requirements> ## YAML Frontmatter Required fields: ```yaml --- name: skill-name # lowercase-with-hyphens, matches directory description: ... # What it does AND when to use it (third person) --- ``` Name conventions: `create-*`, `manage-*`, `setup-*`, `generate-*`, `build-*` </yaml_requirements> <success_criteria> A well-structured skill: - Has valid YAML frontmatter - Uses pure XML structure (no markdown headings in body) - Has essential principles inline in SKILL.md - Routes directly to appropriate workflows based on user intent - Keeps SKILL.md under 500 lines - Asks minimal clarifying questions only when truly needed - Has been tested with real usage </success_criteria>