Skill Builder

Create and maintain Claude Code skills following Anthropic's best practices.

Sub-Commands

Before Any Sub-Command

Required reading (load these before proceeding):

1. •Read references/anthropic-guidelines.md - Official best practices
2. •Scan .claude/skills/ - Know what exists, avoid duplicates
3. •Validate reference material: Before major builds based on skill reference files, verify versions and patterns against current documentation. Pre-build research prevents rework.

/skill-builder create

When to Use

• •User says "create a skill for X" or "make a slash command"
• •A workflow is repeated 3+ times and should be codified
• •Domain knowledge needs capturing for reuse

Step 1: Validate

Check if it should be a skill:

Score timelessness (print this table):

Reject if <4. Revise if 4-6. Proceed if 7+.

Step 2: Design

Choose pattern:

Size targets:

• •Description: ≤200 chars, includes "Use when..." triggers
• •SKILL.md body: ≤500 lines / ~1,500 words
• •If larger → extract to references/

Reference File Structure

If skill needs references/, propose a split before creating:

Proposed Reference Structure
============================
references/
├── patterns.md     # Used by: create, review (core patterns)
├── examples.md     # Used by: create only (code examples)

Rationale:
- patterns.md: Shared across most sub-commands
- examples.md: Only needed when creating new code

Approve? [Yes / Modify: ___]

Sizing rules:

• •<100 lines → fine as-is
• •100-300 lines → add table of contents
• •300-500 lines → consider split if clear domain boundary exists
• •500+ lines → must split; aim for balanced halves (300-400 lines each)

Splitting criteria: Group by shared context, not by sub-command:

• •Ask "which sub-commands need this content?"
• •If all need it → keep together
• •If 2-3 need it → create shared reference file
• •If only one needs it → inline in that sub-command or create narrow reference

Step 3: Write

mkdir -p .claude/skills/{name}
# Add references/ only if needed

Use template from references/templates.md

Required elements:

1. •Frontmatter with name + description (include trigger phrases)
2. •Sub-commands table (if applicable)
3. •"Before Any Sub-Command" section with explicit file reads
4. •Clear steps per sub-command
5. •Verifiable checklist

Step 4: Validate & Update

• • Description includes 3+ trigger phrases ("Use when...")
• • All file paths exist and are correct
• • No placeholders remain
• • Under size limits
• • Reference files sized correctly (<100 lines, or has TOC, or split)
• • All references link directly from SKILL.md (no nested refs)
• • CLAUDE.md skill table updated (with sub-commands)
• • Consider independent audit: spawn general-purpose agent to review (finds different issues than self-audit)

/skill-builder improve

When to Use

• •Skill has gaps, missing patterns, or unclear instructions
• •File references are broken or outdated
• •Skill exceeds size limits
• •Skill predates current standards and needs modernization

Step 1: Determine Mode

Ask: "What kind of improvement?"

Step 2: Full Modernization Checklist

Run through the full create checklist against the existing skill:

Structure:

• • Description has 3+ trigger phrases ("Use when...")
• • "Before Any Sub-Command" section exists with explicit reads
• • Each sub-command has: When to Use, Steps, Checklist
• • No placeholders remain
• • CLAUDE.md skill table is current

Sizing:

• • SKILL.md ≤500 lines — if over, propose reference split (use same format as create)
• • Reference files <100 lines or have TOC
• • All references one level deep (no nested refs)

Content quality:

• • Examples are generic and portable (no project-specific imports)
• • Code samples are correct and current
• • Anti-patterns shown use // ❌ and correct patterns use // ✓

Propose comprehensive update for approval before applying.

Step 3: Targeted Fix

Ask: "What behavior have you observed?"

• •Does it trigger when expected?
• •Which sections get used/ignored?
• •Any unexpected paths?

1. •Read the skill: .claude/skills/{name}/SKILL.md
2. •Read .claude/reflections/index.md (if exists) for relevant principles
3. •Identify specific gaps (don't rewrite everything)
4. •Make targeted edits - change only what's needed
5. •Re-score timelessness if scope changed significantly
6. •Verify reference file sizes - If any >100 lines without TOC, fix
7. •Update CLAUDE.md if description or sub-commands changed

/skill-builder audit

When to Use

• •Periodic health check (monthly)
• •After major codebase changes
• •Before committing skill updates

Steps

1. •

   List skills: ls .claude/skills/

2. •

   Check each skill:

   Check	Pass Criteria
   Frontmatter	Has name + description
   Triggers	Description includes "Use when..."
   Size	≤500 lines or uses references/
   File refs	All paths exist
   Placeholders	None remain
   Portability	No project-specific paths; uses "(if exists)" for optional files
   Read format	Uses Read or Scan verb (bold), not "See" or "Check"
   No duplication	Content in SKILL.md OR references, not both
   Internal consistency	Checklists match the patterns/recommendations taught

3. •

   Check CLAUDE.md alignment:

   • •All skills listed in table?
   • •Sub-commands documented?
4. •

   Output report:

   code

   Skill Audit Report
   ==================
   ✓ finalize: All checks pass
   ✗ reflect: Missing from CLAUDE.md
   
   Actions needed:
   1. Add reflect to CLAUDE.md skill table
   

/skill-builder upgrade

When to Use

• •Monthly maintenance
• •When Claude releases new skill features
• •When Anthropic publishes new best practices

Steps

1. •

   Fetch latest docs:

   • •WebSearch: "Claude Code skills best practices"
   • •WebFetch: https://docs.anthropic.com/en/docs/claude-code/skills
2. •

   Compare with references/anthropic-guidelines.md

3. •

   Propose updates (require approval):

   code

   Proposed Updates
   ================
   1. references/anthropic-guidelines.md
      - Add: [new pattern]
      - Update: [changed guideline]
   
   Sources: [URLs]
   
   Approve? [Yes/No]
   

4. •

   Apply approved changes

Reference Files

• •Anthropic guidelines: references/anthropic-guidelines.md
• •Templates: references/templates.md
• •Existing skills: .claude/skills/*/SKILL.md