Skill builder

Skill Builder

Build structurally correct Claude Code skills by enforcing Anthropic's official skill guide patterns, rules, and validation checklist.

Important

• Take your time with each phase. Quality is more important than speed.
• Do not skip validation steps — every check matters.
• Read the referenced files in references/ before making decisions that depend on them. They contain the authoritative rules.
• Explain the why behind structural decisions so the user builds intuition, not just files.

Instructions

This skill runs a 4-phase workflow with exactly 2 pauses (Phase 1 and Phase 4). Phases 2 and 3 execute automatically.

---

Phase 1: Extract Intent (1 pause)

Determine which entry path applies:

Path A — From Conversation Context

If the user said "turn this into a skill" or similar, referring to work already done in the conversation:

1. Review the conversation history for: tools used, step sequence, corrections made, input/output formats, domain knowledge applied.
2. Synthesize a summary: "Here's what I extracted from our conversation: [summary]."
3. Pause for confirmation: "Does this capture it, or should I adjust?"

Path B — From Intent Argument

If the user provided $ARGUMENTS or described what they want:

1. Ask the 4 intent questions (one message, one pause):
   • What does the user want to accomplish with this skill?
   • What multi-step workflows does this require?
   • Which tools are needed (built-in like Read/Write/Bash/Grep/Glob, or MCP servers)?
   • What domain knowledge or best practices should be embedded?
2. Pause once for answers.

Path C — Idea Development

If the user wants to explore or develop a skill concept before committing to building it (e.g., "help me develop this idea", "I need a skill that can...", "what would this look like"):

1. Engage in structured collaboration:
   • Clarify the core problem the skill solves
   • Identify what makes it hard (domain knowledge, multi-step coordination, tool selection, etc.)
   • Propose the output format and key decisions
   • Surface design tensions and tradeoffs
2. Do NOT ask the 4 intent questions mechanically. Have a real conversation about the concept.
3. Pause as many times as needed — this path is collaborative, not a form.
4. Exit condition: When the user says "build it", "go ahead", "go for it", or equivalent approval, transition to Auto-Decisions below and proceed through Phases 2-4 automatically.

Auto-Decisions (after the pause)

After receiving confirmation (Path A) or answers (Path B):

1. Read reference files first. Before making any decisions, read references/patterns.md, references/frontmatter-rules.md, and references/description-craft.md. These inform the decisions below.
2. Make these decisions automatically. State each one clearly:

Use Case Category — Classify as one of:

• Document & Asset Creation: Skill produces files, reports, documentation, or structured output
• Workflow Automation: Skill orchestrates a multi-step process (build, deploy, test, etc.)
• MCP Enhancement: Skill teaches optimal workflows for connected MCP servers

State: "Category: [X] because [reason]."

Framing — Choose one:

• Problem-first: User describes a goal, skill orchestrates tools to achieve it. ("I need to set up a workspace")
• Tool-first: User has specific tools/MCPs, skill teaches optimal usage patterns. ("I have Notion MCP connected")

State: "Framing: [X] because [reason]."

Pattern — Choose from the 5 patterns (already read in step 1 above):

1. Sequential Workflow
2. Multi-MCP Coordination
3. Iterative Refinement
4. Context-Aware Tool Selection
5. Domain-Specific Intelligence

State: "Pattern: [X] because [reason]."

Location — Determine where to save:

• If the skill is project-specific (only useful in this repo): {project}/.claude/skills/{skill-name}/
• If the skill is general-purpose (useful across projects): ~/.claude/skills/{skill-name}/
• When in doubt, prefer global (~/.claude/skills/) — skills can always be moved later

State: "Location: [path]"

Invocability — Default to user_invocable: true unless the skill is clearly meant to be auto-triggered only.

Proceed immediately to Phase 2.

---

Phase 2: Build (0 pauses)

Construct the entire skill. Do not pause during this phase.

Step 1: Create Folder

• Name in kebab-case (no spaces, underscores, or capitals)
• Create the folder and references/ subdirectory if needed

Step 2: Generate Frontmatter

Consult references/frontmatter-rules.md (already read in Phase 1) for the complete rule set.

Required fields:

• name: kebab-case, must match folder name, no "claude" or "anthropic" in the name
• description: Craft using the formula from references/description-craft.md:
  • Structure: [What it does] + [When to use it] + [Key capabilities]
  • Under 1024 characters
  • No XML tags (< or >)
  • Include specific trigger phrases users would actually say
  • Include negative triggers if scope could be confused with another skill
  • Be "a little pushy" on triggers — Claude undertriggers by default, so lean inclusive
• user_invocable: true by default
• argument: include if the skill accepts input

Optional fields — only include when genuinely needed:

• compatibility: environment requirements (1-500 chars)
• metadata: author, version, mcp-server
• license: MIT, Apache-2.0, etc.

