claude-commands

name	claude-commands
description	This skill should be used when creating slash commands, writing command files, or when "/command", ".claude/commands", "$ARGUMENTS", or "create command" are mentioned.
metadata	{"version":"2.0.0","related-skills":["claude-hooks","claude-plugins","skills-dev"]}
allowed-tools	Read Write Edit Grep Glob Bash TaskCreate TaskUpdate TaskList TaskGet

Claude Command Authoring

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