| name | Skill Builder |
| description | Create new Claude Code Skills with proper YAML frontmatter, progressive disclosure structure, and complete directory organisation. Use when you need to build custom skills for specific workflows, generate skill templates, or understand the Claude Skills specification. |
Skill Builder
When To Use
Use this skill when you need to:
- Create a new Claude Code Skill from scratch
- Understand the Claude Skills specification and structure
- Generate a skill directory layout and starter
SKILL.md
- Audit an existing skill for spec compliance
When NOT to use:
- Using an existing skill — invoke it directly; this skill only creates new ones
- Validating existing docs — use the docs-alignment skill
- Scaffolding from a PRD — use the prd2build skill
- General code generation without skill packaging — write code directly
Quick Start
mkdir -p ~/.claude/skills/my-skill
mkdir -p .claude/skills/my-skill
cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF'
---
name: "My Skill"
description: "What this skill does. Use when [trigger conditions]."
---
[Brief description]
[Single most common usage]
[Core instructions]
EOF
Required: YAML Frontmatter
Every SKILL.md must open with YAML frontmatter containing exactly two fields:
---
name: "Skill Name"
description: "What it does and when to use it."
---
name: human-friendly display name, max 64 characters.
description: must answer both what (functionality) and when (trigger conditions). Front-load keywords — this text is loaded into Claude's system prompt for autonomous matching. Max 1024 characters.
description: "Generate OpenAPI 3.0 docs from Express.js routes. Use when creating API docs, documenting endpoints, or building API specifications."
description: "A comprehensive guide to API documentation."
No other frontmatter fields are recognised by the Claude runtime.
Directory Layout
~/.claude/skills/my-skill/ # MUST sit directly here — no deeper nesting
SKILL.md # REQUIRED entry point
REFERENCE.md # Optional: full spec and field details
EXAMPLES.md # Optional: templates and worked examples
eval-suite-template.md # Optional: eval/validation stubs
scripts/ # Optional: executable scripts
resources/ # Optional: templates, schemas, examples
docs/ # Optional: ADVANCED.md, TROUBLESHOOTING.md
The skill directory must be placed directly under ~/.claude/skills/ or .claude/skills/. Subdirectories within the skill are fully supported.
Progressive Disclosure
Claude loads skill content in three levels:
| Level | Content | When loaded |
|---|
| 1 | name + description frontmatter | Always (all skills, minimal context) |
| 2 | SKILL.md body | Only when this skill is active |
| 3 | Linked sibling files (REFERENCE.md, EXAMPLES.md, etc.) | On demand as Claude navigates |
Target sizes: SKILL.md body 2–5 KB. Move lengthy spec details, all templates, and long examples into sibling files linked from here.
Recommended SKILL.md Structure
---
name: "..."
description: "..."
---
# Skill Name
## When To Use
[2-3 sentences. When yes, when no.]
## Prerequisites
[Only if non-obvious]
## Quick Start
[Single bash block covering the 80% case]
## Step-by-Step Guide
[Core instructions]
## Advanced / Reference
See [REFERENCE.md](REFERENCE.md) for full spec details.
See [EXAMPLES.md](EXAMPLES.md) for templates and worked examples.
Validation Checklist
Before publishing a skill:
For eval/validation methodology, see eval-suite-template.md.
Diagram-Driven Diagnosis
Complex multi-function bug or suspected parallel implementations in a skill under construction? Use this method.
Use when: a bug or design defect spans many functions or modules; you suspect duplicate or parallel implementations of the same concern (multiple writers, divergent validators, shadow copies of an algorithm); or symptom-chasing is not converging on root cause.
Phase 1 — Cartography
Spawn N Sonnet agents, one per concern. Each agent renders its slice of the system as a renderable Mermaid sequence or flow diagram built from the actual code, not from docs. Concerns are domain-specific — for example: settings flow, data population and socket handoff, interaction events, update and backoff logic, data types, GPU physics, analysis/clustering.
Each agent maps all code paths into its diagram and explicitly flags any parallel or duplicate implementation it finds.
Phase 2 — Queen Synthesis
One Opus coordinator collates the diagrams into a single ranked anomaly register (e.g. 00-anomaly-register.md) containing:
- a Mermaid mindmap of anomaly themes
- a revert-vs-reconcile table for each duplication
- git archaeology identifying the commit that introduced each divergence
Phase 3 — QE Fleet
Brief QE agents to write failing repro tests that depend only on the model/pure layer (no GPU, no network) to prove each anomaly objectively before any fix is attempted. This converts "I suspect X" into a red test.
Phase 4 — Fix with Live Diagrams
Implement fixes (deleting or deprecating parallel paths where they are not integrated), updating each Mermaid diagram as you go so resolutions visibly click into place. The red repro tests flip green as proof.
Why it works: forcing every parallel implementation into one visible artefact makes divergent authorities obvious — for example, one layer reads metadata.type while another reads a top-level type field. Failing repro tests prevent symptom-chasing and premature hacks.
Reference and Examples
