claude-commands

Create custom slash commands that extend Claude Code with reusable prompts and workflows.

Commands vs Skills

Critical distinction:

| Aspect | Commands (This Skill) | Skills | | -------------- | --------------------------------------- | -------------------------------------- | | Purpose | Reusable prompts invoked by users | Capability packages auto-triggered | | Invocation | Explicit: /command-name args | Automatic (model-triggered by context) | | Location | commands/ directory | skills/ directory with SKILL.md | | Structure | Single .md file | Directory with resources | | Arguments | $1, $2, $ARGUMENTS | No argument system |

Commands are user-initiated. Skills are model-initiated.

---

Quick Start

Basic Command

Create .claude/commands/review.md:

---
description: Review code for best practices and issues
---

Review the following code for:
- Code quality and readability
- Potential bugs or edge cases
- Performance considerations
- Security concerns

Use with: /review

Command with Arguments

Create .claude/commands/fix-issue.md:

---
description: Fix a specific GitHub issue
argument-hint: <issue-number>
---

Fix issue #$1 following our coding standards.
Review the issue, implement a fix, add tests, and create a commit.

Use with: /fix-issue 123

Command with Context

Create .claude/commands/commit.md:

---
description: Create git commit from staged changes
allowed-tools: Bash(git *)
---

## Context
<!-- NOTE: Place "!" before the opening backtick for preprocessing to work -->
Current branch: `git branch --show-current`
Staged changes: `git diff --staged`
Recent commits: `git log --oneline -5`

## Task

Create a commit with a clear message based on the staged changes.

Use with: /commit

---

Workflow Overview

1. Discovery - Define purpose, scope, and target users
2. Design - Choose features and configuration
3. Implementation - Write frontmatter and content
4. Validation - Verify against quality standards

---

Stage 1: Discovery

Before writing code, clarify:

• Purpose: What task does this command automate?
• Scope: Project-specific or personal workflow?
• Arguments: What inputs does it need?
• Tools: What operations will it perform?

Key questions:

• Will this be shared with the team (project) or personal use?
• Does it require bash execution or file references?
• Should tool access be restricted for safety?

---

Stage 2: Design

Command Scopes

| Scope | Location | Visibility | Use Case | |-------|----------|------------|----------| | Project | .claude/commands/ | Team via git | Shared workflows | | Personal | ~/.claude/commands/ | You only | Individual preferences | | Plugin | <plugin>/commands/ | Plugin users | Distributed via marketplace |

Project commands show "(project)" in /help. Personal show "(user)".

Core Features

| Feature | Syntax | Purpose | |---------|--------|---------| | Arguments | $1, $2, $ARGUMENTS | Dynamic input from user | | Bash execution | !backtickcommandbacktick | Include shell output in context | | File references | @path/to/file | Include file contents | | Tool restrictions | allowed-tools: | Limit Claude's capabilities |

Frontmatter Schema

---
description: Brief description for /help      # Required for discovery
argument-hint: <required> [optional]          # Shown in autocomplete
allowed-tools: Read, Grep, Bash(git *)        # Restrict tool access
model: claude-3-5-haiku-20241022             # Override model
disable-model-invocation: true                # Prevent SlashCommand tool
---

See frontmatter.md for complete schema.

---

Stage 3: Implementation

File Structure

---
description: Deploy to environment with validation
argument-hint: <environment> [--skip-tests]
allowed-tools: Bash(*), Read
---

# Deployment

Target: $1
Options: $2

## Pre-flight Checks
<!-- NOTE: Place "!" before the opening backtick for preprocessing to work -->
Environment: `echo "$1" | grep -E "^(staging|production)$" || echo "Invalid"`
Tests: `[[ "$2" == *"--skip-tests"* ]] && echo "Skipped" || bun test`

## Task

Based on validation above, proceed with deployment or explain issues.

Argument Patterns

Positional arguments ($1, $2, $3):

Compare file $1 with file $2 and summarize differences.

Usage: /compare old.ts new.ts

All arguments ($ARGUMENTS):

Fix the following issues: $ARGUMENTS

Usage: /fix memory leak in auth slow query in search

Combined with file references:

Analyze this file: @$1

Usage: /analyze src/main.ts

See arguments.md for advanced patterns.

Bash Execution

Execute commands and include output. The ! must precede the opening backtick for preprocessing to work:

