/create-skill

name: create-skill
license: MIT
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.
  Use when a user wants to encode a repeating workflow; do NOT use for one-off
  tasks or modifying existing skills.
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
  - repeated pattern

/create-skill — Skill Creator

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 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)
• The pattern has only happened once
• An existing skill already covers this
• The user wants to modify an existing skill (edit directly)

**Output:** A complete `.claude/skills/{name}/SKILL.md` in the project directory, tested and working.

Protocol

Step 1: DISCOVER — The Three Questions

Ask these three questions and wait for answers before proceeding.

**Q1: "What do you keep repeating?"** Listen for: trigger, steps in order, scope, frequency. If vague, probe: "Walk me through the last time you did this."

**Q2: "What mistakes happen when you do it manually?"** Listen for: forgotten steps, ordering mistakes, convention drift, edge cases. These become guardrails and quality gates.

**Q3: "What does 'done right' look like?"** Listen for: observable outputs, quality signals, anti-patterns. These become quality gates and exit protocol.

Step 2: ANALYZE — Extract the Skill's DNA

Internal working material — do not show to user.

**2a. Identity statement:** "You are a {role} that {does what} to ensure {outcome}." Must distinguish this skill from all others.

**2b. Trigger keywords (5-10):** Specific enough to avoid false matches. Check existing `.claude/skills/` for conflicts.

**2c. Protocol steps:** Transform "what I do" into numbered steps where:

• Each step has a clear input and output
• Decision points have explicit criteria ("IF x THEN y, ELSE z")
• Steps reference concrete things (file paths, commands, patterns)

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

**2d. Quality gates:** Yes/no verifiable questions, no subjective criteria. Map each to a user "done right" criterion or common mistake.

**2e. Pitfalls:** From Q2. Become warnings or guard clauses in the protocol.

Step 3: GENERATE — Write the SKILL.md

Every section required. File MUST be under 500 lines.

---
name: {kebab-case-name}
description: >-
  {One to three sentences. Start with verb. Use when X; do NOT use for Y.}
user-invocable: true
auto-trigger: false
trigger_keywords:
  - {keyword 1}
  - {keyword 2}
---

# /{name} — {Readable Title}

## Orientation

**Use when:**
- {condition}

**Do NOT use when:**
- {exclusion}

**What this skill needs:**
- {required input}

## Protocol

### Step 1: {VERB — Name}
{Exact instructions. What to read, what to produce. No vague directives.}

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

## Quality Gates

- [ ] {Verifiable gate}

## Exit Protocol

{Exact output format}

**Writing rules:** 1. Steps must be reproducible by a different AI session with no memory of this conversation. 2. No hedge language — "do X" not "consider X". 3. No filler — delete sections that add no new information. 4. Include examples only where the pattern is non-obvious. 5. Encode the user's taste: "I hate when it does Z" → explicit prohibition.

Step 4: INSTALL & REGISTER

1. Create `.claude/skills/{name}/` 2. Write the SKILL.md 3. Verify file exists and is readable 4. Register with router: a. Read `.claude/harness.json`, Citadel's shared config path for all runtimes including Codex (create with `{}` if missing) b. Add skill name to `registeredSkills` array c. Update `registeredSkillCount` to match array length 5. Only add the skill to an active project instruction file that already has an explicit skills section. Codex uses `AGENTS.md`. Claude Code uses `CLAUDE.md` when present; with confirmed `AGENTS.md` support, it uses `AGENTS.md` by default if no project `CLAUDE.md` exists, or both when configured under **Project instructions**. Check the active setting before editing and preserve user-authored guidance. 6. Run `/reload-skills` if the running Claude Code version supports it; the skill is live without a session restart. If unsupported, tell the user a fresh session is required before `/{name}` resolves.

Step 5: VERIFY — Test on a Real Target

1. Find a real target in the current project the skill applies to. 2. Run the skill's protocol following the SKILL.md exactly — pretend you are a different AI session with no memory of this conversation. 3. Evaluate: did every step have enough information? Did any step require missing context? Did quality gates catch real issues? 4. If it fails or produces thin output, fix SKILL.md (common fixes: step too vague, step assumed context, gate not checkable, exit output missing fields). 5. Run again after fixes. Must pass on second attempt. If it fails twice, discuss scope with user.

Step 6: TEACH — Explain What Was Built

**A. How to invoke:**

• Direct: `/{name}` or `/{name} [target]`
• Via router: `/do {natural language matching trigger keywords}`

**B. How it works (30-second version):**

• Steps summary, quality gates summary, exit output summary

**C. How to modify:**

• File: `.claude/skills/{name}/SKILL.md`
• Add step: new `### Step N` in Protocol
• Change quality standards: edit Quality Gates checkboxes
• Cha