Claude Code Commands - Meta Reference
This skill provides the definitive reference for creating Claude Code slash commands. Use this when building new commands or improving existing command patterns.
2026 note: Custom slash commands have been merged into skills. Prefer
.claude/skills/<name>/SKILL.md
for new work;
.claude/commands/<name>.md
remains supported for legacy single-file commands.
When to Use This Skill
Use this skill when you need to:
- Create a new slash command for repeated workflows
- Add handling to commands
- Invoke agents from commands
- Include file context or bash output in commands
- Organize commands for team sharing
Quick Reference
| Component | Purpose | Example |
|---|
| Filename | Command name | -> |
| Content | Prompt template | Instructions for Claude |
| User input | -> |
| , | Positional args | -> |
| Session tracking | logs/${CLAUDE_SESSION_ID}.log
|
| Include file | includes file contents |
| Bash output (preprocessing) | includes command output |
Command Locations
Claude Code supports both legacy command files and skill-based commands. Skills are the recommended format because they support frontmatter controls and bundled supporting files.
| Location | Scope | Creates | Use For |
|---|
.claude/skills/<name>/SKILL.md
| Project | | Recommended: team-shared commands with supporting files |
~/.claude/skills/<name>/SKILL.md
| Personal | | Personal cross-project commands |
.claude/commands/<name>.md
| Project | | Legacy single-file commands (still supported) |
~/.claude/commands/<name>.md
| Personal | | Legacy personal commands |
packages/*/.claude/skills/<name>/SKILL.md
| Nested | | Monorepo subdirectories |
Nested discovery: Claude automatically discovers
and
in subdirectories when working inside those paths.
Command Structure
Skill-based (recommended):
text
.claude/skills/
|-- review/SKILL.md # /review
|-- test/SKILL.md # /test
`-- deploy/SKILL.md # /deploy
Legacy commands:
text
.claude/commands/
|-- review.md # /review
|-- test.md # /test
`-- deploy.md # /deploy
Command Template (Skill-Based)
markdown
---
name: command-name
description: Brief description for invocation and auto-loading
argument-hint: [path|#pr] [options]
allowed-tools: Read, Grep, Bash(git:*)
disable-model-invocation: false
---
# Command Title
[Clear instructions for what this command does]
User request: $ARGUMENTS
## Steps
1. [First action Claude should take]
2. [Second action]
3. [Third action]
## Output Format
[Specify expected output structure]
Frontmatter Fields (Skills)
| Field | Purpose |
|---|
| Slash command name (kebab-case) |
| When to use this skill/command |
| Hint shown during autocomplete for expected arguments |
| Tools this skill can run without extra prompts |
| If , Claude will not auto-invoke |
| If , hidden from the menu |
| Override the model for this skill |
| Use for isolated execution |
| Subagent used to execute this skill |
| Optional lifecycle hooks for the skill |
Legacy
works for single-file commands; prefer skills if you need frontmatter controls or bundled resources.
allowed-tools Syntax
yaml
allowed-tools: Read, Grep, Bash(git:*)
| Pattern | Meaning |
|---|
| Allow any invocation of that tool |
| Allow with specific prefix only |
| Only git commands |
| Only npm test commands |
$ARGUMENTS Usage
Single Argument
markdown
# Code Review
Review the following file or code for quality, security, and best practices:
$ARGUMENTS
Focus on:
- Code quality issues
- Security vulnerabilities
- Performance concerns
- Best practice violations
Multiple Arguments
markdown
# Compare Files
Compare these two files and explain the differences:
$ARGUMENTS
Provide:
- Line-by-line diff
- Semantic changes
- Impact analysis
Optional Arguments
markdown
# Run Tests
Run tests for the specified scope.
Scope: $ARGUMENTS
If no scope specified, run all tests.
If scope is a file, run tests for that file.
If scope is a directory, run tests in that directory.
Positional Arguments
Use
,
, etc. for specific arguments (like shell scripts):
markdown
# Compare Files
Compare $1 with $2.
Show:
- Line differences
- Semantic changes
- Which version is preferred
File References (@ Prefix)
Include file contents directly in the command with
:
markdown
# Review with Context
Review this code following our standards.
Project standards:
@CLAUDE.md
Code to review:
$ARGUMENTS
Usage:
/review-context src/auth.js
includes CLAUDE.md contents automatically.
Bash Execution (! Prefix)
Execute bash commands and include output with
:
markdown
# Smart Commit
Current status:
!git status --short
Recent commits:
!git log --oneline -5
Staged changes:
!git diff --cached
Generate a commit message for the staged changes.
Usage:
runs git commands and includes their output.
Important: The
syntax is preprocessing - commands execute before the content is sent to Claude. Claude only sees the rendered output with actual data, not the command itself.
Backtick Syntax
For inline execution, use backticks:
markdown
PR diff: !`gh pr diff`
Changed files: !`gh pr diff --name-only`
Command Patterns
Agent Invocation
markdown
# Security Audit
Perform a comprehensive security audit.
Target: $ARGUMENTS
Use the **security-auditor** agent to:
1. Scan for OWASP Top 10 vulnerabilities
2. Check authentication patterns
3. Review data validation
4. Analyze dependencies
Provide a severity-rated findings report.
Multi-Agent Orchestration
markdown
# Fullstack Feature
Build a complete fullstack feature.
Feature: $ARGUMENTS
Workflow:
1. Use **prd-architect** to clarify requirements
2. Use **system-architect** to design approach
3. Use **backend-engineer** for API implementation
4. Use **frontend-engineer** for UI implementation
5. Use **test-architect** for test coverage
Coordinate between agents and ensure integration.
Validation Command
markdown
# Pre-Commit Check
Validate changes before commit.
Files: $ARGUMENTS (or all staged files if not specified)
Checklist:
- [ ] All tests pass
- [ ] No linting errors
- [ ] No type errors
- [ ] No console.log statements
- [ ] No TODO comments
- [ ] No hardcoded secrets
Return READY or BLOCKED with details.
Command Categories
Development Commands
| Command | Purpose |
|---|
| Code review |
| Run/write tests |
| Debug issues |
| Improve code |
Architecture Commands
| Command | Purpose |
|---|
| System design |
| Review architecture |
| Write tech spec |
Security Commands
| Command | Purpose |
|---|
| Security audit |
| Find exposed secrets |
| Check dependencies |
Operations Commands
| Command | Purpose |
|---|
| Deployment workflow |
| Rollback changes |
| Incident response |
Naming Conventions
| Pattern | Example | Use For |
|---|
| | Simple actions |
| | Specific targets |
| | Domain-prefixed |
| | Tool-specific |
Command vs Agent vs Skill
| Feature | Command | Agent | Skill |
|---|
| Trigger | User types | Claude decides | Claude loads |
| Purpose | Quick shortcuts | Complex work | Knowledge |
| Statefulness | Stateless | Maintains context | Reference only |
| Length | Short prompt | Full instructions | Detailed docs |
Flow: User -> Command -> Agent -> Skill
Invocation Control
Control who can invoke commands using frontmatter:
| Frontmatter | User Invokes | Claude Invokes | Use Case |
|---|
| (default) | Yes () | Yes (auto) | General commands |
disable-model-invocation: true
| Yes () | No (never) | Deploy, commit, dangerous ops |
| No (hidden) | Yes (auto) | Background knowledge only |
Example: User-Only Command
yaml
---
description: Deploy to production
disable-model-invocation: true
allowed-tools: Bash(kubectl:*), Bash(docker:*)
---
# Deploy
Deploy $ARGUMENTS to production cluster.
Claude cannot auto-invoke this - user must explicitly type
.
Context Budget
Default skill/command description budget: 15,000 characters.
If many commands are excluded from context:
bash
export SLASH_COMMAND_TOOL_CHAR_BUDGET=20000
Check with
command for warnings about excluded skills.
Best Practices
DO
markdown
# Good Command
Clear, specific instructions.
Target: $ARGUMENTS
1. First, analyze the target
2. Then, perform action X
3. Finally, output result Y
Expected output:
- Summary of findings
- Actionable recommendations
DON'T
markdown
# Bad Command
Do stuff with $ARGUMENTS.
Make it good.
Advanced Patterns
Conditional Logic
markdown
# Smart Review
Review target: $ARGUMENTS
If target is a PR number (e.g., #123):
- Fetch PR details with `gh pr view`
- Review all changed files
If target is a file path:
- Review that specific file
If target is a directory:
- Review all files in directory
Template with Options
markdown
# Generate Tests
Generate tests for: $ARGUMENTS
Options (parsed from arguments):
- `--unit` - Unit tests only
- `--e2e` - E2E tests only
- `--coverage` - Include coverage report
Default: Generate both unit and E2E tests.
Navigation
Resources
- references/command-patterns.md - Common patterns
- references/command-examples.md - Full examples
- data/sources.json - Documentation links
Related Skills
- ../claude-code-agents/SKILL.md - Agent creation
- ../claude-code-skills/SKILL.md - Skill creation
- ../claude-code-hooks/SKILL.md - Hook automation