Author slash command
What you'll learn
A slash command is a saved prompt you invoke with `/name`. Live in `.claude/commands/` (project) or `~/.claude/commands/` (personal). Frontmatter for metadata, body for the prompt.
- Slash command = reusable prompt expansion, invoked via `/name`.
- Project: `.claude/commands/<name>.md` (checked in). Personal: `~/.claude/commands/<name>.md`.
- Frontmatter: description, argument-hint, allowed-tools. Body = the prompt template.
Slash commands are reusable prompt expansions. A user types `/command` and the harness substitutes the command file's body as the user message — sometimes templated with arguments, often pre-filled with project context. They're the lightest-weight mechanism for codifying a recurring on-demand workflow.
File location decides scope. **Project-shared**: `.claude/commands/<name>.md` — checked into the repo, shared across the team, the team's standard workflows. **Personal**: `~/.claude/commands/<name>.md` — your personal commands across all projects. Same file format; different visibility.
Anatomy: optional YAML frontmatter (`description:`, `argument-hint:`, `allowed-tools:`) and a markdown body that becomes the prompt. The frontmatter description is what shows up in the slash-command menu — vague descriptions hurt discoverability the same way vague tool descriptions cause wrong-tool-pick (B4.4). `argument-hint:` documents what the user passes; the body can reference `$ARGUMENTS` (or named args).
When to reach for a slash command vs a Skill: slash commands are *prompt-only*. They expand into a user message, period. If you need bundled supporting files, asset references, scripts, or menu UX with rich metadata, that's a Skill (B7.x). The slash command sweet spot is 'one-paragraph repeated workflow that needs to be one keystroke instead of three sentences typed each time.'
Key points
- Slash command = reusable prompt expansion, invoked via `/name`.
- Project: `.claude/commands/<name>.md` (checked in). Personal: `~/.claude/commands/<name>.md`.
- Frontmatter: description, argument-hint, allowed-tools. Body = the prompt template.
- Use slash for prompt-only reuse. Use Skill when you need assets / discoverability.
Examples
File: `.claude/commands/release-notes.md` Frontmatter: `description: Generate release notes from the last 7 days of merged PRs` argument-hint: `[start-date]` Body: `Generate release notes for $ARGUMENTS through today. Group by component. List breaking changes first. Use the format in docs/RELEASE_NOTES_TEMPLATE.md.` User invokes: `/release-notes 2026-04-25`.
File: `~/.claude/commands/explain-error.md` Frontmatter: `description: Explain a stack trace pasted in the next message` Body: `Explain this stack trace step-by-step. Identify the root cause and suggest fixes.` User pastes a trace and types `/explain-error`.
Pitfalls
- Vague description in frontmatter ('helper'). Same problem as a vague tool description — discoverability dies.
- Putting a slash command in `~/.claude/commands/` when the team needs it. Move to `.claude/commands/` so it ships with the repo.
- Reaching for a slash command when you need persistent/automatic behaviour. That's CLAUDE.md or a hook, not slash.
- Reaching for a slash command when you need bundled assets. That's a Skill.
Source notes: 00-academy-basics/notes/03-claude-code-101.md
Ask Claude
Build a prompt with this lesson + your question, copy it, and open the Claude Project in a new tab.