create-skill

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