Commands

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.

---
description: Fix a GitHub issue by number, following team coding standards
argument-hint: [issue-number]
allowed-tools: Read, Edit, Write, Bash(gh *), Bash(npm test *)
model: sonnet
---

Fix GitHub issue $0 following our coding standards.

## Context
- PR diff: !`gh pr diff`
- Issue details: !`gh issue view $0`

## Steps
1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

Session: ${CLAUDE_SESSION_ID}

Frontmatter Fields

string

required

What the command does. Shown in autocomplete and used by Claude for auto-discovery.

string

Hint shown during autocomplete (e.g., [issue-number], [filename]).

string

Tools allowed without permission prompts when this command is active.Examples: Read, Edit, Write, Bash(npm run *), WebFetch(domain:*)

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:

Variable	Description	Example
`$ARGUMENTS`	All arguments passed to the command	`/fix-issue urgent` → `"urgent"`
`$ARGUMENTS[N]`	Specific argument by index	`$0`, `$1`, `$2`
`$N`	Shorthand for `$ARGUMENTS[N]`	Same as above
`${CLAUDE_SESSION_ID}`	Current session identifier	Unique 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

Create a command file

Create a markdown file in .claude/commands/ with YAML frontmatter:

mkdir -p .claude/commands
touch .claude/commands/my-workflow.md

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

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

Feature	Commands	Agents	Skills
Purpose	Entry point	Task execution	Reusable knowledge
Invocation	`/command-name`	`Task(subagent_type)`	`/skill-name` or `Skill(skill)`
Location	`.claude/commands/`	`.claude/agents/`	`.claude/skills/`
Best for	User-initiated workflows	Specialized task execution	Background 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:

Project (highest priority)

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

Personal

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

Plugin (lowest priority)

<plugin>/commands/ — Commands from installed plugins

Best Practices

Keep commands focused

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

Use descriptive names

Command names appear in autocomplete and should clearly indicate what they do.Good: /fix-github-issue, /weather-orchestratorBad: /cmd1, /thing

Leverage dynamic context

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`

Document the workflow

Add clear step-by-step instructions in the command body. This helps Claude understand the workflow and makes commands self-documenting for your team.

Set appropriate models

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.

Cross-Links

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

Get Started

Core Concepts

Best Practices

Workflows & Patterns

Implementation Examples

What Are Commands?

Why Commands Matter

Frontmatter Fields

String Substitutions

How to Use Commands

Real Example: Weather Orchestrator

Commands vs Agents vs Skills

Scope and Priority

Best Practices

Subdirectories

Cross-Links

Subagents

Skills

Orchestration Workflow

Commands Best Practice

Further Reading

​What Are Commands?

​Why Commands Matter

​Frontmatter Fields

​String Substitutions

​How to Use Commands

​Real Example: Weather Orchestrator

​Commands vs Agents vs Skills

​Scope and Priority

​Best Practices

​Subdirectories

​Cross-Links

Subagents

Skills

Orchestration Workflow

Commands Best Practice

​Further Reading

What Are Commands?

Why Commands Matter

Frontmatter Fields

String Substitutions

How to Use Commands

Real Example: Weather Orchestrator

Commands vs Agents vs Skills

Scope and Priority

Best Practices

Subdirectories

Cross-Links

Further Reading