--- name: new-skill description: Scaffold a new skill that follows this repo's conventions — interviews for purpose, trigger phrases, and tool needs, then writes `.claude/skills//SKILL.md` from the skill template with frontmatter and body that pass the integrity gates on first try. Use when user says "write a skill", "scaffold a skill", "create a new skill", "I keep doing X, make it a skill", "new slash command", or "turn this workflow into a skill". NOT for capturing a one-off session discovery — that is `/learn`. argument-hint: "[skill-name (kebab-case)] [--from-learn] [--dry-run]" allowed-tools: ["Read", "Write", "Glob", "Grep", "Bash"] disable-model-invocation: true effort: medium --- # /new-skill — Author a Convention-Compliant Skill Scaffold a new skill the way this template's gold-standard skills are written: a **deep module behind a simple interface** (Ousterhout, *A Philosophy of Software Design* — "deep modules": a small surface that hides substantial implementation). The user supplies a fuzzy intent; this skill interviews it into a tight spec, then writes `.claude/skills//SKILL.md` with frontmatter and body that are mutually consistent — so `check-skill-integrity.py` and `check-surface-sync.sh` pass without a second pass. Adapted from the *write-a-skill* pattern in [mattpocock/skills](https://github.com/mattpocock/skills), reshaped to this repo's frontmatter, section, and gate conventions. ## When to use - You keep re-explaining the same 3+ step workflow to Claude and want it captured as a reusable slash command. - You need a domain-specific check or output format (citation style, replication gate, a new review lens). - You want a new skill that is consistent with the 40+ siblings in `.claude/skills/` — same sections, same cross-reference style, same gate-passing frontmatter. **Use `/learn` instead** when you just discovered something non-obvious *this session* and want it preserved — `/learn` captures a discovery; `/new-skill` deliberately designs an interface. With `--from-learn`, this skill upgrades a `/learn`-shaped stub into a full convention-compliant skill. ## Phases ### Phase 0 — Resolve the name and check for collisions 1. Take the kebab-case name from `$0` (or ask). Reject non-kebab-case, names that collide with an existing `.claude/skills//`, or names that shadow a built-in (`commit`, `learn`, …) — `ls .claude/skills/` and stop if taken. 2. Read [`templates/skill-template.md`](../../../templates/skill-template.md) for the canonical structure and the frontmatter-field reference. 3. Skim 2-3 sibling skills near the intended domain (e.g. `Glob .claude/skills/*/SKILL.md`, then `Read` the closest matches) so the new skill borrows real conventions, not invented ones. ### Phase 1 — Interview (collect everything *before* writing) A skill cannot stop to ask mid-write, so gather all interactivity up front (the [orchestrator-protocol.md](../../rules/orchestrator-protocol.md) RUN_CONFIG discipline). Ask, in one batch: 1. **Purpose** — one sentence: what does it accomplish and why does it exist? 2. **When it should fire** — the 2-4 *situations* a user is in when they need it (e.g. "preparing a submission", "a number changed between runs"), plus one or two example phrasings. These become the `description`'s "Use when…" clause. Name intent categories rather than enumerating near-synonyms: every model-invocable description is loaded into every session, and `description` + `when_to_use` are truncated in the skill listing (at 1,536 characters per the Claude Code skills docs, 2026-09) — put the key use first. 3. **Inputs / arguments** — positional args and any **flags** (each must become a documented `--token`). 4. **Tools** — does the body Read? Write? Grep/Glob? run `Bash`? fan out to a subagent (Agent)? hit the web via `WebSearch`/`WebFetch`? Only declare what it actually uses. 5. **Output** — a written file (where?), a chat report, or an in-place edit? Should it be read-only? 6. **Scope boundary** — the one or two things it explicitly does NOT do (and which sibling owns those). Echo a one-paragraph **design brief** back for confirmation before writing. ### Phase 2 — Write the SKILL.md (deep module, simple interface) Write `.claude/skills//SKILL.md` from the template, with these gold-standard sections: - Frontmatter: `name`, `description` (third person — what it does, then when to use it by intent category), `argument-hint`, `allowed-tools`, and `effort` only if the skill genuinely needs a level other than the session's (see `model-routing.md` § effort — a skill pin *overrides* the session, downward as well as up). Add `disable-model-invocation: true` if it writes a persistent, load-bearing file (template's "when to disable" rule) — and note that other skills then cannot invoke it; they must Read its `SKILL.md` and follow it. - Body sections: **When to use**; the **goal and deliverable**; the **constraints, each with its reason**; **how to verify it is done**; an **Output / report format**; **Exit behavior**; **Cross-references** (to real sibling files); **What this skill does NOT do**; and a **## Flags** section if any flags are advertised. Number phases only where order genuinely matters (interview before writing, verify before reporting) — current models plan well, and a step-by-step script for a judgment task makes the output worse, not safer. - Keep `SKILL.md` readable in one sitting (well under ~500 lines). Move long rubrics, worked examples, and reference tables into files beside it (e.g. `references/`) and link them, so they load only when needed. - Keep the *interface* small (a few args) and the *implementation* deep (the phases carry the weight) — resist exposing a knob for every internal choice. ### Phase 3 — Enforce parity so the gates pass first try `check-skill-integrity.py` enforces two parities this phase must satisfy (`scripts/check-skill-integrity.py` is the checker; `./scripts/backtest.sh` runs every gate): - **Flag parity (both directions).** Every flag in `argument-hint` MUST appear in the body as a bare-backticked token, and every flag documented in the body MUST appear in `argument-hint`. So `--from-learn` and `--dry-run` are listed in the hint *and* described under `## Flags`. A stale hint flag fails the gate as surely as a missing one. - **allowed-tools parity.** The body may only invoke tools listed in `allowed-tools`. If a phase fans out to a subagent, `Agent` must be in the list; if it never does, do not list it. This skill lists exactly `Read, Write, Glob, Grep, Bash` — the tools its phases use; it does no subagent fan-out. - **Anchor resolution.** Internal `[text](path#anchor)` links must resolve — only link to headings that exist. Run `python3 scripts/check-skill-integrity.py --verbose` and fix any P0/P1 before declaring done. ### Phase 4 — Remind: register the surface (table-row and count gates) The skill is NOT discoverable to a reader until it is listed, and the inventory counts must match what is on disk. `check-surface-sync.sh` runs two surface checks. The **table-row gate** requires the `` table in `README.md` to have exactly one data row per skill on disk. The **count assertions** require every inventory phrasing that states a skill count (e.g. "N agents, M skills, …") in `README.md`, `CLAUDE.md`, `guide/workflow-guide.qmd`, both rendered guide copies (`guide/workflow-guide.html`, `docs/workflow-guide.html`), `docs/index.html`, `templates/skill-template.md` and `.claude/skills/commit/SKILL.md` to equal the number of skill directories. A new skill fails the gate if it has no row or if the counts are not bumped. REMIND the user to: 1. Add a row to the **README.md** skills table: `` | `/` | | `` (the gated table). 2. Add a row to the guide's `## All Skills` appendix table in `guide/workflow-guide.qmd`. That table has no surface-sync marker, so no gate catches a missing row. 3. Bump every skill count. Run `python3 scripts/check-surface-sync.py`: each `asserts N skills (actual: M)` line names a file:line to update. For the guide, edit `guide/workflow-guide.qmd`, then `quarto render guide/workflow-guide.qmd`, `cp guide/workflow-guide.html docs/workflow-guide.html` and `./scripts/stamp-render.sh`, so both HTML copies carry the new count and the staleness gate stays green. 4. Optionally add the skill to CLAUDE.md's "Skills Quick Reference" bullet list — only if it belongs among the most-used skills; no gate checks that list. 5. Run `./scripts/check-surface-sync.sh` and `python3 scripts/check-skill-integrity.py` — both must exit 0. 6. Check what the skill costs and whether it fires: `/skill-doctor` shows its context cost and usage; `./scripts/run-skill-eval.sh` runs its eval cases once they exist. Print the ready-to-paste README row so the user can drop it in. ## Output / report format - A new file at `.claude/skills//SKILL.md`. - A chat summary: the resolved name, the design brief, the gate results (integrity + a reminder that surface-sync still needs the README skills-table row and the count bumps), and the paste-ready README row. - With `--dry-run`: emit the proposed SKILL.md to chat only and write nothing. ## Exit behavior - **Skill written, gates green:** exit 0 with the path, the README row, and the explicit "now add that row, bump the counts, and run the two checks" reminder. - **Name collision or non-kebab-case:** stop in Phase 0 with the conflict named; write nothing. - **`check-skill-integrity.py` reports P0/P1:** fix in-place and re-run before returning; never hand back a skill that fails its own gate. - **`--dry-run`:** print the draft, write nothing, exit 0. ## Flags - `--from-learn` — Seed the interview from an existing `/learn`-style stub (or the current session's discovery) and upgrade it into a full convention-compliant skill rather than starting blank. - `--dry-run` — Produce the SKILL.md content in chat for review without writing it to disk or touching any surface table. ## Cross-references - [`templates/skill-template.md`](../../../templates/skill-template.md) — the canonical structure, frontmatter-field reference, and the "when to set `disable-model-invocation`" rule this skill follows. - [`.claude/skills/learn/SKILL.md`](../learn/SKILL.md) — capture a session discovery (the lighter sibling); `--from-learn` upgrades its output. - [`.claude/skills/coauthor-brief/SKILL.md`](../coauthor-brief/SKILL.md) — a gold-standard skill to imitate (interview → write → flags → exit-behavior shape). - [`.claude/rules/orchestrator-protocol.md`](../../rules/orchestrator-protocol.md) — why the interview collects all interactivity *before* writing. - `scripts/check-skill-integrity.py` and `scripts/check-surface-sync.sh` (both run by `scripts/backtest.sh`) — the gates this skill is built to pass on the first try. ## What this skill does NOT do - **Capture a session discovery** — that is [`/learn`](../learn/SKILL.md). This skill designs an interface; `/learn` records a finding. - **Edit the README skills table (or CLAUDE.md's quick-reference list) for you.** It *prints* the README row and reminds you; registering it (and re-running `./scripts/check-surface-sync.sh`) is a deliberate human step so the surface gate is never silently satisfied. - **Write agents, rules, or hooks.** It scaffolds a skill only; an agent goes in `.claude/agents/`, a rule in `.claude/rules/`. - **Commit anything.** Branch, commit and PR are [`/commit`](../commit/SKILL.md)'s job; a merge is the user's call.