| name | new-skill |
| description | Scaffold a new skill that follows this repo's conventions — interviews for purpose, trigger phrases, and tool needs, then writes `.agents/skills/<name>/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`. |
$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 .agents/skills/<name>/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, reshaped to this repo's frontmatter, section, and gate conventions.
When to use
- You keep re-explaining the same 3+ step workflow to Codex 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
.agents/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
- Take the kebab-case name from
$0 (or ask). Reject non-kebab-case, names that collide with an existing .agents/skills/<name>/, or names that shadow a built-in (commit, learn, …) — ls .agents/skills/ and stop if taken.
- Read
templates/skill-template.md for the canonical structure and the frontmatter-field reference.
- Skim 2-3 sibling skills near the intended domain (e.g.
Glob .agents/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 RUN_CONFIG discipline). Ask, in one batch:
- Purpose — one sentence: what does it accomplish and why does it exist?
- Trigger phrases — the 4-7 quoted phrases a user would actually say. These become the
description's "Use when…" clause and are what makes the skill auto-discoverable.
- Inputs / arguments — positional args and any flags (each must become a documented
--token).
- Tools — does the body Read? Write? Grep/Glob? run
Bash? fan out to a subagent (the Task tool)? hit the web via WebSearch/WebFetch? Only declare what it actually uses.
- Output — a written file (where?), a chat report, or an in-place edit? Should it be read-only?
- 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 .agents/skills/<name>/SKILL.md from the template, with these gold-standard sections:
- Frontmatter:
name, description (third person, with the quoted trigger phrases), documented inputs, declared capabilities, effort. Add disable-model-invocation: true if it writes a persistent, load-bearing file (template's "when to disable" rule).
- Body sections: When to use, numbered Phases (or Steps), 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.
- 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 (.claude/scripts/ hosts the gate runners; scripts/check-skill-integrity.py is the checker):
- Flag parity (both directions). Every flag in
documented inputs MUST appear in the body as a bare-backticked token, and every flag documented in the body MUST appear in documented inputs. 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.
- declared capabilities parity. The body may only invoke tools listed in
declared capabilities. If a phase fans out to a subagent (the Task tool), that tool 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, and 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 gate)
The skill is NOT discoverable to a reader until it is listed. check-surface-sync.sh runs a table-row gate: the <!-- surface-sync-table: skills --> tables in README.md and AGENTS.md must have exactly one data row per skill on disk. Adding a skill without a row fails the gate.
REMIND the user to:
- Add a row to the AGENTS.md "Skills Quick Reference" table:
| `/<name> [args]` | <what it does> |.
- Add a row to the README.md skills table:
| `/<name>` | <what it does> |.
- Run
./scripts/check-surface-sync.sh and python3 scripts/check-skill-integrity.py — both must exit 0.
Print the two ready-to-paste rows so the user can drop them in.
Output / report format
- A new file at
.agents/skills/<name>/SKILL.md.
- A chat summary: the resolved name, the design brief, the gate results (integrity + a reminder that surface-sync still needs the two table rows), and the two paste-ready table rows.
- 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 two table rows, and the explicit "now add those rows + 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
What this skill does NOT do
- Capture a session discovery — that is
$learn. This skill designs an interface; $learn records a finding.
- Edit the README / AGENTS.md surface tables for you. It prints the two rows and reminds you; registering them (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
.codex/workflows/agents/, a rule in .codex/rules/.
- Commit anything. Branch / PR / merge is
$commit's job.
