skill-builder

What This Skill Does

Guides the creation and optimization of Claude Code skills using official best practices. Use this whenever:

• Building a new skill from scratch
• Optimizing or auditing an existing skill
• Deciding on advanced features (subagent execution, hooks, dynamic context, etc.)
• Troubleshooting a skill that isn't working correctly

For the complete technical reference on all frontmatter fields, advanced patterns, and troubleshooting, see reference.md.

Quick Start: What Is a Skill?

A skill is a reusable set of instructions that tells Claude Code how to handle a specific task. Skills live in .claude/skills/[skill-name]/SKILL.md inside your project (or ~/.claude/skills/ for global skills). When you type /skill-name or describe what you need in natural language, Claude loads the skill's instructions and follows them.

Think of skills as SOPs for Claude. Instead of re-explaining a workflow every conversation, you write it once and invoke it forever.

How they work under the hood:

• Your project's CLAUDE.md instructions are always loaded, every conversation
• Skill descriptions (from frontmatter) are always loaded so Claude knows what's available
• The full skill content only loads when the skill is actually invoked
• Once loaded, Claude follows the skill's instructions while still respecting your CLAUDE.md rules

Mode 1: Build a New Skill

When building a new skill, run the Discovery Interview first. Do NOT start writing files until discovery is complete.

Discovery Interview

Ask questions using AskUserQuestion, one round at a time. Each round covers one topic. Move to the next round only after the user answers. Keep going until you're 95% confident you understand the skill well enough to build it without further clarification.

Round 1: Goal & Name Why this matters: A clear goal prevents scope creep. The name becomes the /slash-command, so it needs to be memorable and specific.

• What does this skill do? What problem does it solve or what workflow does it automate?
• What should we call it? (Suggest a name based on their answer -- lowercase, hyphens, max 64 chars)

Round 2: Trigger Why this matters: The description field is how Claude decides whether to load your skill. Bad trigger words mean Claude never uses it. Too broad means Claude fires it when you don't want it.

• What would someone say to trigger this? (Get 2-3 natural language phrases)
• Should it be user-only (/slash-command), Claude-auto-invocable, or both?
• Does it accept arguments? If so, what? (e.g., a topic, a URL, a file path)

Round 3: Process and Fragility Why this matters: Claude follows instructions literally, so specificity should match fragility. Where only one sequence is safe (destructive commands, deploys, output a parser reads), exact steps prevent mistakes. For judgment work, a hand-written script over-constrains the model and usually does worse than its own plan.

• What should happen from trigger to output? Which parts must happen in a fixed order, and which are judgment calls where the goal and a way to verify the result are enough?
• For each step: Does Claude do it directly, or delegate to a subagent/script?
• Does this need to be conversational (back-and-forth with the user) or is it a fire-and-forget task?

Round 4: Inputs, Outputs & Dependencies Why this matters: Skills that don't specify where to find inputs or where to put outputs produce inconsistent results. Nailing this down makes the skill reliable.

• What inputs does the skill need? (Files, API responses, user arguments, live data)
• What does it produce? (Files, text output, structured data) Where do outputs go?
• Does it need external APIs, scripts, or tools? Which ones?
• Does it need reference files, style guides, templates, or examples?

Round 5: Guardrails & Edge Cases Why this matters: Skills without guardrails can produce unexpected behavior -- wrong outputs, unnecessary API costs, or actions you didn't intend.

• What could go wrong? What are the common failure modes?
• What should this skill NOT do? Any hard boundaries?
• Are there cost concerns? (API calls, AI image generation, etc.)
• Any ordering or dependency constraints? (e.g., "must check X before doing Y")

Round 6: Confirmation Why this matters: Misunderstandings caught here save you from rebuilding the skill later.

After all rounds, summarize your understanding back to the user in this format:

## Skill Summary: [name]

**Goal:** [one sentence]
**Trigger:** `/name` + [natural language phrases]
**Arguments:** [what it accepts, or "none"]

**Process:**
1. [step]
2. [step]
...

**Inputs:** [what it reads/needs]
**Outputs:** [what it produces + where]
**Dependencies:** [APIs, scripts, agents, reference files]
**Guardrails:** [what can go wrong, what to avoid]

Ask: "Does this capture it? Anything to add or change?" Only proceed to building once the user confirms.

Skipping rounds: If the user provides enough context upfront (e.g., they describe the full workflow in their first message), skip rounds that are already answered. Don't re-ask what you already know.

Build Phase

Once discovery is complete, build the skill following these steps:

Step 1: Choose the skill type

• Task skills (most common) give step-by-step instructions for a specific action. Invoked with /name or natural language. Examples: generate a report, summarize a PR, deploy code.
• Reference skills add knowledge Claude applies to current work without performing an action. Examples: coding conventions, API patterns, style guides.

Step 2: Configure frontmatter

Set these fields based on what you learned in discovery:

• name -- Matches the directory name. Lowercase, hyphens, max 64 chars.
• description -- What the skill does and when to use it, named as categories of intent ("Use when ending or pausing a working session") rather than a list of example phrases.
• disable-model-invocation: true -- Set if the skill has side effects (file generation, API calls, costs money). Prevents Claude from auto-invoking.
• argument-hint -- Set if the skill accepts arguments. Shows in the / menu autocomplete.
• context: fork + agent -- Set if the skill is self-contained and doesn't need conversation history.
• model -- Set if a specific model capability is needed.
• allowed-tools -- Set if the skill should have restricted tool access.

