Create Skill

Purpose

Extract domain expertise from the user and produce a well-structured, verified skill following this library's conventions. Do not begin writing the skill until Phase 1 is complete: a skill written without grounded expertise will be generic and low-value. Do not declare the skill done until Phase 5 verification has run: a skill verified only by reading it is unverified. The deliverable is a skill directory containing SKILL.md, plus optional scripts/ and references/ files when warranted. For changes to an existing skill, the same conventions and verification apply through the adapted workflow in Updating an Existing Skill.

Workflow

Phase 1 - Extract Domain Expertise

First, mine the current conversation. If the user is saying "make this a skill" about work just completed, the answers already exist in the transcript: the procedure followed, tools used, corrections the user made along the way, and input/output formats observed. Extract these, present them back as a summary, and ask only about the gaps. Corrections the user made mid-task are the highest-value content; they mark exactly where default behavior was wrong.

If the conversation does not contain the expertise, send the user all of these questions in a single message:

1. What task or situation should trigger this skill? (defines the description trigger)
2. Walk me through how you do this from start to finish. (extracts the core procedure)
3. What do agents or people most often get wrong about this? (yields the Gotchas section)
4. What should never be done here, and why? (yields anti-patterns and the description's near-miss boundary)
5. Is there a concrete example, past artifact, or reference I can look at? (grounds the skill in reality)
6. How broad should this skill be, one scenario or a family of related tasks? (scope decision)

Skip questions the user's original message already answers. Do not proceed to Phase 2 until the scope is unambiguous. If the user's answer introduces unrelated additions, push back; each unrelated behavior added is a signal the scope should be split into two skills.

Phase 2 - Design the Structure

Make these decisions before writing:

Skill type. Classify the skill; the type drives format and how Phase 5 tests it.

Scope. Is this one coherent skill or should it be split? A skill that spans unrelated behaviors triggers imprecisely. A skill scoped to a single micro-step forces the agent to load multiple skills for one task. The right unit covers a complete procedure the agent performs start-to-finish.

Degrees of freedom. Match instruction specificity to how fragile the task is:

• High freedom (prose heuristics): multiple approaches are valid and context determines the best one. Example: review processes.
• Medium freedom (template or pseudocode with parameters): a preferred pattern exists but variation is acceptable.
• Low freedom (exact script, no deviation): the operation is fragile, must be consistent, or has one safe sequence. Write a scripts/ script and instruct "run exactly this."

Over-specifying judgment calls makes the skill brittle; under-specifying fragile operations makes it unreliable.

Scripts. Bundle a script when the operation is deterministic (validation, transformation, formatting), when the same code would be regenerated on every invocation, or when errors need explicit handling. A bundled script is more reliable than generated code, costs no context until run, and its output is the only part that consumes tokens. See the Scripts section for conventions.

Progressive disclosure. Use references/ only for material needed conditionally (large option tables, API docs, format specs, methodology detail). Put the core procedure in SKILL.md and state exactly when to read each reference file. Keep references one level deep: every reference file links directly from SKILL.md, never from another reference file, because nested references get partially read. Give any reference file over 100 lines a table of contents at the top. Most skills under 300 lines need no references/ at all.

Format. Match structure to content type:

• Sequential phases with dependencies: numbered H3 phases under a Workflow H2
• A set of rules with no ordering: bulleted list with directive verbs
• Comparison or lookup reference: table
• Decision procedure: explicit conditional ("if X, do Y; if Z, do W")

Invocation and execution controls. Most skills need no frontmatter beyond name and description, but decide deliberately for two cases: side-effect workflows where the user controls timing (deploy, commit, publish) get disable-model-invocation: true, and background knowledge that is not a meaningful user action gets user-invocable: false. For these and the rest of the harness surface (arguments, allowed-tools, context: fork, dynamic context injection, path-scoped loading), read references/skill-config.md before writing the frontmatter.

Phase 3 - Write the SKILL.md

Use the template below. Fill every section; delete placeholder text. Specific rules:

• name field must exactly match the directory name (kebab-case)
• Names are verb-led: the name states the action the skill performs (create-diagram, write-docs, fix, follow-tdd), because the name doubles as the /command the user types and a command is an imperative. Noun or topic names (obsidian, code-planning) read as subject areas, not actions, and give no hint what invoking them does
• Write the description field last (see Phase 4)
• H2 for major sections, H3 for subsections; never H1 inside the body
• Directive language: "Always," "Never," "Prefer," "Avoid." Pair each directive with its reason unless the reason is obvious. A rule whose why is understood generalizes to situations the rule's author never anticipated; a bare MUST invites loopholes the moment the literal wording does not fit
• Every code block must include a language identifier, even for shell snippets
• Use tables for comparisons, option lists, and anti-pattern catalogues
• No "When to Use" or "When NOT to Use" sections in the body. Triggers and boundaries live only in the description; body duplicates drift out of sync and restate routing the agent has already passed. A boundary needing more detail than the description holds becomes a Gotcha; a behavioral exception becomes part of the relevant rule
• No absolute filesystem paths anywhere in a skill; they break when the library moves or is shared. Refer to locations relative to the skill directory (scripts/x.py, references/x.md), or use ${CLAUDE_SKILL_DIR} where a command needs a path that works from any working directory (see references/skill-config.md)
• One excellent, runnable, real example beats several mediocre ones. Never implement the same example in multiple languages; the agent can port
• Use one term per concept throughout (always "endpoint", not a mix of "endpoint", "URL", "route")
• No time-sensitive content ("before August 2025, use the old API"); if legacy behavior matters, put it in a collapsed "Old patterns" subsection
• For workflows of four or more steps, include a copyable checklist at the top of the workflow so the agent can track progress and not skip validation steps
• Front-load the critical rules and write them as standing instructions, not one-time steps. An invoked skill body stays in context all session but is never re-read, and on compaction only its first 5,000 tokens survive; a rule buried in the tail can silently vanish mid-task
• Build feedback loops around quality-critical steps: "run the validator, fix errors, run again; proceed only when it passes"
• Target 80-250 lines; hard limit 500 lines; if running long, move reference material to references/
• Each sentence must survive this test: "Would the agent get this wrong without this line?" If no, delete it. Assume the agent is already smart; only add context it does not have

Template:

---
name: <skill-name>
description: This skill should be used when <primary trigger>. It applies when <secondary
  triggers and exact user phrases>. It should not be used for <near-miss boundary, only
  if one is likely>.
---

## Purpose

<One short paragraph. What the agent does when this skill loads. What the deliverable is.
What the agent must NOT do before a certain condition is met, if applicable.>

## Workflow

### 1. <First phase name>

<Directive instructions with reasons. Bullet list or short paragraph.>

### 2. <Second phase name>

<Continue.>

## <Domain-specific section: Rules, Standards, Anti-Patterns, etc.>

<Tables, bulleted rules, or prose as appropriate to the content type.>

## Gotchas

- **<Non-obvious pitfall>**: <What defies reasonable assumptions and why.>

## Examples

<One concrete, realistic example. Not a toy. Runnable if code.>

Phase 4 - Write the Description Field

Write the description after the body is complete; the body reveals the true scope. The description is the only routing surface: at startup the agent preloads every skill's name and description (never the body) into its context, then matches the user's task against them to decide what to load. The body is read only after a match. A bad description causes the skill to never load (too narrow) or load at the wrong time (too broad).

State both what the skill does and when to use it, in the third person. The "what" is a brief capability line (the kind of thing the user asks for), not a procedure; the "when" is concrete triggers. Third person is non-negotiable: the description is injected into the system prompt, and a first-person ("I can help you...") or second-person ("You can use this...") point of view degrades matching. This holds for the whole description, not just the lead: continuation triggers read "It applies when..." (not "Use when..." or "Also use when..."), and boundaries read "It should not be used for..." (not "Do not use for..."). The one exception is a parenthetical cross-reference to another skill, which stays imperative ("(use decompose)") because it directs the agent elsewhere rather than describing this skill.

Descriptions compete for a shared budget. The full set is capped (roughly 1% of the context window); on overflow the least-used skills' descriptions are shortened or dropped first, which strips the keywords needed to match. Lead with the primary trigger so it survives truncation, and keep each description well under the 1,536-character listing cap.

Never summarize the skill's workflow in the description. A brief capability line is fine ("Processes Excel files and generates reports"); a step sequence is not. A description that says "does X by doing A then B" becomes a shortcut: the agent follows the two-word summary instead of reading the body, and the body's actual procedure silently stops executing. Capability and triggers in the description; procedure in the body.

Err generous on triggers. Skills undertrigger by default, and the routing mechanism only consults a skill for tasks substantial enough to benefit; an extra trigger phrase rarely causes false loads, but a missing one guarantees missed loads.

Negative scoping is a remedy, not a default. Add a "not for" boundary only when a real adjacent skill or a likely misread would otherwise pull this skill in. When fixing an observed mis-trigger, generalize to the category that caused it rather than pasting the failed query's exact keywords; specific-keyword patches overfit to one prompt and leave the real boundary fuzzy.

Validate before finalizing: if a different agent read only this description and the user's message, would it confidently decide to load this skill? If not, revise.

Phase 5 - Verify Before Deploying

A skill is a behavior change, and behavior changes get tested. The default verification is lightweight; offer it, and skip only if the user explicitly declines.

1. Write 2-3 realistic test prompts. The kind of message a real user would actually type: concrete, with file paths, specifics, and casual phrasing. Not "use the skill to do X." Confirm them with the user.
2. Run baseline and with-skill in parallel. For each prompt, spawn two subagents in the same message: one given only the task, one told to read the SKILL.md first and then do the task. Parallel spawning matters; serial runs tempt you to skip the baseline.
3. Compare. The question is not "is the with-skill output good?" but "did the skill change behavior in the intended way?" If the baseline output is equivalent, the skill adds nothing where it claims to; cut the redundant content or sharpen what remains. If the with-skill run ignored part of the procedure, that part is unclear or buried; fix the skill, not the prompt.
4. Check for repeated improvisation. If with-skill subagents independently write similar helper code, that code belongs in scripts/ so future invocations stop reinventing it.
5. Trigger check. For each test prompt plus one near-miss negative (a prompt that shares keywords but should NOT trigger), judge whether the description alone would fire correctly. Revise the description on misses.
6. Iterate. Apply fixes, rerun the affected cases. Stop when behavior matches intent or the user is satisfied.

For discipline skills (rules the agent will be tempted to bypass under pressure), lightweight testing is insufficient; read references/testing-skills.md for pressure-scenario methodology before verifying. For skills with subjective outputs (writing style, design taste), skip assertions and have the user qualitatively review the with-skill outputs instead.

Updating an Existing Skill

Trivial typo or formatting fixes that change no behavior need none of this; edit the file directly. Everything else reuses the phases above rather than restarting them:

1. Read the entire skill first, including its references/ and scripts/. Edits made from memory of the skill or from its description alone contradict sections that were not read, and break the one-term-per-concept rule when new wording lands next to old.
2. Mine what triggered the update. Most updates come from observed failure: the skill misfired, missed a trigger, or an agent rationalized around a rule. That observation is the Phase 1 expertise; capture it verbatim before it leaves the conversation, because counters and gotchas added from imagination instead of observation are dead weight (same rule as rationalization counters in references/testing-skills.md).
3. Classify the change, which selects the phases to re-run:

4. Hold the line on scope. "While you're in there, also add X" that crosses a domain boundary is a new skill, not an update. The scope-creep gotcha applies double here because the existing skill already has a settled scope and a description tuned to it.
5. Re-verify proportionally. Mechanical checks always: no em dashes, line count, description parses and matches what you wrote, name still matches the directory. Behavior and trigger changes additionally get targeted Phase 5 runs aimed at the changed behavior only; unchanged behavior needs no re-test.

Scripts

All bundled scripts are Python, executed with uv run. Conventions:

• Path: scripts/<verb-noun>.py inside the skill directory; descriptive names, never helper.py or util.py
• Declare dependencies inline with PEP 723 metadata so the script is fully self-contained; uv run resolves them in an ephemeral environment with no venv or project setup:

# /// script
# requires-python = ">=3.12"
# dependencies = ["pydantic>=2"]
# ///

• Invoke as uv run ${CLAUDE_SKILL_DIR}/scripts/<name>.py <args> in the SKILL.md instructions. The harness substitutes the skill's real directory when the skill content is rendered, so the command works from any working directory while the file on disk stays free of absolute paths. An agent reading the raw file instead of invoking the skill sees the literal placeholder and resolves it from the file's own location
• Solve, don't punt: handle foreseeable error conditions inside the script (missing file, bad input) instead of failing and leaving the agent to figure it out
• Validation errors must be verbose and actionable ("Field 'signature_date' not found. Available fields: customer_name, order_total") because the agent uses the message to self-correct
• No unexplained constants; justify every threshold or timeout in a comment. If you cannot justify the value, the agent cannot adapt it correctly
• State execution intent in SKILL.md: "Run uv run scripts/x.py" means execute; "Read scripts/x.py for the algorithm" means load as reference. Default to execute; the script's output is cheaper than its source

Local Conventions

• Each skill is a directory in the user skills library: <skill-name>/SKILL.md
• Directory name must be kebab-case, verb-led, and match the name frontmatter field exactly
• Check the new name against the bundled command list before settling on it; a personal skill colliding with a bundled skill (/debug, /verify, /run, /review) has undefined precedence
• Reference files: references/<filename>.md inside the skill directory
• Scripts: scripts/<filename>.py inside the skill directory, Python only, run via uv run ${CLAUDE_SKILL_DIR}/scripts/<filename>.py
• No absolute filesystem paths inside any skill file; everything is relative to the skill directory or uses ${CLAUDE_SKILL_DIR}
• No H1 headings inside the body (the frontmatter name serves as the title)
• Confirm the path with the user before saving if there is any ambiguity about the name

Gotchas

• Write the description last. Writing it before the body produces a description of what you intended to write, not what you wrote. Finish the body, then derive the description from it.

• A workflow summary in the description silently disables the body. The routing agent reads the description, thinks it knows the procedure, and never reads the actual steps. This is a documented failure mode, not a style preference: a description mentioning "review between tasks" caused one review where the body required two.

• Scope creep during the interview. Users often start with a narrow task and keep adding "and also when X." Push back on unrelated additions; each one that crosses a domain boundary is a signal this should be two skills.

• Generic content the agent already knows. A skill that says "write clean code" or "be thorough" adds nothing. Every line must be something the agent would not do by default or would get wrong without being told. The Phase 5 baseline run is the empirical test: if the baseline output matches the with-skill output, that content is dead weight.

• The description is the only routing surface. Body sections restating when to use the skill are dead weight: by the time the body is read, routing already happened. Spend that space on procedure; put every trigger and boundary in the description instead.

• Declarations are not procedures. "The output should be well-structured" is a declaration and is useless. "Use H2 for major sections and include a fillable template block" is a procedure. Skills teach the agent how to approach a class of problems.

• A near-miss boundary prevents false triggers, but only when one is actually likely. If a real adjacent skill or a plausible misread would pull this skill in, name the most likely false positive as an explicit exclusion. Skip the boundary when nothing else competes for the request; a boilerplate "not for" only spends budget. When patching an observed mis-trigger, exclude the category that caused it, not that one query's keywords, or the patch overfits.

• A colon-space inside an unquoted description breaks the frontmatter. YAML plain scalars cannot contain ": "; the description silently fails to parse and the skill router falls back to garbage (observed: a description showing as "Purpose"). Avoid inline colons in the description, or quote the whole string. Verify after writing: the parsed description must match what you wrote.

• name field and directory name must be identical. The command name always comes from the directory; the name field only sets the display label in listings. A divergent field gives one skill two identities, so the user invokes a name that no listing shows. Create the directory first, then write the SKILL.md with the field matching.

• Narrative is not a skill. "In one session we found that X caused Y" is a story about one instance. Extract the reusable rule, state it directively, and drop the narrative.