/create-skill

name: create-skill
description: Author a new skill for this repository end to end by choosing its category, writing trigger-friendly frontmatter, structuring the SKILL.md, splitting reference material into companion files, then regenerating the registry and README catalog. Use when creating, scaffolding, restructuring, or reviewing a skill in this repo.
argument-hint: "(optional) the skill's purpose, proposed name, or category"

Create a new skill that fits this repository's conventions and earns its place: one clear job, a description that triggers reliably, a lean `SKILL.md`, and any heavy detail pushed into companion files. Then regenerate the derived files and validate.

This repo's source layout is `skills/<category>/<name>/SKILL.md`. The **category is the folder**, so there is no category field. Everything else (per-skill `registry.json`, the root `registry.json`, the README catalog) is *generated* by `pnpm gen` from the folder location plus the frontmatter. Never hand-edit generated files.

Hard rules: never break these

• **One skill, one job.** If it needs "and" to describe it, it's probably two skills. Split rather than bloat.
• **Earn the skill.** Don't create one for a single command or something a plain instruction covers. A skill is worth it when there's a reusable, multi-step procedure with judgment and rules.
• **Never hand-write `registry.json`** (per-skill or root) or the README catalog. They are derived; run `pnpm gen`. Editing them by hand guarantees drift.
• **The `SKILL.md` body is always loaded when the skill triggers**, so keep it lean. Push reference material, long tables, examples, and templates into companion files the agent reads on demand (progressive disclosure).
• **`name` must be globally unique and equal the folder name**, kebab-case. Skills install to a flat `.claude/skills/<name>/`, so two skills can't share a name even across categories.
• **Don't invent a category.** Reuse an existing folder unless a genuinely new family is justified (and then it's a deliberate decision, not a default).
• **Match the house voice**: see [reference/voice-and-structure.md](./reference/voice-and-structure.md). No AI/co-author mentions anywhere.

Step 1: Define the skill

Pin down before writing a line:

• **The one job** it does, in a sentence.
• **The trigger**: what a user says or does that should load it. This drives the description.
• **Why a skill**: the reusable procedure/judgment it encodes (vs. a one-off instruction).
• **Whether it already exists**: search `skills/` so you extend rather than duplicate.

If the purpose is fuzzy or sounds like two things, sharpen or split it now.

Step 2: Name and place it

• **Category**: pick the folder it belongs in. Current categories: `academic`, `deployment`, `documentation`, `engineering`, `productivity`, `research`, `security`, `testing`, `version-control`, `writing` (run `ls skills` for the live list). Recategorising later is just a `git mv`.
• **Name**: short, kebab-case, action- or domain-oriented, unique across all skills (see hard rules). The display title is derived by title-casing the name.
• Create `skills/<category>/<name>/`.

Step 3: Write the frontmatter

Frontmatter is what Claude reads to decide *whether* to load the skill, so it's load-bearing. Required: `name`, `description`. Optional: `title` (defaults to title-cased name), `argument-hint`.

• **`description`** is the trigger: write it third-person, lead with what the skill does, and end with an explicit **"Use when …"** clause covering the phrasings that should fire it. Be specific; vague descriptions misfire.

Full field reference and good/bad examples: [reference/frontmatter.md](./reference/frontmatter.md).

Step 4: Write the SKILL.md body

Start from [templates/SKILL.template.md](./templates/SKILL.template.md) and adapt. The established shape across this repo:

1. A one- or two-sentence framing of the job. 2. A **Hard rules** section: the non-negotiables and safety gates, stated imperatively. 3. Numbered **Steps**: the procedure, each step scannable, with the actual commands/decisions. 4. A closing line on what to report/produce.

Write in the second person to the agent, imperative and direct. Voice details, do/don't, and structural patterns: [reference/voice-and-structure.md](./reference/voice-and-structure.md).

Step 5: Split out companion files (when warranted)

Keep `SKILL.md` as the orchestrator. Move into companion files anything that is long, optional, or only needed mid-task: reference tables, format specs, fill-in templates, worked examples. Reference them with relative links so the agent loads them on demand:

skills/<category>/<name>/
├── SKILL.md
├── reference/<topic>.md
└── templates/<thing>.template.md

`pnpm gen` bundles **every** file in the folder automatically (except `registry.json`) and installs it under `.claude/skills/<name>/<relpath>`. Link from `SKILL.md` like `[label](./reference/topic.md)`. When to split vs. inline: [reference/voice-and-structure.md](./reference/voice-and-structure.md).

Step 6: Regenerate and validate

From the repo root:

pnpm gen        # writes per-skill registry.json, root registry.json, README catalog
pnpm validate   # checks frontmatter + layout, then shadcn registry validate

`pnpm gen` is the only thing that should ever touch the generated files. If `pnpm validate` fails, fix the frontmatter/layout it points at and rerun; don't patch the generated output.

Step 7: Review against the bar

Before calling it done:

• The description would actually trigger on the intended phrasings (and wouldn't over-trigger).
• `SKILL.md` is lean; depth lives in companion files.
• Hard rules and steps are concrete and safe, with confirmations on anything irreversible or outward-facing.
• It reads like the existing skills in voice and structure.
• `pnpm validate` passes and the README catalog shows the new row under the right category.

Report the skill's path, category, what