skill-builder — Skills That Don't Rot

Takes a plain-language description of a task and produces a ready-to-ship agent skill. The design goal is skills that are cheap in ambient context and current with the skill spec — most skill generators fail on exactly those two axes: they don't know about arguments/argument-hint, never suggest disable-model-invocation, and write bloated descriptions that tax every session.

Modes

Parse $ARGUMENTS for a mode; default to new when the input is a description.

• new <description> — scaffold a skill from scratch (the flow below).
• review <path> — audit an existing SKILL.md against steps 1–3's decision points and run the validator (step 4). Report findings; don't rewrite unless asked.
• migrate <path> — convert a legacy .claude/commands/*.md file into a skill directory: carry the frontmatter over, apply the review checklist, and place supporting content in the directory.

Before You Start

Read references/claude-code-frontmatter.md — a pinned, dated snapshot of the skill frontmatter spec, argument substitutions, and context-loading behavior.

Staleness policy: if the snapshot date is more than 3 months old, warn the user and continue with the pinned snapshot. Do not re-fetch or modify the reference mid-generation — updating the spec is a maintenance operation (agent-skill-builder's spec-drift CI watches for it), not a side effect of building a skill. Only update the snapshot when the user explicitly asks.

Also read the host repo's CLAUDE.md and existing skills — avoid duplicating a skill that already exists, and match local conventions.

Instructions

1. Clarify the skill

Ask (or infer from context):

• Target runtime: Claude Code (default — full frontmatter feature set) or the portable Agent Skills core (name + description only; keep Claude-specific fields out or document them as optional extensions).
• Name: lowercase, hyphenated. In Claude Code the directory name under .claude/skills/ is the command you type; frontmatter name is only a display label.
• Who invokes it — the most important design decision:
  • User-only (side effects, or timing the user controls: publish, send, deploy, log) → disable-model-invocation: true. Bonus: the description is then not loaded into every session — zero ambient context cost.
  • Claude-only (background knowledge, not an action) → user-invocable: false.
  • Both (default) → the description must carry the trigger keywords, and it becomes a permanent per-session context cost. Make it earn that.
• Arguments: does the user pass input on the command line? If yes: set argument-hint, and consume $ARGUMENTS (or $0/$1, or named arguments:) in the body. Don't make the model guess what the trailing text means.
• Input/Output: what does it read (files, MCP data, live command output), what does it produce?
• Tools: allowed-tools is a pre-approval grant (no permission prompts while active), not a restriction — scope entries tightly, e.g. Bash(git add *) not Bash. Use disallowed-tools to actually remove tools.
• Where it runs: inline (default — shares conversation context) or context: fork + agent: for isolated, self-contained tasks. Fork only works when the body is an explicit task, not reference guidelines.
• Data at load time: use dynamic context injection (!`command` at line start) to inline live data (a diff, a status file) before the model reads the skill.
• Only set model/effort overrides with a specific reason. Use paths: for skills scoped to certain files.

2. Write the description — the context-budget step

• 1–2 sentences, key use case first, third person, containing the words the user would actually say. Target ~250 chars; the listing truncates at 1,536.
• Detail, steps, and edge cases go in the body — the body loads only on invocation, so it's nearly free until used. Never pad the description to be "thorough"; that's the anti-pattern that bloats every session.
• If disable-model-invocation: true, the model never sees the description — write it for the human scanning the / menu, and keep it short.

3. Draft the SKILL.md

Frontmatter template — include only the fields this skill needs (all are optional; see the reference for the full table):

---
name: [skill-name]
description: [1-2 sentences, triggers first]
argument-hint: "[expected args, e.g. [issue-number] [format]]"   # only if it takes arguments
disable-model-invocation: true    # only for user-triggered workflows
allowed-tools: [tightly-scoped grants]   # only if prompts would be annoying
---

Body structure: short purpose line, "When to Use" bullets, numbered step-by-step instructions, explicit output format.

Quality checklist:

• Steps, not paragraph prose; each step names the tool or command
• Output format defined, not left ambiguous
• Instructions written as standing rules — skill content stays in context for the rest of the session, so "do X once" phrasing goes stale; "always X when Y" doesn't
• Body under 500 lines; long reference material moved to supporting files in the skill directory, linked from SKILL.md
• No hardcoded IDs, paths, or credentials — use config files, env vars, or ${CLAUDE_SKILL_DIR} for bundled scripts
• Confirmation gate on anything that changes external state (git push, API calls, file deletes)

4. Validate

If agent-skill-builder is available locally, run its validator against the generated skill directory:

python3 <agent-skill-builder>/scripts/validate_skill.py <path-to-skill-dir>

It machine-checks what the checklist above describes: frontmatter parses, unknown keys, description budget, $ARGUMENTS/argument-hint pairing, unscoped Bash grants, side-effect commands on model-invocable skills, broken relative links, missing referenced files, body length. Report its output verbatim (PASS/FAIL plus warnings) as part of your deliverable. If Python isn't available, walk the checklist manually and say so.

5. Install it

Before writing anything, check the target path is clear. If <install-dir>/<skill-name>/SKILL.md already exists, stop and show the user the existing file — a skill with that name is already installed. Confirm an overwrite or pick a different name; never clobber an existing SKILL.md silently. (review mode is the right tool for improving one that already exists.)

For Claude Code: .claude/skills/<skill-name>/SKILL.md is the whole installation — the directory name becomes the command, supporting files live alongside, and changes hot-reload within a session. No routing stub or registry edit is needed. (.claude/commands/ files still work, but they're the legacy form — that's what migrate mode is for.)

Then follow whatever conventions the host repo has: a changelog entry, a command table in CLAUDE.md, a routing doc. Check before assuming none exist.

6. Test before shipping

• Confirm it's listed: ask What skills are available? (or check /skills).
• Invoke it directly (/name with realistic arguments) and check the output matches the spec.
• If model-invocable: in a fresh session, phrase a matching request naturally and confirm it triggers — then phrase a near-miss and confirm it stays quiet. Leftover authoring context masks trigger gaps, so fresh session matters.
• For skills worth hardening, offer the official eval loop: /plugin install skill-creator@claude-plugins-official runs with/without-skill benchmarks and description tuning. (That plugin evaluates output quality; this skill designs and validates structure — they compose.)

7. Present for review

Show the SKILL.md, the validator output, and any wiring changes in labeled fenced code blocks. Ask: "Want me to save these, or make any changes first?"

Tips for Good Skills

• Be specific over flexible. A skill that does one thing well beats one that tries to handle every edge case.
• Spend context deliberately. Every model-invocable description is loaded into every session. The body is free until invoked. Put things on the right side of that line.
• Gate destructive actions. Anything that changes external state should require explicit approval — and consider disable-model-invocation: true so the model can't decide to run it because the code "looks ready."
• Reference, don't duplicate. If a skill needs data from a file, read the file — don't copy its contents into the skill.