create-skill · diff
git:20260329.6c378a2 to git:20260503.631b94d
81 added, 215 removed. Audit A to A.
---
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.
+ 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
---
# /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)
+ - 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)
- **What this skill produces:**
- - A complete `.claude/skills/{name}/SKILL.md` file in the project's directory
- (custom skills live in the project, separate from Citadel's built-in skills)
- - A tested, working skill that has been validated on a real target
- - A user who understands how to invoke and modify their new skill
+ **Output:** A complete `.claude/skills/{name}/SKILL.md` in the project directory, tested and working.
## 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.
+ Ask these three questions and wait for answers before proceeding.
- **Question 3: "What does 'done right' look like?"**
+ **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."
- 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"?)
+ **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.
- These become the skill's quality gates and exit protocol.
+ **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
- 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.
+ Internal working material — do not show to user.
- **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
+ **2a. Identity statement:** "You are a {role} that {does what} to ensure {outcome}." Must distinguish this skill from all others.
- 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.
+ **2b. Trigger keywords (5-10):** Specific enough to avoid false matches. Check existing `.claude/skills/` for conflicts.
- **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
+ **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) 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."
+ - Steps reference concrete things (file paths, commands, patterns)
- The difference: a bad step requires judgment that has not been encoded. A good
- step converts judgment into checkable criteria.
+ 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** (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.
+ **2d. Quality gates:** Yes/no verifiable questions, no subjective criteria. Map each to a user "done right" criterion or common mistake.
- **2e. Common pitfalls** (what to warn about)
- These come directly from Question 2. They become warnings or guard clauses in
- the protocol.
+ **2e. Pitfalls:** From Q2. 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.
+ Every section required. File MUST be under 500 lines.
```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.}
+ {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}
- ## 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}
+ - {condition}
**Do NOT use when:**
- - {Specific exclusion 1}
- - {Specific exclusion 2}
+ - {exclusion}
**What this skill needs:**
- - {Required input 1}
- - {Required input 2}
+ - {required input}
## 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}
+ ### Step 1: {VERB — Name}
+ {Exact instructions. What to read, what to produce. No vague directives.}
- {Continue for each step...}
+ ### Step 2: {VERB — Name}
+ {Continue...}
## Quality Gates
- All of these must be true before the skill exits:
-
- - [ ] {Verifiable gate 1}
- - [ ] {Verifiable gate 2}
- - [ ] {Verifiable gate 3}
+ - [ ] {Verifiable gate}
## 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.}
+ {Exact output format}
```
- **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 & REGISTER — Place the File
+ **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.
- 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
- 4. **Register with the router:**
- a. Read `.claude/harness.json` (create if missing with `{}`)
- b. Add the skill name to the `registeredSkills` array (if not already present)
- c. Update `registeredSkillCount` to match the array length
- d. This ensures `/do` routes to the new skill immediately without waiting for `/do setup`
+ ### Step 4: INSTALL & REGISTER
- 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.
+ 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` (create with `{}` if missing)
+ b. Add skill name to `registeredSkills` array
+ c. Update `registeredSkillCount` to match array length
+ 5. Only add to CLAUDE.md if it has an explicit skills section listing 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.
+ 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
- The user must leave this conversation knowing three things:
-
- **A. How to invoke it:**
+ **A. How to invoke:**
- Direct: `/{name}` or `/{name} [target]`
- - Via router: `/do {natural language that matches trigger keywords}`
- - Explain which trigger keywords will route to this skill
+ - Via router: `/do {natural language matching trigger keywords}`
**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]."
+ - Steps summary, quality gates summary, 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
+ **C. How to modify:**
+ - File: `.claude/skills/{name}/SKILL.md`
+ - Add step: new `### Step N` in Protocol
+ - Change quality standards: edit Quality Gates checkboxes
+ - Change trigger words: edit `trigger_keywords` in frontmatter
+ - Split if too large: create two skills, move steps between them
- ## Quality Gates
+ ## Contextual Gates
- All of these must be true before the skill exits:
+ **Disclosure:** "Creating skill '{name}'. Will create `skills/{name}/SKILL.md`."
+ **Reversibility:** green — creates `skills/{name}/SKILL.md` only; undo by deleting the directory.
+ **Trust gates:**
+ - Any: full skill creation, install, and teach workflow.
- - [ ] Three discovery questions were asked and answered by the user
- - [ ] Generated SKILL.md follows the exact format (frontmatter + 5 sections)
+ ## Quality Gates
+
+ - [ ] Three discovery questions asked and answered
+ - [ ] Generated SKILL.md follows exact format (frontmatter + required 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
+ - [ ] Description includes use-when / do-not-use orientation
+ - [ ] Protocol steps 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)
+ - [ ] Quality gates all yes/no verifiable
- [ ] 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`
+ - [ ] Skill tested on a real target in the current project
+ - [ ] Test produced meaningful output
+ - [ ] User taught invocation, mechanics, and modification
+ - [ ] File 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}
+ Reversibility: green — delete skills/{name}/ to undo
```
-
- Then include the one-liner invocation example:
```
Try it now: /{name} {suggested first target}
```