Only set fields you actually need. Don't add frontmatter just because you can.

For the full field reference and invocation control matrix, see reference.md.

Step 3: Write the skill content

Structure task skills as:

1. Context -- Files to read, APIs to call, reference material to load
2. Workflow -- The goal, the constraints, and how to verify the result. Use exact numbered steps only where order or safety demands it (destructive commands, deploys, schema-matched output); state judgment steps as outcomes.
3. Output format -- What the result looks like. Include templates, file paths, structured formats.
4. Notes -- Edge cases and constraints, each with the reason behind it; what to delegate.

Content rules:

• Keep SKILL.md under 500 lines. Move detailed reference material to supporting files.
• Use $ARGUMENTS / $N for dynamic input from arguments.
• Use !command`` for dynamic context injection (preprocessing).
• Be specific about agent delegation -- include exact prompt text.
• Specify all file paths (inputs, outputs, scripts, references).

Step 4: Add supporting files (if needed)

If your skill needs detailed reference docs, examples, or scripts, add them alongside SKILL.md in the same directory. Reference them from SKILL.md so Claude knows they exist. Supporting files are NOT loaded automatically -- they load only when Claude needs them. See reference.md for the full pattern.

Step 5: Register in INDEX.md

After creating a skill, add it to ~/.claude/skills/INDEX.md (for global skills) or document it in the project's CLAUDE.md. Include:

• Skill name and invocation type (Auto + Manual, Manual only, Auto only)
• Whether it's forked
• Brief description

Step 6: Test

Test both invocation methods:

1. Natural language -- Say something matching the description. Does Claude load the skill?
   • If not, broaden the intent the description names; don't append the exact phrase you typed
   • Try 2-3 different phrasings to verify it triggers reliably
2. Direct invocation -- Run /skill-name with test arguments
   • Verify $ARGUMENTS / $N are substituting correctly
   • Check that outputs go where expected
3. Edge cases -- Try invoking with missing arguments, unusual input, or empty input
4. Character budget -- If you have many skills, run /context to confirm your skill's description is being loaded. If it's not, your total descriptions may exceed the budget (see reference.md for details).

If issues arise, see Troubleshooting in reference.md.

Complete Example

Here's a minimal but complete skill as a starting template:

File: .claude/skills/meeting-notes/SKILL.md

---
name: meeting-notes
description: Summarize raw meeting notes into structured minutes with decisions and action items. Use when the user shares meeting notes or asks for minutes.
argument-hint: [topic or date]
---

## Steps

1. Ask the user to paste their raw meeting notes (or provide a file path).
2. Extract: Attendees, Key decisions, Action items (who/what/deadline), Open questions.
3. Format using the template below.
4. If $ARGUMENTS is provided, use it as the meeting title.

## Output Template

# Meeting: [title]
**Date:** [date or "Not specified"]
**Attendees:** [list]

## Key Decisions
- [decision]

## Action Items
- [ ] [person]: [task] (due: [date or "TBD"])

## Open Questions
- [question]

Mode 2: Audit an Existing Skill

Use this checklist to audit any existing skill. Read the skill file first before running through the checklist.

Frontmatter Audit

• name matches the directory name
• description names what the skill does and the situations it applies to
• description is specific enough to avoid false triggers but broad enough to catch real requests
• disable-model-invocation: true is set if the skill has side effects
• argument-hint is set if the skill accepts arguments
• allowed-tools is set if the skill should NOT have access to all tools
• context: fork is used if the skill is self-contained and produces verbose output
• No unnecessary fields are set

Content Audit

• Total SKILL.md is under 500 lines (detailed reference moved to supporting files)
• Specificity matches fragility: exact steps for fixed-order or destructive operations, goals plus verification for judgment work
• Output format is specified with templates or examples
• All file paths and locations are documented
• Agent delegation instructions include the actual prompt text
• Every instruction is concrete about the outcome it wants, without scripting judgment calls
• String substitutions ($ARGUMENTS, $N) are used where the skill takes input
• No duplication with global rules or other skills

Integration Audit

• Skill is registered in INDEX.md (for global skills) or documented in CLAUDE.md
• Supporting files (if any) are referenced from SKILL.md, not orphaned
• API keys (if any) are stored in environment variables, never hardcoded

Quality Audit

• Carries what the model can't infer (paths, conventions, quality bar, reasons behind constraints) and skips general how-to it already knows
• Instructions are actionable, not abstract
• Delegates to subagents when appropriate to keep main context clean
• Output paths follow a predictable convention
• Emphasis (caps, MUST/NEVER/CRITICAL) is reserved for an instruction shown to be underweighted, and each prohibition states its reason

After auditing, check reference.md for advanced features that could improve the skill.

Important Notes

• Always read an existing skill before optimizing it. Never propose changes to a skill you haven't read.
• When building a new skill, check if a similar skill already exists that could be extended instead.
• For advanced patterns (subagent execution, hooks, permissions), see reference.md.