## Git Context
<!-- NOTE: Place "!" before the opening backtick for preprocessing to work -->
Branch: `git branch --show-current`
Status: `git status --short`
Diff: `git diff --stat`

Based on the above, suggest next steps.

Important: Output is truncated at 15,000 characters by default. Use SLASH_COMMAND_TOOL_CHAR_BUDGET to adjust.

See bash-execution.md for patterns.

File References

Include file contents directly:

Review this configuration:
- Package: @package.json
- TypeScript: @tsconfig.json
- User input: @$1

See file-references.md for details.

Tool Permissions

Restrict what Claude can do:

# Read-only analysis
allowed-tools: Read, Grep, Glob

# Git operations only
allowed-tools: Bash(git *), Read

# Full bash with restrictions
allowed-tools: Bash(bun *), Bash(npm *), Read, Write, Edit

See permissions.md for patterns.

---

Stage 4: Validation

After creating a command, validate against these checklists.

Frontmatter Checks

• [ ] Opens with --- on line 1, closes with ---
• [ ] description present and action-oriented
• [ ] argument-hint uses <required> and [optional] syntax
• [ ] allowed-tools uses correct names (case-sensitive)
• [ ] Uses spaces (not tabs) for indentation

Naming Conventions

• [ ] Kebab-case filename: my-command.md
• [ ] No spaces or special characters
• [ ] Action-oriented: verb-noun pattern preferred
• [ ] Concise: 1-3 words

Good: review-pr.md, deploy-staging.md, fix-issue.md Bad: my command.md, DoStuff.md, helper.md

Description Quality

• [ ] Action-oriented (starts with verb)
• [ ] Specific about what it does
• [ ] Under 80 characters
• [ ] Helpful for /help discovery

Good: "Deploy to staging with health checks and Slack notification" Bad: "Deploy stuff" or "Helps with deployment"

Content Quality

• [ ] Clear instructions for Claude
• [ ] Proper argument handling if used
• [ ] Bash commands validated (test in terminal first)
• [ ] File paths relative to project root
• [ ] Error handling for edge cases

Validation Report Format

# Command Validation: [command-name]

## Summary
- **Status**: PASS | FAIL | WARNINGS
- **Location**: [path]
- **Issues**: [count]

## Critical Issues (must fix)
1. [Issue with fix]

## Warnings (should fix)
1. [Issue with fix]

## Strengths
- [What's done well]

---

Namespacing

Organize commands in subdirectories:

.claude/commands/
+-- frontend/
|   +-- component.md      # /component (project:frontend)
|   +-- styling.md        # /styling (project:frontend)
+-- backend/
|   +-- migration.md      # /migration (project:backend)
+-- review.md             # /review (project)

The namespace appears in /help but commands are invoked without prefix: /component or /frontend/component.

See namespacing.md for organization patterns.

---

Testing Commands

1. Create the command file
2. Verify with /help - should see your command listed
3. Test basic invocation: /your-command
4. Test with arguments: /your-command arg1 arg2
5. Verify tool restrictions if using allowed-tools

Debug Mode

claude --debug

Shows command loading and execution details.

---

Troubleshooting

Command Not Found

• Verify file location: .claude/commands/name.md
• Check filename: lowercase, .md extension, no spaces
• Restart Claude Code or use /clear

Arguments Not Working

• Use $1, $2 not {1}, {2}
• Use $ARGUMENTS for all arguments
• Quote arguments with spaces: /cmd "arg with spaces"

Bash Commands Failing

• Use ! before backticks: !`command`
• Test command in terminal first
• Check output length (15k char limit)
• Verify allowed-tools includes Bash

Tool Restrictions Not Applied

• Check YAML syntax (no tabs, proper quoting)
• Tool names are case-sensitive: Read not read
• Use wildcards for bash: Bash(git *)

---

References

| Reference | Content | |-----------|---------| | frontmatter.md | Complete frontmatter schema and fields | | arguments.md | Argument handling and patterns | | bash-execution.md | Shell command execution | | file-references.md | File inclusion syntax | | permissions.md | Tool restriction patterns | | namespacing.md | Directory organization | | sdk-integration.md | Agent SDK usage | | community.md | Community examples and resources |

See EXAMPLES.md for complete real-world examples. See scripts/ for scaffolding and validation utilities.

---

Related Skills

• claude-hook-authoring: Add automation triggers to command workflows
• claude-plugin-development: Bundle commands into distributable plugins
• claude-code-configuration: Configure Claude Code settings globally