4.1 — Anatomy of a slash command
Slash commands are Markdown files that Claude Code loads and runs as specialized prompts. Unlike native commands (/clear, /compact, /help), custom slash commands are files you create, share via Git, and use to encapsulate repeated workflows in a single invocation.
File format
A slash command is an .md file placed in one of the locations recognized by Claude Code. The file can start with an optional YAML frontmatter, followed by the Markdown content that forms the prompt:
---
description: Generate a unit test for the target file
argument-hint: [file-path]
allowed-tools: Read, Write, Bash(npm:*)
---
Read the file @$1 and generate a complete unit test.
Use the test framework already present in the project.
Run the tests to verify they pass.
The frontmatter is entirely optional. A file containing only Markdown works, Claude Code interprets it as a raw prompt. But the frontmatter adds structure: description shows up in autocomplete, argument-hint guides the user, and allowed-tools restricts the tools available during execution.
Command locations
- Project:
.claude/commands/, versioned in Git, shared with the team - User:
~/.claude/commands/, personal, available across all projects - Plugin:
, distributed through a plugin/commands/
Invocation uses /file-name (without the .md extension). Sub-directories become namespaces: .claude/commands/test/unit.md is invoked with /test:unit.
Key takeaways
• A slash command = a Markdown file with a reusable prompt
• YAML frontmatter is optional but adds description, allowed tools and argument hints
• Three locations: project (.claude/commands/), user (~/.claude/commands/), plugin
• Sub-directories create namespaces (invocation with :)