SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsskill-builder

skill-builder

Coding & development

View repository

Updated 10-16 09:33

About this skill

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.