claude-command-authoring

name	claude-command-authoring
description	Creates custom slash commands for Claude Code with proper syntax, frontmatter, arguments, bash execution, and file references. Use when building slash commands, creating custom Claude Code commands, setting up team workflows, or when users mention slash commands, command files, or .md command creation.
version	1.0.0

Claude Command Authoring

Create custom slash commands that extend Claude Code with frequently-used prompts and workflows.

Overview

Slash commands are Markdown files that define reusable prompts. They support:

• Arguments: $1, $2, $ARGUMENTS
• Bash execution: ! prefix for command output
• File references: @ prefix to include file contents
• Frontmatter: Metadata for configuration
• Namespacing: Organize in subdirectories

Quick Start

Basic Command

# Create a simple command
mkdir -p .claude/commands
cat > .claude/commands/review.md << 'EOF'
---
description: Review code for best practices and potential issues
---

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

# Use it
/review

Command with Arguments

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

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

Command with Bash Execution

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

## Context

Current branch: !`git branch --show-current`
Staged changes: !`git diff --staged`
Recent commits: !`git log --oneline -5`

## Task

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

Command with File References

---
description: Compare two implementations
argument-hint: <file1> <file2>
---

Compare these two implementations and explain the differences:

**File 1**: @$1
**File 2**: @$2

Provide a detailed comparison focusing on architecture, performance, and maintainability.

Command Scopes

Project Commands (.claude/commands/)

• Shared with your team via git
• Show "(project)" in /help
• Team-specific workflows

Personal Commands (~/.claude/commands/)

• Available across all your projects
• Show "(user)" in /help
• Individual preferences

Plugin Commands (plugin/commands/)

• Bundled with plugins
• Show "(plugin-name)" in /help
• Distributed via marketplaces

Frontmatter Options

Field	Purpose	Example
description	Brief description shown in /help	"Deploy to staging environment"
argument-hint	Expected arguments for autocomplete	"<environment> [--skip-tests]"
allowed-tools	Restrict tool usage	"Bash(git *), Read, Write"
model	Specific model to use	"claude-3-5-haiku-20241022"
disable-model-invocation	Prevent SlashCommand tool usage	true

Argument Handling

All Arguments ($ARGUMENTS)

Fix issues: $ARGUMENTS

Usage: /fix-issues 123 456 789 → $ARGUMENTS = "123 456 789"

Individual Arguments ($1, $2, $3, ...)

Review PR #$1 with priority $2 and assign to $3

Usage: /review-pr 456 high alice → $1="456", $2="high", $3="alice"

Combining Arguments with Files

Compare @$1 with @$2 and summarize differences

Usage: /compare src/old.ts src/new.ts

Bash Execution with !

Execute bash commands before the prompt runs:

---
description: Show current project status
---

## Git Status
!`git status`

## Recent Activity
!`git log --oneline -10`

## Uncommitted Changes
!`git diff`

Based on the above, provide a summary of the current project state.

Output truncation: Commands producing >15,000 chars are truncated by default. Set SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable to adjust.

File References with @

Include file contents in your command:

---
description: Explain a specific file
argument-hint: <file-path>
---

# File Analysis

**File**: @$1

Provide a detailed explanation of:
1. Purpose and responsibility
2. Key functions and methods
3. Dependencies and imports
4. Potential improvements

Namespacing

Organize commands in subdirectories:

.claude/commands/
├── frontend/
│   ├── component.md      → /component (project:frontend)
│   └── styling.md        → /styling (project:frontend)
└── backend/
    ├── migration.md      → /migration (project:backend)
    └── testing.md        → /testing (project:backend)

Access: /component or /frontend/component

Tool Restrictions

Limit what tools Claude can use:

---
description: Safe code review (read-only)
allowed-tools: Read, Grep, Glob
---

Review the codebase for issues without making any changes.

Claude can only use specified tools without asking permission.

Best Practices

1. Clear Descriptions

---
# ❌ Too vague
description: Deploy stuff

# ✅ Specific and helpful
description: Deploy to staging with health checks and Slack notification
---

2. Helpful Argument Hints

