create-skill

What this skill does

# Create Skill

Create new agent skills with specification-driven generation, live documentation fetching, and interactive planning.

## Writing Philosophy

Before starting, internalize these principles — they make the difference between a skill that works once vs. one that works reliably across varied inputs:

**Explain the why**: Replace heavy-handed "MUSTs" with reasoning. LLMs respond better to understanding why a constraint exists than to being commanded. "Fetch live specs because specifications evolve weekly" beats "ALWAYS fetch live specs."

**Pushy descriptions**: Combat undertriggering by making descriptions assertive. "Use this whenever someone says 'create a workflow', 'make a command', or 'turn this into a skill'" beats "Use for skill creation." Model-invoked skills that don't trigger aren't useful.

**Keep it lean**: Remove instructions that aren't pulling their weight. Every line competes for attention in the context window. A 100-line skill often beats a 500-line skill if the extra 400 lines are noise, redundancy, or edge cases that never occur.

**Generalize, don't overfit**: Skills designed only around their own test examples fail in practice. Design for the pattern, not the specific instance. Ask: "Would this instruction still apply if the user's request looked different?"

**Mine conversations first**: Users rarely articulate needs perfectly upfront. Extract information they've already provided before asking more questions.

## Workflow

### Phase 0: Fetch Live Specifications

Fetch latest specs before every creation — never rely on memory or bundled docs, because specifications evolve.

Spawn 2 parallel Explore agents (model: haiku to minimize cost):

```
Agent 1 - Fetch Skill Specifications:
- subagent_type: "Explore"
- model: "haiku"
- prompt: "Fetch and summarize the latest skill specifications:
  1. WebFetch https://agentskills.io/what-are-skills.md — extract: what skills are, anatomy, when to use
  2. WebFetch https://agentskills.io/specification.md — extract: frontmatter fields, allowed-tools syntax, directory rules
  Return: Structured summary with examples"

Agent 2 - Fetch Best Practices:
- subagent_type: "Explore"
- model: "haiku"
- prompt: "Fetch Claude Code skill best practices:
  1. WebFetch https://platform.claude.com/docs/skills/best-practices.md — extract: progressive disclosure, writing style, anti-hallucination patterns
  2. If URL fails, read bundled: skills/create-skill/references/skill-anatomy.md
  Return: Key guidelines and common pitfalls"
```

Hold results in context. Do not proceed until both agents return.

### Phase 1: Understand Requirements

**Step 1: Mine the conversation.** Read what the user already said and extract:
- What skill/command/workflow they want
- Examples of triggers they mentioned
- Tools, files, or outputs they described
- Who will use it (personal, team, organization)

Extract answers from conversation history before asking questions — don't ask what's already there.

**Step 2: Four key questions** (ask only what the conversation didn't already answer) using AskUserQuestion:

1. **What does this skill do?** — Focus on the outcome. "Generates ADRs in the Nygard format from a decision description" beats "helps with documentation." The more specific, the better the description will be.

2. **When should it trigger?** — Give 2-3 examples of exactly what a user would type to activate it. These become the description. Think about different phrasings the same intent might take.

3. **What does success look like?** — Describe the output or end state specifically. "Creates a numbered file in docs/adr/ with YAML frontmatter and four required sections" is useful; "produces documentation" isn't.

4. **Is this worth measuring?** — Would you want to compare this skill's output against a no-skill baseline to know it's actually helping? This matters most for model-invoked skills that trigger automatically on vague prompts.

Adapt communication style to the user. Technical users: use precise terms (frontmatter, YAML, subprocess). Non-technical users: explain concepts ("the skill's metadata tells agents when to activate it").

**Step 3: Interview for edge cases.** Before planning, clarify:
- What are 2-3 common ways this could go wrong?
- Are there input variations that need different handling?
- What should the skill explicitly NOT do (to set scope boundaries)?

### Phase 2: Research Existing Patterns & Composition

Spawn 2 parallel Explore agents (model: haiku) using the Task tool:

```
Agent 1 - Internal Pattern Analysis:
- subagent_type: "Explore"
- model: "haiku"
- prompt: "Search skills/ directory for skills similar to [SKILL_PURPOSE].
  Extract:
  1. Similar skill patterns: frontmatter structure, phase organization, tool usage
  2. Composable skills: existing skills this new skill could reference or invoke
     Example: A deploy skill could invoke git-commit; a testing skill could invoke fix-bug
  3. scripts/ usage patterns: when scripts are included vs not
  Return: Patterns summary with file paths + composable skills list"

Agent 2 - External Example Research:
- subagent_type: "Explore"
- model: "haiku"
- prompt: "Research external skill examples:
  1. WebFetch https://skills.sh — search for skills similar to [SKILL_PURPOSE]
  2. WebFetch https://raw.githubusercontent.com/anthropics/skills/main/skills/skill-creator/SKILL.md — extract: workflow phases, frontmatter patterns, anti-hallucination techniques used in Anthropic's own skill-creator reference implementation
  3. Look for anti-hallucination and verification patterns
  Return: Best practices and common patterns with sources"
```

Consolidate into: pattern summary, composable skills list, decision rationale.

### Phase 3: Plan Skill Structure (User Approval Required)

Use EnterPlanMode to require explicit user approval before generating any files.

Present a complete blueprint:

**1. Frontmatter Design:**
```yaml
name: skill-name          # kebab-case, ≤64 chars, no leading/trailing/consecutive hyphens
description: "..."        # assertive, covers multiple trigger phrasings, 50-1024 chars
[disable-model-invocation: true]   # add only for explicit /slash-command-only skills
[argument-hint: "[hint]"]          # add if skill accepts a positional argument
allowed-tools:            # only list tools actually used — each has a cost
  - Read                  # explain why each is here
  - Write
```

Allowed frontmatter keys: `name`, `description`, `license`, `allowed-tools`, `metadata`, `compatibility`, `disable-model-invocation`, `argument-hint`. Reject anything else — unknown keys cause validation failures.

**2. Directory Structure** — explain why each directory is or isn't included:
```
skill-name/
├── SKILL.md (required)
├── scripts/      ← include if: code would be rewritten identically on every invocation
├── references/   ← include if: reference docs would push SKILL.md past 500 lines
└── assets/       ← include if: output templates or static files are needed
```

**3. Workflow Outline**: 2-6 phases covering the full task from start to verified completion.

**4. Test Case Plan** (if user said "yes" to Q4):
- 2-3 trigger prompts that should activate the skill
- Expected output for each prompt
- These will become `evals/evals.json` entries

**5. Composition Plan**: List existing skills to invoke and why, vs. reimplementing.

Use ExitPlanMode to submit for user approval. Do NOT generate any files before ExitPlanMode returns.

### Phase 4: Generate Skill Files

Create files only after approval from Phase 3.

**Writing SKILL.md:**

Lead with what the skill does (outcome), not what it is. Structure instructions as imperative phases: "Fetch...", "Create...", "Validate..." — not "You should fetch..." or "Claude will create..."

Each phase should explain WHY the step matters:
- BAD: "Run the validator."
- GOOD: "Run the validator — it catches frontmatter key typos that silently break skill loading."

Include verification checkpoints: what does