create-skill

You build skills regularly, and there's a specific philosophy: skills are atomic — single-responsibility. Each does one job well; composite behavior comes from chaining atoms (ad-hoc in a session, or as a named composite like /work or /super-review). This skill helps you author a new one that fits that model from birth, instead of producing a sprawling skill you'll have to split later.

Apply the "S" in SOLID to skills: if the ask is really several jobs, recommend splitting it into single-responsibility atoms rather than building one skill wearing a trench coat. Whether those atoms also warrant a standing composite that chains them is a separate, higher bar — see the guardrail below.

The flow

1. Capture intent — chain /interview

First mine the conversation: is there already a described workflow or a repeated pattern the user wants to capture ("turn this into a skill")? Extract what you can — the steps, the tools used, the trigger phrasing, the input/output shape, corrections made along the way.

Then invoke /interview to lock the design decisions you can't infer. The skill-specific axes worth interrogating (let /interview pick the ~4 that are genuinely open — don't ask what the conversation already answered):

• Single responsibility. What is the one job? If it smells like several, surface the split (atoms + composite) as a recommended option in the interview.
• Trigger. When should it fire — what phrases/contexts? This becomes the description, which is the actual auto-invocation mechanism, so it matters most.
• Invocation mode. Listed, name-only, or not model-invocable at all? Decided by the listing rules in step 3. Trade-off to weigh, not a reflex: chaining a hygiene skill to an invariable moment (a hook-backed command like /done) guarantees it runs consistently — but only pays off if that moment is one where the user actually wants the skill's output. A codify skill chained from a closeout command is the cautionary case: closeout is exactly when you want to move on, not read a codify dump, so it works better run manually. So: weigh consistency-via-chaining against whether the trigger moment fits the output, and don't assume the user won't keep a manual ritual — for some skills a manual one is preferred.
• Chaining. Will other skills chain this one, and does it chain others? Drives chain-safety (see below).
• Halt points (orchestrators only). Which steps genuinely need to stop for a human (an irreversible action, a judgment only the user can make)? Everything else is decided in-flow and printed as a Decision: line — never a chained decision skill.
• Isolation. Should it run in a context: fork (read-only analysis that would otherwise end the turn when chained, or just to keep main context clean)? If so, which agent? Lean fork for a long, self-contained job whose inputs fit in its arguments — the user can keep steering the main session while it runs, where an inline skill forces a hard stop to redirect. Keep it inline when it needs the conversation (it judges from the session) or has to talk to the user; and don't wrap a skill in a separate fork skill — make the skill fork itself.
• Output shape, arguments, and location (shared vs project — see below).

The name is deliberately not one of those axes — it's step 2, once the one job is pinned down.

/interview ends by restating intent and getting the user's confirm. When it hands that back, you have your spec — continue here. Don't re-ask what it already locked.

2. Name it — always bring options, even when the user named it

Users often float a candidate name or three when they ask for a skill ("something like /value-to-effort or /matrix or /eval, idk"). Those are candidates, never the decision — offer a real set to choose from every time, without being asked and without the user having to say "open to suggestions." They often keep their own; the point is that it wins against alternatives rather than by default.

Name after the one job, in the suite's register: verbs for actions (/ship, /test, /mutate), nouns for what lands in front of the user (/notes, /steps, /report). One word where it reads, two hyphenated where it doesn't (/done-check, /blast-radius). Check what's taken first — ls ~/.claude/skills/ .claude/skills/ plus this session's skill list for native built-ins — because a shared name silently shadows a project one (personal > project precedence), so a collision is a bug, not a note. Avoid a name whose meaning collides with a sibling even when the string doesn't; the cost is the user reaching for the wrong skill months later.

Offer 3–4 candidates including the user's own, via AskUserQuestion so they pick at a glance ("Other" covers a name neither of you listed). Vary the angle instead of listing synonyms — what it does, what it hands back, the shorthand they'd say out loud — one line of why each, recommendation first (a committed call is easier to act on than a bare menu).

3. Draft the SKILL.md against the standards

These are the same bar /curate audits against, so a skill drafted to them passes review on substance, not style (the good bones, lightly adapted from the native skill-creator):