---
# ❌ Not helpful
argument-hint: args

# ✅ Clear expectations
argument-hint: <environment> [--skip-tests] [--no-notify]
---

3. Context Before Instructions

---
description: Create feature branch from issue
---

## Context
Current branch: !`git branch --show-current`
Issue: $1

## Task
1. Fetch latest changes
2. Create feature branch: feature/$1
3. Push to remote with tracking

4. Use Tool Restrictions

---
description: Security audit (read-only)
allowed-tools: Read, Grep, Glob, Bash(find:*)
---

5. Document Complex Commands

---
description: Full deployment pipeline with validation
---

# Deployment Pipeline

This command runs the complete deployment process:

1. **Pre-flight**: Runs test suite
2. **Build**: Creates Docker image
3. **Deploy**: Updates Kubernetes
4. **Validate**: Health checks
5. **Notify**: Posts to Slack

## Usage
- `/deploy staging` - Deploy to staging
- `/deploy production` - Deploy to production
- `/deploy staging --skip-tests` - Skip test suite

## Requirements
- Docker installed and running
- kubectl configured for target environment
- SLACK_WEBHOOK in .env file

---

[Command implementation here...]

Testing Commands

# 1. Register command
# Create the .md file in .claude/commands/

# 2. Verify registration
/help
# Should see your command listed

# 3. Test invocation
/your-command arg1 arg2

# 4. Check bash execution (if using !)
# Enable transcript mode: Ctrl-R
# Look for bash command output

# 5. Test with different arguments
/your-command different args

# 6. Validate tool restrictions (if using allowed-tools)
# Try operations outside allowed list
# Should ask permission or be blocked

Common Patterns

Code Review

---
description: Review code changes with security focus
allowed-tools: Read, Grep, Glob, Bash(git *)
---

Review changes: !`git diff $1`

Focus on:
1. Security vulnerabilities
2. Input validation
3. Authentication/authorization
4. Data sanitization
5. Error handling

Issue Handling

---
description: Create feature branch and link issue
argument-hint: <issue-number>
---

Issue #$1 details: !`gh issue view $1`

1. Create feature branch: `feature/$1`
2. Update issue with branch link
3. Provide implementation plan

Testing Workflow

---
description: Run tests and analyze failures
allowed-tools: Bash(bun test:*, npm test:*)
---

Test results: !`bun test`

Analyze any failures and suggest fixes.

Documentation Generation

---
description: Generate API docs from code
argument-hint: <file-or-directory>
---

Code to document: @$1

Generate comprehensive API documentation including:
- Function signatures with types
- Parameter descriptions
- Return value documentation
- Usage examples
- Edge cases and error handling

Troubleshooting

Command Not Found

• Verify file location: .claude/commands/your-command.md
• Check filename: no spaces, lowercase, .md extension
• Restart Claude Code if needed

Arguments Not Working

• Use $1, $2, not {1}, {2}
• Use $ARGUMENTS for all arguments
• Quote arguments if they contain spaces

Bash Commands Failing

• Use ! prefix before backticks: !\command``
• Verify command works in terminal first
• Check command output length (<15k chars)

File References Not Working

• Use @ prefix: @path/to/file.ts
• Verify file paths are relative to project root
• Combine with arguments: @$1

Tool Restrictions Not Applied

• Verify frontmatter syntax (YAML format)
• Check tool names match exactly: Read, not read
• Use wildcards for bash: Bash(git *)

Advanced Patterns

See REFERENCE.md for:

• SlashCommand tool configuration
• Complex argument parsing
• Multi-step command workflows
• Error handling patterns
• Integration with hooks

See EXAMPLES.md for:

• Real-world command implementations
• Team workflow examples
• Integration patterns
• Common use cases

Quick Reference

# Scaffold new command
./scripts/scaffold-command.sh my-command "Description here"

# Validate command
./scripts/validate-command.sh .claude/commands/my-command.md

# Test command
/my-command test args

Related Skills

• claude-hook-authoring: Add automation to commands with hooks
• claude-plugin-authoring: Bundle commands into distributable plugins
• claude-config-management: Configure command behavior globally