Create Skill

/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.