• The description is the trigger. Make it crisp and a little pushy so it fires at the right moment — and say when NOT to use it, cross-referencing the sibling skill that covers the adjacent case (the way /tldr ↔ /recommend and /done-check ↔ /wrap-up do). This is the single highest-leverage line in the file.
• Explain the why, not heavy-handed MUSTs. The model running the skill is smart and has theory of mind; tell it why a step matters and it'll generalize. All-caps ALWAYS/NEVER and rigid scaffolding are a yellow flag — reframe as reasoning. (The exception this suite actually uses: deliberate anti-halt pressure in composites — but prefer the structural fork fix over prompt-pressure; see chain-safety.)
• Single responsibility, high signal. One job. No repetition — restating the same instruction three ways is the #1 bloat smell. Length isn't bloat; repetition is.
• Progressive disclosure. Keep SKILL.md tight (ideally < ~500 lines). If it needs a lot of reference material, push it into references/*.md and point at it, rather than inlining.
• Pointers must be explicit Read instructions. Only the invoked SKILL.md auto-loads — "the /other-skill rules apply here" silently loads nothing. Any reference to a sibling file or another skill's content must say Read <full path> (a real /curate find: a skill pointed at a sibling file without a Read instruction, so nothing actually loaded).
• Listed or name-only is a judgment call — default to name-only, and if you keep it listed, say which listing criterion (under Frontmatter below) it meets in the hand-off. The listing is a shared budget; every listed skill spends it in every session.
• Match the voice. Read a sibling skill of the same shape before drafting — interaction/decision skills (/recommend), gates (/done-check), orchestrators (/work), composites (/wrap-up) — and mirror its register.
• Glance-first for high-load moments. If the skill fires at a context-switch or closeout moment (chained from /done, end-of-flow, anything the user reads while juggling), it earns its keep by leading with — or ending on — a single glanceable verdict, with the supporting detail deferred behind an opt-in follow-up (/go, "show me #2"). A report-shaped dump at a closeout is noise; users stop using a skill that makes them hunt for the bottom line. (A multi-section ledger that becomes one verdict line with the detail held back is the model.)

Frontmatter per house conventions (full field reference: ~/.claude/skills/FRONTMATTER-REFERENCE.txt — read it if unsure):

• name must match the folder name.
• YAML-safe values. Quote any value containing : or starting with [, {, *, &, !, |, > (argument-hint: "[scope] — optional", not bare), or use a >- block for a long description.
• disable-model-invocation is false by default for every skill. That's what lets you sequence a skill mid-prompt ("…then wrap up") and lets orchestrators chain it — a chained inner skill set to true balks and short-circuits the chain. Set true only when the model must be unable to run it even when you ask (a prod action you start by typing); it costs mid-prompt use, so it's rare on purpose.
• Listing mode (separate from disable-model-invocation): a "<name>": "name-only" entry in skillOverrides in ~/.claude/settings.json keeps the skill invocable and chainable but takes its description out of the always-loaded skill listing. Name-only is the default. Keep a description listed only if the model should fire the skill from the situation, unasked, or you trigger it with natural language rather than its slash name (the description is what maps your words to it). A skill a CLAUDE.md already routes to by name needs no listed description either. Keep the listed set short (on the order of 15): the listing has a total size budget, and on overflow the harness silently drops descriptions, least-used first, so a brand-new skill loses its description first.
• Safeguards go in the body's first lines, not only the description. Name-only lowers self-firing but doesn't prevent it — the model can still pick a skill from its name alone — and a name-only description never loads. So "run only on an explicit ask" belongs at the top of the body, where it loads on invocation.
• context: fork + agent: when the skill should run isolated. Add background: false if a caller reads its result before continuing, because forks run in the background by default.
• argument-hint — arguments are optional steering, never required modes. Give a skill the user initiates an argument-hint whenever it has a scope worth narrowing: the CLI shows it greyed out after /name when the skill starts a prompt, which is the only in-terminal reminder of the shape (it shows nothing mid-prompt). The body resolves scope in one order — explicit $ARGUMENTS → the words around the invocation and the conversation → a no-arg default that does the right thing on its own — so a mid-prompt or chained call needs no argument and the hint stays a reminder, not a contract. Keep the hint shape-level and mark it optional ([feedback | cull [epic] | hygiene | TICKET-<n>] — optional). What stays ruled out is the toolbox: an argument set that is really a menu of unrelated jobs is several skills, and a keyword the user must remember to get the right behavior is a mode nobody will use. Positional/flag args remain fine for skills orchestrators chain, since the caller knows the contract.

4. Confirm + write

If /interview already locked the spec, don't re-gate the concept — but do show the drafted SKILL.md for a quick read before writing (a draft is easy to tweak; a written file invites yak-shaving). On the nod:

• Create <dir>/<name>/SKILL.md. Folder name must equal the name: field.
• Location:
  • Shared (default) → ~/.claude/skills/<name>/ — personal, available in every project on this machine (and anywhere else you sync that dir). Call out that a shared write lands in all of them.
  • Project → .claude/skills/<name>/ in the current repo — for team-facing or repo-specific skills (a repo's own review or deploy skill). Checked into the repo.
  • A composite lives at the narrowest scope among its atoms. Dependency arrows point up-scope only: a project composite may chain shared atoms (present in every session), but a shared composite must never chain a project/local atom — it would break in every scope that atom doesn't exist in, and the shared name would silently shadow the project copy (personal > project precedence). So a composite that chains any project-local atom is itself project-local — the /ship / /wrap-up pattern: project glue chaining shared building blocks, never pushed down into ~/.claude/skills/. Match visibility too: a composite that chains a local-only atom (git-excluded, machine-tied) is itself local-only.
  • Hand-offs point DOWN-scope — the mirror image of that dependency rule. A project-local skill that ends by naming a next skill should name the project's own driver, not the shared atom that driver wraps. Shared orchestrators like /work are deliberately generic — /work stops at reviewed code and knows nothing about how this repo verifies or lands anything. If you're going to /work something you almost always intend to ship it, so the shared atom is almost never the right thing to offer by name. Ask "which skill knows this repo's deploy flow?" — that's the hand-off.
• Name-only it (the default) — add "<name>": "name-only" to skillOverrides in your settings file.

5. Verify + hand off

• Sanity-check the file against the step 3 standards, one by one: folder == name; frontmatter parses; listing decision made; description in budget (≤ ~70 words if listed, with a when-NOT-to + sibling cross-ref); no bloat; chain-safe ending.
• Chain-safety flag. If this skill is meant to be chained by another but ends with a terminal/satisfying block (a verdict, a recap, "final reply and nothing else"), it'll halt the chain. The structural fix is a thin forked wrapper with background: false, so its output returns as a result and the caller keeps control — the /review-plan and /super-review precedent. Recommend it where it applies rather than papering over with "you MUST continue" pressure.
• Dogfood the chain — for any skill another skill will call. Reading the frontmatter can't prove chain-safety; running it can. Invoke the new skill once through the Skill tool exactly the way its caller will — same argument shape, same hand-back token (nested, noreport) — on a harmless input: a verification-only scope, a no-op diff, a local or dev target. It passes when all three hold: the result comes back as a tool result and your own turn keeps going (no stall, no turn-ending block); the output matches the skill's own contract (its terminus block, its evidence lines); and it actually walked its steps (the scripts ran, the gates printed). A fork that returns mid-flight, a report that reads like a finished turn, or skipped steps is a fail — fix the structure and re-run before hand-off. It catches real defects too, like a preflight gap the author missed.
• A skill written this session can come back Unknown skill until the harness re-reads the skills directory. Don't wait: dogfood it as a general-purpose Agent told to Read the new SKILL.md and follow it with the same arguments. [workaround — delete when new skills register immediately]
• Curate it — every time, before hand-off. Invoke /curate <name> right after writing; it forks itself and runs in the background, so do the dogfood run meanwhile. The hand-off waits for its report. Fold every real defect it finds (a wrong command or path, a broken pointer, a contradiction between the skill, its references, and its callers) into the files, re-run anything the fix touched, and list the style items in the hand-off for the user to take or leave. A style item is also a gap in the standards — add the rule to step 3 above (or wherever you keep your standards) in the same pass, so the next skill is drafted right. Don't skip it for a small skill: a skill that passes its own tests and a live dogfood run can still carry real defects only a review catches.
• For formal evals — benchmarked triggering accuracy, baseline-vs-skill runs, description optimization — reach for the native skill-creator plugin (claude-plugins-official marketplace), if you have it. This skill deliberately stays lean and doesn't reimplement that harness; most of these skills are judgment/interaction skills where your own review beats a benchmark.

Guardrails

• One skill = one job; a composite clears a higher bar. If the request is genuinely several responsibilities, recommend one atom each. But only recommend wrapping them in a standing composite when it would chain 3 or more skills — the rule: a 2-skill chain isn't worth a composite, just chain the two ad-hoc. Skip the composite even at 3+ if an early step's value is conditional (only sometimes wanted) — a standing composite hard-codes "always run every step," so conditional-first-step chains stay ad-hoc too. And build it from runs, not foresight: drive a new chain by hand a few times first, logging each run (what you invoked, in what order, what you had to fix up between steps), and that log becomes the composite's spec. Dogfood the philosophy; don't violate it to save a step.
• Don't manufacture complexity. A one-line prose skill (/recommend, /notes) is often exactly the right size. Don't pad a simple skill with sections it doesn't need — right-sizing matters as much as completeness.
• Look before you overwrite. If a skill by that name already exists, read it first; if it contradicts how the request described it, surface that rather than clobbering it. Confirm before overwriting existing work.
• No new dependencies without a supply-chain vet (maintainer reputation, age, install scripts, advisories) — skills rarely need any, but if a scripts/ helper would pull one in, check first.