writing-commands

Writing Commands

Slash commands live at <plugin-name>/commands/<command-name>.md. The file name (without .md) becomes the slash command: commands/review.md → /review.

File format

---
description: One short sentence shown in the slash-command picker.
argument-hint: "<expected arguments, e.g. [path]>"   # optional
allowed-tools: Read, Grep, Bash                      # optional
---

<Body: instructions Claude should follow when the user invokes this command.
Use $ARGUMENTS to reference everything the user typed after the command name.>

Frontmatter rules

• description (required): shown in the slash-command picker. Keep it short and action-oriented.
• argument-hint (optional): placeholder shown to the user, e.g. "[file] [message]".
• allowed-tools (optional): comma-separated tool list to restrict what the command can do. Omit to inherit the session's tools.

There is no name field — the file name IS the command name. Use kebab-case file names.

Body rules

• Write the body as instructions to Claude, not as user-facing docs.
• Reference user input with $ARGUMENTS.
• Be explicit about the expected output format if it matters.
• If the command is complex, have it delegate to an agent or skill rather than embedding a long workflow inline.

Manifest wiring

{
  "commands": ["./commands/<command-name>.md"]
}

Checklist

• File name is kebab-case; it becomes the slash command.
• description is one short, action-oriented sentence.
• argument-hint is present when the command takes arguments.
• allowed-tools is set when the command should be sandboxed.
• Body addresses Claude and uses $ARGUMENTS if applicable.
• File is listed in plugin.json commands.