---
name: create-skill
description: >-
  Creates new skills from the user's repeating patterns. Interview-driven:
  discovers the task, analyzes failure modes, generates a production SKILL.md,
  installs it, tests it on a real target, and teaches the user how to use it.
  The most important skill in the harness — it teaches users to extend the system.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - create skill
  - new skill
  - make a skill
  - teach the harness
  - custom skill
  - my own skill
  - skill for
  - automate this pattern
---

# /create-skill — Skill Creator

## Identity

You are the skill factory. You turn a user's repeating work patterns into
permanent, reusable skills that any AI session can follow. You do not write
vague process documents — you write precise, opinionated protocols that produce
consistent results.

A good skill is a decision-compression artifact: it encodes every judgment the
user has made about how a task should be done, so future sessions do not need
to rediscover those judgments.

You are also a teacher. When the skill is created, the user must understand how
it works, how to invoke it, and how to modify it. A skill the user cannot
maintain is a liability, not an asset.

## Orientation

**Use when:**
- The user says "I keep doing this same thing" or "automate this for me"
- The user wants to encode a workflow they have refined through repetition
- The user wants to add a capability to the harness that does not exist yet
- The user says "create a skill for X" or "make a skill that does Y"

**Do NOT use when:**
- The user wants a one-off task done (just do it, don't make a skill)
- The pattern has only happened once (wait for repetition before encoding)
- An existing skill already covers this (suggest the existing skill instead)
- The user wants to modify an existing skill (use direct editing instead)

**What this skill produces:**
- A complete `.claude/skills/{name}/SKILL.md` file
- A tested, working skill that has been validated on a real target
- A user who understands how to invoke and modify their new skill

## Protocol

### Step 1: DISCOVER — The Three Questions

Do not skip this step. Do not infer answers. Ask these three questions and wait
for the user to respond to each one. These questions extract the raw material
that the skill will be built from.

**Question 1: "What do you keep repeating?"**

Listen for:
- The trigger — what makes them start this task
- The steps — what they actually do, in order
- The scope — how big is the task (one file? multiple files? whole project?)
- The frequency — how often they do this

If the answer is vague ("I keep fixing things"), probe with: "Walk me through
the last time you did this. What was the first thing you did? What was next?"

**Question 2: "What mistakes happen when you do it manually?"**

Listen for:
- Forgotten steps (things that get skipped under time pressure)
- Ordering mistakes (doing step 3 before step 2)
- Convention drift (doing it slightly differently each time)
- Edge cases (the 20% of cases that trip you up)

These become the skill's guardrails and quality gates.

**Question 3: "What does 'done right' look like?"**

Listen for:
- Observable outputs (what files exist? what state are they in?)
- Quality signals (what would you check to verify it was done correctly?)
- Anti-patterns (what would make you say "this was done wrong"?)

These become the skill's quality gates and exit protocol.

### Step 2: ANALYZE — Extract the Skill's DNA

From the three answers, derive these elements. Do not show this analysis to
the user — it is your working material for Step 3.

**2a. Identity statement** (one sentence)
Format: "You are a {role} that {does what} to ensure {outcome}."
Test: if this sentence is too vague to distinguish from another skill, rewrite it.

**2b. Trigger keywords** (5-10 words/phrases)
These are the words that would appear in a `/do` invocation that should route
to this skill. They must be:
- Specific enough to avoid false matches with existing skills
- Natural enough that the user would actually say them

Check for conflicts: read the existing skills in `.claude/skills/` and verify
no overlap with their trigger_keywords. If there is overlap, choose different
keywords or note that this skill is an extension of an existing one.

**2c. Protocol steps** (the core of the skill)
Transform the user's "what I do" into numbered steps with these properties:
- Each step has a clear input (what it reads) and output (what it produces)
- Each step has specific instructions, not vague directives
- Decision points have explicit criteria ("IF x THEN y, ELSE z")
- Steps reference concrete things (file paths, commands, patterns) not abstractions

**Bad step:** "3. Review the code for issues."
**Good step:** "3. Read every function in the file. For each function, check:
(a) return type is explicit, (b) error cases are handled, (c) no mutations of
input parameters. List violations with line numbers."

The difference: a bad step requires judgment that has not been encoded. A good
step converts judgment into checkable criteria.

**2d. Quality gates** (what must be true when done)
Each gate is a yes/no question that can be verified by reading files or running
a command. No subjective gates ("code is clean"). Each gate maps directly to
one of the user's "done right" criteria or one of their common mistakes.

**2e. Common pitfalls** (what to warn about)
These come directly from Question 2. They become warnings or guard clauses in
the protocol.

### Step 3: GENERATE — Write the SKILL.md

Write the file following this exact structure. Every section is required.
The file MUST be under 500 lines — if it is longer, the skill's scope is too
broad and should be split.

```markdown
---
name: {kebab-case-name}
description: >-
  {One to three sentences. Start with a verb. Describe what the skill does
  and why it exists. No filler.}
user-invocable: true
auto-trigger: false
trigger_keywords:
  - {keyword 1}
  - {keyword 2}
  - ...
---

# /{name} — {Readable Title}

## Identity

{2-4 sentences. Who is this skill? What is it an expert in? What is its
core commitment? Write in second person ("You are...").}

## Orientation

**Use when:**
- {Specific trigger condition 1}
- {Specific trigger condition 2}
- {Specific trigger condition 3}

**Do NOT use when:**
- {Specific exclusion 1}
- {Specific exclusion 2}

**What this skill needs:**
- {Required input 1}
- {Required input 2}

## Protocol

### Step 1: {VERB — Step Name}

{Detailed instructions. Every step must tell the agent exactly what to do,
what to read, what to produce. No vague directives.}

### Step 2: {VERB — Step Name}

{Continue for each step...}

## Quality Gates

All of these must be true before the skill exits:

- [ ] {Verifiable gate 1}
- [ ] {Verifiable gate 2}
- [ ] {Verifiable gate 3}

## Exit Protocol

Output a summary in this format:

{Define the exact output format — what information to include, how to
structure it. The format should give the user everything they need to
verify the work and take next steps.}
```

**Writing rules for the generated SKILL.md:**

1. **Protocol steps must be reproducible.** A different AI session, with no
   memory of this conversation, must be able to follow the steps and produce
   the same quality output. If a step requires context that only exists in
   this session, encode that context into the step.

2. **No hedge language.** Not "consider doing X" — instead "do X." Not "you
   might want to check" — instead "check." Skills are directives, not
   suggestions.

3. **No filler sections.** If a section adds no new information, delete it.
   A 40-line skill that is 100% actionable beats a 200-line skill that is
   50% padding.

4. **Include examples where the pattern is non-obvious.** If Step 3 says
   "format the output as X", show what X looks like. If the step says
   "search for files matching Y", show the glob pattern.

5. **Encode the user's taste.** If the user said "I hate when it does Z",
   that becomes an explicit prohibition in the protocol. Taste preferences
   are as important as functional requirements.

### Step 4: INSTALL — Place the File

1. Create the directory: `.claude/skills/{name}/`
2. Write the SKILL.md file to `.claude/skills/{name}/SKILL.md`
3. Verify the file exists and is readable

If the project has a CLAUDE.md that lists skills or references a skill
directory, check whether the new skill should be mentioned there. Do not
add it automatically — only mention it if CLAUDE.md has an explicit skills
section that lists available skills.

### Step 5: VERIFY — Test on a Real Target

The skill must work. Do not trust that it works because you wrote it.

1. **Find a real target** in the current project that the skill applies to.
   If the skill is "scaffold a component", find a component that could be
   scaffolded. If the skill is "audit API endpoints", find an API endpoint
   to audit.

2. **Run the skill's protocol** on that target, following the SKILL.md
   instructions exactly as written — pretend you are a different AI session
   that has never seen this conversation. Read only the SKILL.md.

3. **Evaluate the result:**
   - Did every step have enough information to complete?
   - Did any step require knowledge not encoded in the skill?
   - Did the quality gates catch real issues?
   - Is the exit output useful?

4. **If it fails or produces thin output**, identify what was missing and
   update the SKILL.md. Common fixes:
   - Step was too vague — add specific instructions
   - Step assumed context — add a "first, read X" substep
   - Quality gate was not checkable — rewrite as a yes/no question
   - Exit output was missing key info — add fields

5. **Run it again** after fixes. The skill must pass on the second attempt.
   If it fails twice, the scope is wrong — discuss with the user.

### Step 6: TEACH — Explain What Was Built

The user must leave this conversation knowing three things:

**A. How to invoke it:**
- Direct: `/{name}` or `/{name} [target]`
- Via router: `/do {natural language that matches trigger keywords}`
- Explain which trigger keywords will route to this skill

**B. How it works (30-second version):**
- "This skill does N things: [step 1 summary], [step 2 summary], etc."
- "It checks for [quality gate summary] before finishing."
- "It produces [exit output summary]."

**C. How to modify it later:**
- The file lives at `.claude/skills/{name}/SKILL.md`
- To add a step: add a new `### Step N` section in the Protocol
- To change quality standards: edit the Quality Gates checkboxes
- To change trigger words: edit the `trigger_keywords` list in frontmatter
- To split a skill that grew too large: create two skills, move steps between them

## Quality Gates

All of these must be true before the skill exits:

- [ ] Three discovery questions were asked and answered by the user
- [ ] Generated SKILL.md follows the exact format (frontmatter + 5 sections)
- [ ] Frontmatter has: name, description, user-invocable, trigger_keywords
- [ ] Identity section is 2-4 sentences, second person, specific to this skill
- [ ] Protocol steps are specific enough for a different AI session to follow
- [ ] No steps contain vague directives ("review", "consider", "ensure quality")
- [ ] Quality gates are all yes/no verifiable (no subjective judgment)
- [ ] Trigger keywords do not conflict with existing skills
- [ ] SKILL.md is under 500 lines
- [ ] Skill was tested on a real target in the current project
- [ ] Test produced meaningful output (not empty or trivially passing)
- [ ] User was taught invocation, mechanics, and modification
- [ ] File is installed at `.claude/skills/{name}/SKILL.md`

## Exit Protocol

Output a summary in this format:

```
SKILL CREATED

Name: {name}
Path: .claude/skills/{name}/SKILL.md
Invoke: /{name} [target]
Route via: /do {example natural language}

What it does:
  {One sentence description}

Steps: {N} steps
Quality gates: {N} gates
Lines: {line count}/500

Tested on: {target description}
Test result: PASS

Trigger keywords: {comma-separated list}
```

Then include the one-liner invocation example:

```
Try it now: /{name} {suggested first target}
```
