Slash-Command Frontmatter Reference

What a slash command is

A Claude Code slash command is a markdown file whose body is a prompt template. Typing /<name> in Claude Code runs that template as a message. The file lives at commands/<name>.md; project commands go in .claude/commands/, user commands in ~/.claude/commands/, and plugins ship them in a commands/ directory. Optional YAML frontmatter at the top tunes how the command behaves. The authoritative spec is the Claude Code slash-commands documentation; this page is a practical companion.

A complete example

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [message]
description: Create a git commit with a generated message
model: sonnet
---

Create a git commit.

Current status: !`git status`
Current diff: !`git diff HEAD`

If the user passed a message, use it: $ARGUMENTS
Otherwise write a concise message describing the change. Then run the commit.

Frontmatter keys

All of these are optional — a slash command with no frontmatter at all is valid.

• allowed-tools — a comma-separated list of tools the command may use. Entries can be bare names (Read) or scoped (Bash(git add:*), which permits only git add invocations). Omit the key to inherit the conversation's tools.
• argument-hint — text shown after the command name in the UI, e.g. [message] or [pr-number]. Set this whenever your template reads arguments, so users know what to type.
• description — a short summary shown in /help and in theSlashCommand tool listing. Strongly recommended; without it the command is harder to discover.
• model — one of sonnet, opus, haiku, or omitted to inherit the conversation's model. Useful when a command does cheap, mechanical work and you want it on a smaller model.
• disable-model-invocation: true — prevents Claude from running the command itself via the SlashCommand tool. The user can still type it manually. Use this for commands with side effects you only want triggered explicitly.

Body placeholders

The body is plain markdown plus a few special substitutions, evaluated when the command runs:

• $ARGUMENTS — everything the user typed after the command name, as one string. /commit fix the build → $ARGUMENTS becomes fix the build.
• $1, $2, … — individual positional arguments, split on whitespace. Handy when a command takes a fixed set of arguments.
• !`command` — runs a shell command and inlines its output into the prompt. !`git status` embeds the current status. The command must be permitted by allowed-tools.
• @path/to/file — includes the contents of a file at that path. Useful for templates that should always see a particular config or spec.

Differences from sub-agent frontmatter

The keys look similar but are not the same. Sub-agents use name, tools (note: no hyphen), and color; slash commands use allowed-tools (hyphenated), argument-hint, and disable-model-invocation, and have no name key at all (the filename is the name). Both support description and model. If you're unsure which artifact you actually want, read sub-agent vs. slash command; for the agent side, see what is a sub-agent.

Common mistakes

• Using tools: instead of allowed-tools:. Slash commands use the hyphenated key.
• Referencing $ARGUMENTS with no argument-hint. It still works, but users can't tell the command takes input.
• Running !`cmd` without permitting it. The shell call must be covered by allowed-tools, e.g. Bash(git status:*).
• A non-kebab-case filename. The filename is the command name, so commands/My Command.md won't give you /my-command.

Generate one with a form

Rather than memorising which keys are hyphenated, use the Claude Code Agent & Slash-Command Builder: switch it to “Slash command”, fill in the fields, and it assembles a correct commands/<name>.md file with a live preview, flags unrecognised tool entries, and nudges you to add an argument-hint when your template uses arguments. Copy or download the result straight into your project or plugin.