---
name: skill-builder
trigger: /skill-builder
description: >
  Create well-structured Claude Code skills with proper YAML frontmatter,
  progressive disclosure architecture, completion criteria, and a self-
  improvement section. Use when building a new custom skill or auditing an
  existing one for quality. NOT for editing an existing skill's behavior
  (edit that skill's own SKILL.md directly) or for one-off scripts that
  don't need to persist as a skill.
user_invocable: true
---

> **Public / shared version** — trimmed from a private Claude Code setup and
> posted at smereski.com as a reusable pattern.

# skill-builder — Claude Code skill authoring guide

Creates production-ready Claude Code skills with proper YAML frontmatter,
progressive disclosure architecture, and complete file/folder structure.

## What a skill is

A Claude Code skill is a directory under `~/.claude/skills/<name>/` (personal)
or `<project-root>/.claude/skills/<name>/` (project-scoped), containing a
`SKILL.md` file with YAML frontmatter. Claude loads the frontmatter for all
skills at startup and reads the full body only when the skill is triggered.

## Quick start

```bash
# Create the skill directory (must be top-level, not nested)
mkdir -p ~/.claude/skills/my-skill

# Create the SKILL.md
cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: >
  Brief description of what this skill does and when to use it.
  Include both "what" and "when" — max 1024 characters.
user_invocable: true
---

# my-skill — subtitle

## What This Skill Does
[Main instructions]

## Quick Start
[Basic usage with a copy-pasteable example]
EOF
```

Restart Claude Code (or reload) to pick up the new skill.

## Canonical frontmatter

```yaml
---
name: skill-name           # REQUIRED. Max 64 chars. Matches directory name.
trigger: /skill-name       # Optional. Slash command that fires this skill.
description: >             # REQUIRED. Max 1024 chars.
  What it does.            # Front-load trigger keywords.
  When Claude should invoke it. When NOT to invoke it.
user_invocable: true       # true if users can call it with /skill-name
---
```

Only `name` and `description` are used by the harness; all other fields are
advisory. Keep `name` lowercase-hyphenated and matching the directory name —
the harness lists skills by directory name.

## Directory structure

```
~/.claude/skills/
└── my-skill/                 # top-level ONLY — no nested subdirectories
    ├── SKILL.md              # REQUIRED: main skill file
    ├── references/           # optional: deep reference docs
    │   ├── advanced.md
    │   └── troubleshooting.md
    ├── scripts/              # optional: executable scripts
    │   ├── setup.sh
    │   └── validate.py
    └── resources/            # optional: templates, schemas, examples
        └── templates/
```

Skills must be directly under `~/.claude/skills/[skill-name]/`. Claude Code
does NOT support nested subdirectories or namespaces.

## Progressive disclosure (3 levels)

| Level | What loads | When |
|-------|-----------|------|
| 1 — Metadata | `name` + `description` (~200 chars) | Always, at startup for ALL skills |
| 2 — SKILL.md body | Main instructions (~1-10KB) | Only when the skill is active |
| 3 — Referenced files | `references/`, `resources/` | On demand as Claude navigates |

Keep the SKILL.md body focused on the most-used path. Push depth to
`references/` files — Claude loads them only when it navigates there. This
lets you install 100+ skills with minimal context penalty.

## Required content checklist

Every SKILL.md must include:

1. **When to use AND when NOT to use** — guard against being invoked in the
   wrong context.
2. **Copy-pasteable commands** with concrete examples (not "run the
   appropriate script").
3. **A verifier per action** + an explicit "done means X" line — Claude must
   be able to confirm completion without self-certifying.
4. **Ambiguity line** — "If the target/goal is unclear, STOP and ask — do
   not guess, do not create files."
5. **Never-do list** — name destructive edges explicitly; cite tool-level
   hooks where they exist.
6. **Stop conditions** — retry caps, polling limits, hand-back-to-user
   triggers.
7. **At least one worked example** — situation → correct action.
8. **Known gotchas** — documented friction points.

## Failure modes to avoid

| Failure | What it looks like | Fix |
|---------|--------------------|-----|
| Premature completion | Skill marks done before verifier passes | Add explicit "done means" + a checkable artifact |
| Prompt sediment | Instructions accumulate over edits until contradictory | Rewrite from scratch; keep < 500 lines |
| Scope sprawl | Skill tries to do everything | Split into smaller, focused skills |
| Duplication | Two skills do the same thing with different names | Merge or make one a thin wrapper |
| Vague commands | "run the right script" with no path | Replace with exact, copy-pasteable commands |
| Self-certification | "looks good" as a gate | Require a screenshot, a test pass, or a `ls` check |

## Writing the description (frontmatter)

The description is what Claude uses to decide whether to invoke the skill.
Front-load the trigger keywords.

Good:
```yaml
description: >
  Generate OpenAPI 3.0 documentation from Express.js route files. Use when
  creating API docs, documenting endpoints, or building API specifications.
  NOT for generating client SDKs or mocking servers.
```

Bad:
```yaml
description: "A comprehensive guide to API documentation"  # no "when" clause
description: "Documentation tool"                          # too vague
```

## File size guidelines

- SKILL.md: aim for 200-500 lines, hard max ~800 lines.
- Push detail to `references/*.md` files — load them on demand.
- Scripts in `scripts/` should do one thing and be independently runnable.

## Validation (runnable)

```bash
python -c "
import re, sys
t = open(sys.argv[1], encoding='utf-8').read()
m = re.match(r'^---\s*\n(.*?)\n---\s*\n', t, re.S)
if not m: sys.exit('FAIL: no frontmatter')
fm = m.group(1)
if 'name:' not in fm or 'description:' not in fm:
    sys.exit('FAIL: missing name or description')
print('OK')
" ~/.claude/skills/<name>/SKILL.md
```

## Worked example

Situation: "Build a skill that generates SQL migration files from a schema diff."

1. Create `~/.claude/skills/sql-migrate/SKILL.md`.
2. Frontmatter: `name: sql-migrate`, description covers "what" (generate SQL
   migrations from schema diffs) and "when" (use when diffing two schema
   files or adding a column).
3. Body: Quick Start → copy-pasteable command, Step-by-Step → full procedure
   with verifier per step, Gotchas → known edge cases.
4. Verify frontmatter with the Python snippet above.
5. Test: trigger `/sql-migrate` in a session, confirm Claude reads the skill
   and follows the instructions.

## Self-improvement section (template)

Include at the bottom of each SKILL.md you build:

```markdown
## Self-improvement

Each real use that hits friction (a gotcha, a missing verifier, a scope
question) should update this SKILL.md before the session ends. Propose the
edit; do not write it without review if vault-protection hooks are active.
```

## Resources

- [Anthropic Agent Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code)