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 $ARGUMENTS 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 | review.md -> /review | | Content | Prompt template | Instructions for Claude | | $ARGUMENTS | User input | /review auth.js -> $ARGUMENTS = "auth.js" | | $1, $2 | Positional args | /compare a.js b.js -> $1 = "a.js" | | ${CLAUDE_SESSION_ID} | Session tracking | logs/${CLAUDE_SESSION_ID}.log | | @file | Include file | @CLAUDE.md includes file contents | | !command | Bash output (preprocessing) | !git status 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 | /name | Recommended: team-shared commands with supporting files | | ~/.claude/skills/<name>/SKILL.md | Personal | /name | Personal cross-project commands | | .claude/commands/<name>.md | Project | /name | Legacy single-file commands (still supported) | | ~/.claude/commands/<name>.md | Personal | /name | Legacy personal commands | | packages/*/.claude/skills/<name>/SKILL.md | Nested | /name | Monorepo subdirectories |

Nested discovery: Claude automatically discovers .claude/skills/ and .claude/commands/ in subdirectories when working inside those paths.

Command Structure

Skill-based (recommended):

.claude/skills/
|-- review/SKILL.md           # /review
|-- test/SKILL.md             # /test
`-- deploy/SKILL.md           # /deploy

Legacy commands:

.claude/commands/
|-- review.md                 # /review
|-- test.md                   # /test
`-- deploy.md                 # /deploy

Command Template (Skill-Based)

---
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 | |-------|---------| | name | Slash command name (kebab-case) | | description | When to use this skill/command | | argument-hint | Hint shown during autocomplete for expected arguments | | allowed-tools | Tools this skill can run without extra prompts | | disable-model-invocation | If true, Claude will not auto-invoke | | user-invocable | If false, hidden from the / menu | | model | Override the model for this skill | | context | Use fork for isolated execution | | agent | Subagent used to execute this skill | | hooks | Optional lifecycle hooks for the skill |

Legacy .claude/commands/*.md works for single-file commands; prefer skills if you need frontmatter controls or bundled resources.

allowed-tools Syntax

allowed-tools: Read, Grep, Bash(git:*)

| Pattern | Meaning | |---------|---------| | Tool | Allow any invocation of that tool | | Tool(prefix:*) | Allow with specific prefix only | | Bash(git:*) | Only git commands | | Bash(npm test:*) | Only npm test commands |

$ARGUMENTS Usage

Single Argument

# 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

Usage: /review src/auth.js

Multiple Arguments

# Compare Files

Compare these two files and explain the differences:

$ARGUMENTS

Provide:
- Line-by-line diff
- Semantic changes
- Impact analysis

Usage: /compare old.js new.js

Optional Arguments

# 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.

Usage: /test or /test auth/ or /test login.test.ts

Positional Arguments

Use $1, $2, etc. for specific arguments (like shell scripts):

# Compare Files

Compare $1 with $2.

Show:
- Line differences
- Semantic changes
- Which version is preferred

Usage: /compare old.js new.js -> $1 = "old.js", $2 = "new.js"

File References (@ Prefix)

Include file contents directly in the command with @:

# 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 !:

# 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: /smart-commit runs git commands and includes their output.

Important: The !command 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:

PR diff: !`gh pr diff`
Changed files: !`gh pr diff --name-only`

Command Patterns

Agent Invocation

# 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

# 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

# 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 | |---------|---------| | /review | Code review | | /test | Run/write tests | | /debug | Debug issues | | /refactor | Improve code |

Architecture Commands

| Command | Purpose | |---------|---------| | /design | System design | | /architecture-review | Review architecture | | /tech-spec | Write tech spec |

Security Commands

| Command | Purpose | |---------|---------| | /security-scan | Security audit | | /secrets-check | Find exposed secrets | | /dependency-audit | Check dependencies |

Operations Commands

| Command | Purpose | |---------|---------| | /deploy | Deployment workflow | | /rollback | Rollback changes | | /incident | Incident response |

Naming Conventions

| Pattern | Example | Use For | |---------|---------|---------| | {action} | /review | Simple actions | | {action}-{target} | /security-scan | Specific targets | | {domain}-{action} | /pm-strategy | Domain-prefixed | | {tool}-{action} | /git-commit | Tool-specific |

Command vs Agent vs Skill

| Feature | Command | Agent | Skill | |---------|---------|-------|-------| | Trigger | User types /command | 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 (/name) | Yes (auto) | General commands | | disable-model-invocation: true | Yes (/name) | No (never) | Deploy, commit, dangerous ops | | user-invocable: false | No (hidden) | Yes (auto) | Background knowledge only |

Example: User-Only Command

---
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 /deploy.

Context Budget

Default skill/command description budget: 15,000 characters.

If many commands are excluded from context:

export SLASH_COMMAND_TOOL_CHAR_BUDGET=20000

Check with /context command for warnings about excluded skills.

Best Practices

DO

# 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

# Bad Command

Do stuff with $ARGUMENTS.

Make it good.

Advanced Patterns

Conditional Logic

# 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

# 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.

claude-code-commands