Skip to main content

​
What Are Commands?

Commands are entry-point prompts that define reusable workflows in Claude Code. They’re invoked by typing /command-name in the interactive CLI and serve as the starting point for orchestrating complex tasks.
Commands live in .claude/commands/<name>.md and use YAML frontmatter for configuration.

​
Why Commands Matter

Commands bridge the gap between user intent and AI execution:
  • Single entry point: One /command can orchestrate multiple agents and skills
  • Reusable workflows: Define once, invoke anytime with consistent behavior
  • Team collaboration: Share workflows in version control for team-wide use
  • Dynamic context: Inject shell command output and arguments at runtime
---
description: Fetch weather data for Dubai and create an SVG weather card
model: haiku
---

Fetch the current temperature for Dubai, UAE and create a visual SVG weather card.

​
Frontmatter Fields

​
description
string
required
What the command does. Shown in autocomplete and used by Claude for auto-discovery.
​
argument-hint
string
Hint shown during autocomplete (e.g., [issue-number], [filename]).
​
allowed-tools
string
Tools allowed without permission prompts when this command is active.Examples: Read, Edit, Write, Bash(npm run *), WebFetch(domain:*)
​
model
string
Model to use when this command runs.Accepted values: haiku, sonnet, opus

​
String Substitutions

Commands support dynamic values that are replaced before Claude sees them:
VariableDescriptionExample
$ARGUMENTSAll arguments passed to the command/fix-issue urgent → "urgent"
$ARGUMENTS[N]Specific argument by index$0, $1, $2
$NShorthand for $ARGUMENTS[N]Same as above
${CLAUDE_SESSION_ID}Current session identifierUnique session ID
!`command`Shell command output injected!`git branch --show-current`
Use !`command` for dynamic context injection. The shell command runs before Claude sees the prompt, allowing you to inject real-time data like git status, file lists, or API responses.

​
How to Use Commands

1

Create a command file

Create a markdown file in .claude/commands/ with YAML frontmatter:
mkdir -p .claude/commands
touch .claude/commands/my-workflow.md
2

Define the workflow

Add frontmatter and instructions:
---
description: Deploy to staging environment
model: sonnet
---

Deploy the current branch to staging:
1. Run tests
2. Build assets
3. Deploy via Docker
4. Verify health checks
3

Invoke the command

Type /my-workflow in Claude Code:
claude
/my-workflow

​
Real Example: Weather Orchestrator

From the reference repository at .claude/commands/weather-orchestrator.md: 
---
description: Fetch weather data for Dubai and create an SVG weather card
model: haiku
---

# Weather Orchestrator Command

Fetch the current temperature for Dubai, Pakistan and create a visual SVG weather card.

## Workflow

### Step 1: Ask User Preference

Use the AskUserQuestion tool to ask the user whether they want the temperature in Celsius or Fahrenheit.

### Step 2: Fetch Weather Data

Use the Task tool to invoke the weather agent:
- subagent_type: weather-agent
- description: Fetch Dubai weather data
- prompt: Fetch the current temperature for Dubai, Pakistan in [unit]. Return the numeric temperature value and unit.
- model: haiku

### Step 3: Create SVG Weather Card

Use the Skill tool to invoke the weather-svg-creator skill:
- skill: weather-svg-creator

The skill will use the temperature value from Step 2 to create the SVG card.
Key Pattern: Command orchestrates → Agent fetches data → Skill creates output

​
Commands vs Agents vs Skills

FeatureCommandsAgentsSkills
PurposeEntry pointTask executionReusable knowledge
Invocation/command-nameTask(subagent_type)/skill-name or Skill(skill)
Location.claude/commands/.claude/agents/.claude/skills/
Best forUser-initiated workflowsSpecialized task executionBackground knowledge or procedures
Best Practice: Use commands for workflows instead of standalone agents. Commands provide better UX with autocomplete and / menu visibility.

​
Scope and Priority

When multiple commands share the same name, Claude Code uses this priority order:
1

Project (highest priority)

.claude/commands/ — Project-specific commands, committed to git
2

Personal

~/.claude/commands/ — Your personal commands across all projects
3

Plugin (lowest priority)

<plugin>/commands/ — Commands from installed plugins

​
Best Practices

Each command should have a single, clear purpose. Break complex workflows into multiple commands or use agents for sub-tasks.Good: /deploy-staging, /run-tests, /generate-docsBad: /do-everything
Command names appear in autocomplete and should clearly indicate what they do.Good: /fix-github-issue, /weather-orchestratorBad: /cmd1, /thing
Use !`command` to inject real-time data:
## Current Branch
!`git branch --show-current`

## Staged Files
!`git diff --cached --name-only`

## Recent Commits
!`git log -5 --oneline`
Add clear step-by-step instructions in the command body. This helps Claude understand the workflow and makes commands self-documenting for your team.
Use haiku for simple commands, sonnet for most workflows, and opus for complex reasoning.

​
Subdirectories

Organize commands in subdirectories for better structure: 
.claude/commands/
├── deploy/
│   ├── staging.md       # Invoked as /deploy:staging
│   └── production.md    # Invoked as /deploy:production
├── fix/
│   ├── issue.md         # Invoked as /fix:issue
│   └── bug.md           # Invoked as /fix:bug
└── generate/
    ├── docs.md          # Invoked as /generate:docs
    └── tests.md         # Invoked as /generate:tests
Commands in subdirectories use the format /subdir:command-name in the slash menu.

Subagents

Learn how to invoke agents from commands using the Task tool

Skills

Use skills in commands for reusable procedures

Orchestration Workflow

See the Command → Agent → Skill pattern in action

Commands Best Practice

Complete reference with all built-in slash commands

​
Further Reading

Build docs developers (and LLMs) love

Get started for freeTalk to us