Scaffold a new skill that follows this repo's conventions — interviews for purpose, trigger phrases, and tool needs, then writes `.claude/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`.
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/<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.
.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.
$0 (or ask). Reject non-kebab-case, names that collide with an existing .claude/skills/<name>/, or names that shadow a built-in (commit, learn, …) — ls .claude/skills/ and stop if taken.templates/skill-template.md for the canonical structure and the frontmatter-field reference.Glob .claude/skills/*/SKILL.md, then Read the closest matches) so the new skill borrows real conventions, not invented ones.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:
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.--token).Bash? fan out to a subagent (Agent)? hit the web via WebSearch/WebFetch? Only declare what it actually uses.confidential-data.md.post-flight-verification.md).Echo a one-paragraph design brief back for confirmation before writing.
Write .claude/skills/<name>/SKILL.md from the template, with these gold-standard sections:
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.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.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):
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. 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.[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.
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 <!-- surface-sync-table: skills --> 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:
| `/<name>` | <what it does> | (the gated table).## All Skills appendix table in guide/workflow-guide.qmd. That table has no surface-sync marker, so no gate catches a missing row.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.INCLUDE in scripts/sync-agent-skills.py and run python3 scripts/sync-agent-skills.py; otherwise add it to EXCLUDE with the reason. Left in neither list, it stays Claude-only and check-skill-integrity.py prints a P2 reminder../scripts/check-surface-sync.sh and python3 scripts/check-skill-integrity.py — both must exit 0./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.
.claude/skills/<name>/SKILL.md.--dry-run: emit the proposed SKILL.md to chat only and 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.--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.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 — capture a session discovery (the lighter sibling); --from-learn upgrades its output..claude/skills/coauthor-brief/SKILL.md — a gold-standard skill to imitate (interview → write → flags → exit-behavior shape)..claude/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./learn. This skill designs an interface; /learn records a finding../scripts/check-surface-sync.sh) is a deliberate human step so the surface gate is never silently satisfied..claude/agents/, a rule in .claude/rules/./commit's job; a merge is the user's call.pedrohcgs/claude-code-my-workflow
fe70774
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.