create-command

Create a slash command: a prompt the user invokes by typing /<name>. Make it do one well-scoped action, accept its arguments cleanly, and read like a tight instruction set. Then regenerate the derived files and validate.

Source layout is commands/<category>/<name>/COMMAND.md. Commands are file-layout: the folder must contain only COMMAND.md, because it installs as the single file .claude/commands/<name>.md. The /<name> the user types comes from that filename. The category is the folder; registry.json and the README catalog are generated by pnpm gen. Never hand-edit generated files.

Hard rules: never break these

• One command, one action. A command is something the user deliberately triggers (/write-tests, /deploy). Keep it to a single, well-scoped job.
• File layout: only COMMAND.md. No companion files; pnpm gen rejects extras because the command installs as one file.
• Gate side effects. If the command commits, pushes, deploys, deletes, or sends anything, state exactly what will happen and confirm before doing it. Consider disable-model-invocation: true so only the user can fire it.
• name is globally unique and equals the folder name, kebab-case.
• Never hand-write registry.json or the README catalog. Run pnpm gen.
• No AI/co-author mentions anywhere in the command or its output.

Step 1: Define the command

• The one action it performs, in a sentence.
• The arguments it takes, if any, and what each means.
• Who invokes it. User-only (set disable-model-invocation: true) for anything with side effects or timing you want to control; both you and Claude for safe, read-only helpers.

Step 2: Scaffold it

From the repo root:

pnpm new --type command --category <category> --name <name> --description "<what it does>"

Current command categories: academic, documentation, engineering, productivity, review, security, testing, version-control (run ls commands for the live list). Reuse one or add a new folder if a different family is justified. The scaffolder enforces kebab-case and global name uniqueness and regenerates the registry.

Step 3: Write the frontmatter

Required: name, description. Useful optional fields:

Write description third person, leading with the action; avoid a : (it is YAML).

Step 4: Write the body with arguments

The markdown body is the prompt that runs when the command is invoked. Address the agent, imperative. Wire in input:

• $ARGUMENTS expands to everything the user typed after the command.
• $1, $2, … expand to positional arguments.
• A leading ! line runs a shell command and inlines its output (needs allowed-tools), e.g. !`git diff --stat` to ground the prompt in live state.
• @path/to/file pulls a file's contents into the prompt.

If the command takes arguments but the body omits $ARGUMENTS, Claude Code appends what the user typed automatically, but referencing it explicitly reads better.

Step 5: Regenerate and validate

pnpm gen
pnpm validate

Fix the source COMMAND.md if validation complains; never patch generated output.

Step 6: Review against the bar

• Invoking /<name> does the one action cleanly, with arguments handled.
• Side effects are gated and, where appropriate, disable-model-invocation: true is set.
• The folder contains only COMMAND.md.
• pnpm validate passes and the README catalog shows the new row.

Report the command's path, category, how it's invoked, and the validation result. Leave committing to the user.