Step 3: Write Instructions

Apply the pattern selected in Phase 1 to structure the instructions. Follow these rules:

Voice and form:

• Imperative form: "Run X", "Check Y" — not "You should run X"
• Every instruction is a concrete action, never vague
• GOOD: Run \python scripts/validate.py --input {filename}` to check data format`
• BAD: Validate the data before proceeding

Structure:

• Start with # Skill Name
• Add ## Important or ## Critical header at top for must-follow rules
• Use ## Instructions with ### Step N: [Action] subsections
• Include ## Error Handling section with concrete numbered fixes
• Include ## Examples section with input/output format for common scenarios
• Reference bundled resources: "Before doing X, consult references/Y.md for the complete rule set"

Quality enforcement:

• Add performance notes: "Take your time", "Quality is more important than speed", "Do not skip validation steps"
• Explain the why behind non-obvious decisions — theory of mind beats heavy-handed MUSTs
• Critical instructions go at the top, not buried in the middle

Progressive disclosure:

• Core instructions in SKILL.md, detailed docs in references/
• Keep SKILL.md under 500 lines
• If approaching the limit, add hierarchy and clear pointers to reference files

Step 4: Create References (if needed)

Only create references/ files for skills with:

• Domain knowledge that would bloat SKILL.md
• API patterns or templates
• Multiple variants or modes

For simple skills (~50 lines of instructions), skip references entirely.

When creating reference files:

• Include table of contents for files over 300 lines
• Organize by variant/domain if supporting multiple contexts

Step 5: No README.md

Never create a README.md inside the skill folder. SKILL.md is the only documentation file.

---

Phase 3: Validate (0 pauses)

Run every check from the validation checklist automatically. Read references/validation-checklist.md for the full list.

Validation checks to run:

1. Folder named in kebab-case
2. SKILL.md exists (exact spelling, case-sensitive)
3. YAML frontmatter has --- delimiters
4. name field: kebab-case, no spaces, no capitals
5. name matches folder name
6. description includes WHAT and WHEN components
7. description under 1024 characters
8. No XML tags (< or >) in any frontmatter field
9. Instructions use imperative form (spot-check first 5 action sentences)
10. Error handling section present
11. Examples section present
12. References clearly linked (if references/ exists)
13. No README.md in skill folder
14. SKILL.md under 500 lines

Print the validation report:

Validation Report:
  [PASS] Folder named in kebab-case
  [PASS] SKILL.md exists (exact spelling)
  [PASS] YAML frontmatter has --- delimiters
  ...

If any check fails: fix the issue immediately, re-validate, and show the corrected report. Do not present a report with failures unless the fix requires user input.

---

Phase 4: Deliver (1 pause)

Present the finished skill:

1. Show the full frontmatter — the YAML block between --- delimiters
2. Show instruction structure — headers and step names (not the full content)
3. State the pattern applied and why it was chosen
4. Provide test prompts:
   • 2-3 should-trigger prompts:
     • One obvious task description
     • One paraphrased/indirect request
     • One edge case that should still trigger
   • 2 should-NOT-trigger prompts:
     • Near-misses that share keywords but need a different skill or no skill
     • These are the most valuable tests for preventing overtriggering
5. State location and how to invoke: /skill-name or natural language

Ask: "Anything to adjust, or ready to use? Run /skill-eval to benchmark how well this skill follows its own instructions."

---

Error Handling

Folder already exists

1. Check contents. If it contains an existing skill, ask the user: overwrite or pick a new name?
2. Never silently overwrite.

SKILL.md exceeds 500 lines

1. Identify sections that can move to references/
2. Extract them, replace with pointers: "See references/X.md for details"
3. Re-validate line count

Description exceeds 1024 characters

1. Tighten language — remove redundant trigger phrases
2. Keep the WHAT + WHEN + negative triggers structure
3. Cut capabilities list if needed (triggers matter more)

Frontmatter validation fails

1. Fix the specific field
2. Re-run validation
3. Show corrected report

Examples

Example 1: Simple workflow skill

User: /skill-builder a skill that runs my Python test suite with coverage

Result: A sequential-workflow skill with:

• Frontmatter with triggers like "run tests", "test coverage", "pytest"
• Steps: discover test files, run pytest with coverage flags, parse output, report results
• Error handling for missing dependencies, no tests found, failures
• Examples showing different invocation patterns

Example 2: From conversation

User (after debugging session): "turn this into a skill"

Result: Extracts the debugging workflow from conversation, builds a domain-specific intelligence skill with the diagnostic patterns embedded, triggers on relevant error types.

Example 3: MCP-enhanced skill

User: /skill-builder a skill for managing GitHub issues with labels and milestones

Result: A multi-MCP coordination skill (if GitHub MCP is available) or sequential workflow (if using gh CLI), with triggers for "create issue", "label issues", "milestone planning".