Skill Builder

What This Skill Does

Guides the creation and optimization of Claude Code skills using official best practices from the Claude Code documentation. 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.

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

• 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

• 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: Step-by-Step Process

• Walk me through exactly what should happen from trigger to output. What's step 1? Step 2? Keep going.
• 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

• 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

• 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 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 of ours) give step-by-step instructions for a specific action. Invoked with /name or natural language.
• Reference skills add knowledge Claude applies to current work. Conventions, patterns, style guides.

Step 2: Configure frontmatter

Set these fields based on what you learned in discovery:

• name -- Matches the directory name.
• description -- Written as: "Use when someone asks to [action], [action], or [action]." Include natural keywords from the trigger phrases.
• disable-model-invocation: true -- Set if the skill has side effects (file generation, API calls, costs money).
• argument-hint -- Set if the skill accepts arguments.
• 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.

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, brand assets, agent prompts
2. Step-by-step workflow -- Numbered steps. Each step tells Claude exactly what to do.
3. Output format -- What the result looks like. Include templates, file paths, structured formats.
4. Notes -- Edge cases, constraints, what to delegate, what NOT to do.

Content rules:

• Keep SKILL.md under 500 lines. Move detailed reference 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)

my-skill/
 SKILL.md           # Main instructions (required, <500 lines)
 reference.md       # Detailed docs (loaded when needed)
 examples/
   sample.md        # Example output
 scripts/
   helper.py        # Utility script

Reference these from SKILL.md so Claude knows they exist and when to load them.

Step 5: Register in CLAUDE.md

1. Add to Active Skills section with: name, trigger command, trigger phrases, description, agents used, output location.
2. Log the decision in decisions/log.md.

Step 6: Test

1. Natural language -- Say something matching the description. Check if Claude loads it.
2. Direct invocation -- Run /skill-name with test arguments.

If issues arise, see Troubleshooting in reference.md.

Mode 2: Audit an Existing Skill

Use this checklist to audit any existing skill. Fix issues before marking the audit complete.

Frontmatter Audit

• name matches the directory name
• description uses natural keywords someone would actually say when they need this skill
• 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 (generates files, calls APIs, sends messages, costs money)
• argument-hint is set if the skill accepts arguments via /name
• 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
• model is set if a specific model capability is needed
• No unnecessary fields are set (don't add frontmatter just because you can)

Content Audit

• Total SKILL.md is under 500 lines (detailed reference in supporting files)
• Clear step-by-step workflow with numbered steps (for task skills)
• Output format is specified with templates or examples
• All file paths and locations are documented
• Agent delegation instructions include the actual prompt text to send
• Notes section covers edge cases, constraints, and what NOT to do
• No vague instructions -- every step tells Claude exactly what to do
• String substitutions ($ARGUMENTS, $N) are used where the skill takes input

Integration Audit

• Skill is registered in CLAUDE.md under Active Skills
• Creation was logged in decisions/log.md
• Supporting files (if any) are referenced from SKILL.md, not orphaned
• Scripts (if any) have correct file paths and are executable
• API keys (if any) are read from .env with placeholders documented

Quality Audit

• A complete beginner (to Claude Code, not necessarily to the topic) could follow the instructions
• Instructions are actionable, not abstract
• Delegates to subagents when appropriate to keep main context clean
• Doesn't duplicate information that lives elsewhere (CLAUDE.md, other skills)
• Output paths follow project conventions (projects/[skill-name]/)

Optimization Opportunities

After running the audit, evaluate whether the skill would benefit from:

• context: fork -- If it produces verbose output or is fully self-contained
• allowed-tools -- If it only needs read access or specific tools
• Supporting files -- If SKILL.md is over 300 lines, move reference material out
• Dynamic context injection -- If the skill needs live data (git status, API responses, file listings) injected before Claude sees the content
• Hooks -- If the skill needs pre/post validation on tool usage
• argument-hint -- If users would benefit from autocomplete guidance

Our Project Conventions

Skills in this project follow these conventions:

• Skills live in .claude/skills/[skill-name]/SKILL.md
• Agents live in .claude/agents/[agent-name].md
• Output files go in projects/[skill-name]/
• API keys are read from .env (never ask Nate for keys)
• Scripts go in scripts/[skill-name]/
• Brand assets are in brand-assets/
• Reference material is in references/
• All skills are registered in CLAUDE.md under Active Skills
• All creation decisions are logged in decisions/log.md
• Frontmatter description field is written as: "Use when someone asks to [action], [action], or [action]."

Important Notes

• Always read the existing skill before optimizing it. Never propose changes to code you haven't read.
• When building a new skill, check if a similar skill already exists that could be extended instead.
• Skills and agents work together in two directions: skills can run inside agents (context: fork + agent), and agents can preload skills (skills field in agent frontmatter). Choose the right direction based on who controls the system prompt.
• Skill descriptions are loaded into context. If there are many skills, they may exceed the character budget (2% of context window, fallback 16,000 chars). Keep descriptions concise.
• The / menu only shows skills where user-invocable is not false. Use user-invocable: false for background knowledge skills.
• disable-model-invocation: true is the strongest restriction -- it removes the skill from Claude's context entirely and prevents programmatic invocation via the Skill tool.