Skill Builder

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: Step-by-Step Process Why this matters: Claude follows instructions literally. Vague steps produce vague results. Specific steps produce consistent output every time.

• 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 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 -- 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). 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. 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 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: Deploy, Backup & Register in Installer

All skills are backed up to the central skill repository and deployed to their target project.

Backup location (always): ~/workspace/x85446/claudecodetricks/skills/[skill-name]/ This is the canonical copy. The installer script deploys from here.

Deploy location: The target project's .claude/skills/ directory. Ask the user which project to deploy to using AskUserQuestion. There is no default -- the user must specify.

Known deploy targets (for reference):

Then:

1. Write the skill files (SKILL.md + any supporting files) to the backup location first: ~/workspace/x85446/claudecodetricks/skills/[skill-name]/
2. Copy the same files to the deploy location: [deploy-path]/.claude/skills/[skill-name]/
3. Register in the installer — add a case entry to ~/workspace/x85446/claudecodetricks/skills/skillinstall.sh:

# In the do_install() function, add:
<skill-name>)  install_skill <skill-name> "$TARGET_VAR" ;;

Where $TARGET_VAR is one of the predefined deploy target variables at the top of skillinstall.sh:

• $IMARKETING — Izuma Marketing
• $TAXES — Travis Taxes (Google Drive)
• $CCTRICKS — ClaudeCodeTricks finance pipeline

If the deploy target doesn't have a variable yet, add one to the "Deploy targets" section of skillinstall.sh.

4. Confirm all three steps succeeded (backup, deploy, installer registration).

If the user declines a location (skips deploy), still write to backup and register in the installer.

Step 6: Document in CLAUDE.md

Your project's CLAUDE.md file is where Claude loads project-wide instructions every conversation. After creating a skill, add a brief entry so you (and your team) know what's available:

• Skill name and /slash-command
• Trigger phrases
• Brief description of what it does
• Output location (if it produces files)

This isn't required for the skill to work, but it keeps your project organized and helps Claude understand how skills fit into your broader workflow.

Step 7: Test

Test both invocation methods:

1. Natural language -- Say something matching the description. Does Claude load the skill?
   • If not, revise the description field to include the keywords you used
   • 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 you can use as a starting template:

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

---