/build-skill

Build Skill Command

Create a new Claude Code skill with proper structure and best practices.

Workflow

1. Invoke skill-builder reference for current patterns:

   • Read skills/claude-code-meta/references/skill-builder.md
   • Get: anatomy, frontmatter requirements, progressive disclosure patterns

2. Extract requirements from context:

   • What should the skill do?
   • What tools/resources does it need?
   • What's the expected size/complexity?

3. Plan structure:

   • Determine if scripts/, references/, or assets/ needed
   • Plan progressive disclosure (SKILL.md vs references/)
   • Keep SKILL.md under 500 lines

4. Create skill directory:

   mkdir -p plugins/<plugin-name>/skills/<skill-name>
   

5. Write SKILL.md:

   ---
   name: skill-name
   description: >
     {One-sentence WHAT}
   
     USE THIS SKILL WHEN:
     - {scenario 1}
     - {scenario 2}
   
     TRIGGERS ON: "{keyword1}", "{keyword2}"
   
     NOT FOR: {anti-patterns}
   ---
   
   # Skill Name
   
   [Content following skill-builder patterns]
   

6. Create bundled resources (if needed):

   • scripts/ - executable code
   • references/ - deep-dive docs (progressive disclosure)
   • assets/ - templates, data files

7. Validate:

   • SKILL.md has valid frontmatter
   • Description uses USE WHEN / TRIGGERS ON pattern
   • SKILL.md under 500 lines (or uses references/)
   • No external hardcoded paths

8. Return:

   • Skill directory path
   • Structure created
   • Validation results

Criteria

Description Quality:

• Concrete USE WHEN scenarios (not "ALWAYS ACTIVE")
• Specific TRIGGERS ON keywords
• Clear NOT FOR anti-patterns
• Under 1024 chars

Structure:

• SKILL.md is the entry point
• Progressive disclosure: heavy content → references/
• Scripts are executable and documented

Best Practices (from skill-builder reference):

• Concise over comprehensive
• Set appropriate degrees of freedom
• Use grep patterns for reference discovery
• Cross-link related skills

See Also

• Full patterns: skills/claude-code-meta/references/skill-builder.md
• Testing: skills/claude-code-meta/references/command-testing.md