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

• Discovery - Define purpose, scope, and target users

• Design - Choose features and configuration

• Implementation - Write frontmatter and content

• 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 ! backtickcommand backtick 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

• Create the command file

• Verify with /help

• should see your command listed

• Test basic invocation: /your-command

• Test with arguments: /your-command arg1 arg2

• 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