Command Development for Claude Code
Overview
Slash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions. Understanding command structure, frontmatter options, and dynamic features enables creating powerful, reusable workflows.
Key concepts:
- Markdown file format for commands
- YAML frontmatter for configuration
- Dynamic arguments and file references
- Bash execution for context
- Command organization and namespacing
Command Basics
What is a Slash Command?
A slash command is a Markdown file containing a prompt that Claude executes when invoked. Commands provide:
- Reusability: Define once, use repeatedly
- Consistency: Standardize common workflows
- Sharing: Distribute across team or projects
- Efficiency: Quick access to complex prompts
Critical: Commands are Instructions FOR Claude
Commands are written for agent consumption, not human consumption.
When a user invokes /command-name, the command content becomes Claude's instructions. Write commands as directives TO Claude about what to do, not as messages TO the user.
Correct approach (instructions for Claude):
Review this code for security vulnerabilities including:
- SQL injection
- XSS attacks
- Authentication issues
Provide specific line numbers and severity ratings.
Incorrect approach (messages to user):
This command will review your code for security issues.
You'll receive a report with vulnerability details.
The first example tells Claude what to do. The second tells the user what will happen but doesn't instruct Claude. Always use the first approach.
Command Locations
Project commands (shared with team):
- Location:
.claude/commands/ - Scope: Available in specific project
- Label: Shown as "(project)" in
/help - Use for: Team workflows, project-specific tasks
Personal commands (available everywhere):
- Location:
~/.claude/commands/ - Scope: Available in all projects
- Label: Shown as "(user)" in
/help - Use for: Personal workflows, cross-project utilities
Plugin commands (bundled with plugins):
- Location:
plugin-name/commands/ - Scope: Available when plugin installed
- Label: Shown as "(plugin-name)" in
/help - Use for: Plugin-specific functionality
File Format
Basic Structure
Commands are Markdown files with .md extension:
.claude/commands/
├── review.md # /review command
├── test.md # /test command
└── deploy.md # /deploy command
Simple command:
Review this code for security vulnerabilities including:
- SQL injection
- XSS attacks
- Authentication bypass
- Insecure data handling
No frontmatter needed for basic commands.
With YAML Frontmatter
Add configuration using YAML frontmatter:
---
description: Review code for security issues
allowed-tools: Read, Grep, Bash(git:*)
model: sonnet
---
Review this code for security vulnerabilities...
YAML Frontmatter Fields
description
Purpose: Brief description shown in /help
Type: String
Default: First line of command prompt
---
description: Review pull request for code quality
---
Best practice: Clear, actionable description (under 60 characters)
allowed-tools
Purpose: Specify which tools command can use Type: String or Array Default: Inherits from conversation
---
allowed-tools: Read, Write, Edit, Bash(git:*)
---
Patterns:
Read, Write, Edit- Specific toolsBash(git:*)- Bash with git commands only*- All tools (rarely needed)
Use when: Command requires specific tool access
model
Purpose: Specify model for command execution Type: String (sonnet, opus, haiku) Default: Inherits from conversation
---
model: haiku
---
Use cases:
haiku- Fast, simple commandssonnet- Standard workflowsopus- Complex analysis
argument-hint
Purpose: Document expected arguments for autocomplete Type: String Default: None
---
argument-hint: [pr-number] [priority] [assignee]
---
Benefits:
- Helps users understand command arguments
- Improves command discovery
- Documents command interface
disable-model-invocation
Purpose: Prevent SlashCommand tool from programmatically calling command Type: Boolean Default: false
---
disable-model-invocation: true
---
Use when: Command should only be manually invoked
Dynamic Arguments
Using $ARGUMENTS
Capture all arguments as single string:
---
description: Fix issue by number
argument-hint: [issue-number]
---
Fix issue #$ARGUMENTS following our coding standards and best practices.
Usage:
> /fix-issue 123
> /fix-issue 456
Expands to:
Fix issue #123 following our coding standards...
Fix issue #456 following our coding standards...
Using Positional Arguments
Capture individual arguments with $1, $2, $3, etc.:
---
description: Review PR with priority and assignee
argument-hint: [pr-number] [priority] [assignee]
---
Review pull request #$1 with priority level $2.
After review, assign to $3 for follow-up.
Usage:
> /review-pr 123 high alice
Expands to:
Review pull request #123 with priority level high.
After review, assign to alice for follow-up.
Combining Arguments
Mix positional and remaining arguments:
Deploy $1 to $2 environment with options: $3
Usage:
> /deploy api staging --force --skip-tests
Expands to:
Deploy api to staging environment with options: --force --skip-tests
File References
Using @ Syntax
Include file contents in command:
---
description: Review specific file
argument-hint: [file-path]
---
Review @$1 for:
- Code quality
- Best practices
- Potential bugs
Usage:
> /review-file src/api/users.ts
Effect: Claude reads src/api/users.ts before processing command
Multiple File References
Reference multiple files:
Compare @src/old-version.js with @src/new-version.js
Identify:
- Breaking changes
- New features
- Bug fixes
Static File References
Reference known files without arguments:
Review @package.json and @tsconfig.json for consistency
Ensure:
- TypeScript version matches
- Dependencies are aligned
- Build configuration is correct
Bash Execution in Commands
Commands can execute bash commands inline to dynamically gather context before Claude processes the command. This is useful for including repository state, environment information, or project-specific context.
When to use:
- Include dynamic context (git status, environment vars, etc.)
- Gather project/repository state
- Build context-aware workflows
Implementation details:
For complete syntax, examples, and best practices, see references/plugin-features-reference.md section on bash execution. The reference includes the exact syntax and multiple working examples to avoid execution issues
Command Organization
Flat Structure
Simple organization for small command sets:
.claude/commands/
├── build.md
├── test.md
├── deploy.md
├── review.md
└── docs.md
Use when: 5-15 commands, no clear categories
Namespaced Structure
Organize commands in subdirectories:
.claude/commands/
├── ci/
│ ├── build.md # /build (project:ci)
│ ├── test.md # /test (project:ci)
│ └── lint.md # /lint (project:ci)
├── git/
│ ├── commit.md # /commit (project:git)
│ └── pr.md # /pr (project:git)
└── docs/
├── generate.md # /generate (project:docs)
└── publish.md # /publish (project:docs)
Benefits:
- Logical grouping by category
- Namespace shown in
/help - Easier to find related commands
Use when: 15+ commands, clear categories