Command Development for Claude Code

Overview

• Markdown file format for commands
• YAML frontmatter for configuration
• Dynamic arguments and file references
• Bash execution for context
• Command organization and namespacing

Command Basics

What is a Slash Command?

• Reusability: Define once, use repeatedly
• Consistency: Standardize common workflows
• Sharing: Distribute across team or projects
• Efficiency: Quick access to complex prompts

Critical: Commands are Instructions FOR Claude

Copy
Review this code for security vulnerabilities including:
- SQL injection
- XSS attacks
- Authentication issues

Provide specific line numbers and severity ratings.
`**Incorrect approach (messages to user):**`
This command will review your code for security issues.
You'll receive a report with vulnerability details.

Command Locations

• Location: .claude/commands/
• Scope: Available in specific project
• Label: Shown as "(project)" in /help
• Use for: Team workflows, project-specific tasks

• Location: ~/.claude/commands/
• Scope: Available in all projects
• Label: Shown as "(user)" in /help
• Use for: Personal workflows, cross-project utilities

• Location: plugin-name/commands/
• Scope: Available when plugin installed
• Label: Shown as "(plugin-name)" in /help
• Use for: Plugin-specific functionality

File Format

Basic Structure

Copy
.claude/commands/
├── review.md           # /review command
├── test.md             # /test command
└── deploy.md           # /deploy command
`**Simple command:**`
Review this code for security vulnerabilities including:
- SQL injection
- XSS attacks
- Authentication bypass
- Insecure data handling

With YAML Frontmatter

Copy
---
description: Review code for security issues
allowed-tools: Read, Grep, Bash(git:*)
model: sonnet
---

Review this code for security vulnerabilities...

YAML Frontmatter Fields

description

Copy
---
description: Review pull request for code quality
---

allowed-tools

Copy
---
allowed-tools: Read, Write, Edit, Bash(git:*)
---

• Read, Write, Edit - Specific tools
• Bash(git:*) - Bash with git commands only
• * - All tools (rarely needed)

model

Copy
---
model: haiku
---

• haiku - Fast, simple commands
• sonnet - Standard workflows
• opus - Complex analysis

argument-hint

Copy
---
argument-hint: [pr-number] [priority] [assignee]
---

• Helps users understand command arguments
• Improves command discovery
• Documents command interface

disable-model-invocation

Copy
---
disable-model-invocation: true
---

Dynamic Arguments

Using $ARGUMENTS

Copy
---
description: Fix issue by number
argument-hint: [issue-number]
---

Fix issue #$ARGUMENTS following our coding standards and best practices.
`**Usage:**`
> /fix-issue 123
> /fix-issue 456
`**Expands to:**`
Fix issue #123 following our coding standards...
Fix issue #456 following our coding standards...

Using Positional Arguments

Copy
---
description: Review PR with priority and assignee
argument-hint: [pr-number] [priority] [assignee]
---

Review pull request #$1 with priority level $2.
After review, assign to $3 for follow-up.
`**Usage:**`
> /review-pr 123 high alice
`**Expands to:**`
Review pull request #123 with priority level high.
After review, assign to alice for follow-up.

Combining Arguments

File References

Using @ Syntax

Copy
---
description: Review specific file
argument-hint: [file-path]
---

Review @$1 for:
- Code quality
- Best practices
- Potential bugs
`**Usage:**`
> /review-file src/api/users.ts

Multiple File References

Copy
Compare @src/old-version.js with @src/new-version.js

Identify:
- Breaking changes
- New features
- Bug fixes

Static File References

Copy
Review @package.json and @tsconfig.json for consistency

Ensure:
- TypeScript version matches
- Dependencies are aligned
- Build configuration is correct

Bash Execution in Commands

• Include dynamic context (git status, environment vars, etc.)
• Gather project/repository state
• Build context-aware workflows

Command Organization

Flat Structure

Copy
.claude/commands/
├── build.md
├── test.md
├── deploy.md
├── review.md
└── docs.md

Namespaced Structure

Copy
.claude/commands/
├── ci/
│   ├── build.md        # /build (project:ci)
│   ├── test.md         # /test (project:ci)
│   └── lint.md         # /lint (project:ci)
├── git/
│   ├── commit.md       # /commit (project:git)
│   └── pr.md           # /pr (project:git)
└── docs/
    ├── generate.md     # /generate (project:docs)
    └── publish.md      # /publish (project:docs)

• Logical grouping by category
• Namespace shown in /help
• Easier to find related commands

Best Practices

Command Design

1. Single responsibility: One command, one task
2. Clear descriptions: Self-explanatory in /help
3. Explicit dependencies: Use allowed-tools when needed
4. Document arguments: Always provide argument-hint
5. Consistent naming: Use verb-noun pattern (review-pr, fix-issue)

Argument Handling

1. Validate arguments: Check for required arguments in prompt
2. Provide defaults: Suggest defaults when arguments missing
3. Document format: Explain expected argument format
4. Handle edge cases: Consider missing or invalid arguments

Copy
---
argument-hint: [pr-number]
---

$IF($1,
  Review PR #$1,
  Please provide a PR number. Usage: /review-pr [number]
)

File References

1. Explicit paths: Use clear file paths
2. Check existence: Handle missing files gracefully
3. Relative paths: Use project-relative paths
4. Glob support: Consider using Glob tool for patterns

Bash Commands

1. Limit scope: Use Bash(git:*) not Bash(*)
2. Safe commands: Avoid destructive operations
3. Handle errors: Consider command failures
4. Keep fast: Long-running commands slow invocation

Documentation

1. Add comments: Explain complex logic
2. Provide examples: Show usage in comments
3. List requirements: Document dependencies
4. Version commands: Note breaking changes

Copy
---
description: Deploy application to environment
argument-hint: [environment] [version]
---

<!--
Usage: /deploy [staging|production] [version]
Requires: AWS credentials configured
Example: /deploy staging v1.2.3
-->

Deploy application to $1 environment using version $2...

Common Patterns

Review Pattern

Copy
---
description: Review code changes
allowed-tools: Read, Bash(git:*)
---

Files changed: !`git diff --name-only`

Review each file for:
1. Code quality and style
2. Potential bugs or issues
3. Test coverage
4. Documentation needs

Provide specific feedback for each file.
`### Testing Pattern`
---
description: Run tests for specific file
argument-hint: [test-file]
allowed-tools: Bash(npm:*)
---

Run tests: !`npm test $1`

Analyze results and suggest fixes for failures.
`### Documentation Pattern`
---
description: Generate documentation for file
argument-hint: [source-file]
---

Generate comprehensive documentation for @$1 including:
- Function/class descriptions
- Parameter documentation
- Return value descriptions
- Usage examples
- Edge cases and errors
`### Workflow Pattern`
---
description: Complete PR workflow
argument-hint: [pr-number]
allowed-tools: Bash(gh:*), Read
---

PR #$1 Workflow:

1. Fetch PR: !`gh pr view $1`
2. Review changes
3. Run checks
4. Approve or request changes

Troubleshooting

• Check file is in correct directory
• Verify .md extension present
• Ensure valid Markdown format
• Restart Claude Code

• Verify $1, $2 syntax correct
• Check argument-hint matches usage
• Ensure no extra spaces

• Check allowed-tools includes Bash
• Verify command syntax in backticks
• Test command in terminal first
• Check for required permissions

• Verify @ syntax correct
• Check file path is valid
• Ensure Read tool allowed
• Use absolute or project-relative paths

Plugin-Specific Features

CLAUDE_PLUGIN_ROOT Variable

• Reference plugin files portably
• Execute plugin scripts
• Load plugin configuration
• Access plugin templates

Copy
---
description: Analyze using plugin script
allowed-tools: Bash(node:*)
---

Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`

Review results and report findings.
`**Common patterns:**`
# Execute plugin script
!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`

# Load plugin configuration
@${CLAUDE_PLUGIN_ROOT}/config/settings.json

# Use plugin template
@${CLAUDE_PLUGIN_ROOT}/templates/report.md

# Access plugin resources
@${CLAUDE_PLUGIN_ROOT}/docs/reference.md

• Works across all installations
• Portable between systems
• No hardcoded paths needed
• Essential for multi-file plugins

Plugin Command Organization

Copy
plugin-name/
├── commands/
│   ├── foo.md              # /foo (plugin:plugin-name)
│   ├── bar.md              # /bar (plugin:plugin-name)
│   └── utils/
│       └── helper.md       # /helper (plugin:plugin-name:utils)
└── plugin.json

• Logical command grouping
• Shown in /help output
• Avoid name conflicts
• Organize related commands

• Use descriptive action names
• Avoid generic names (test, run)
• Consider plugin-specific prefix
• Use hyphens for multi-word names

Plugin Command Patterns

Copy
---
description: Deploy using plugin configuration
argument-hint: [environment]
allowed-tools: Read, Bash(*)
---

Load configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json

Deploy to $1 using configuration settings.
Monitor deployment and report status.
`**Template-based pattern:**`
---
description: Generate docs from template
argument-hint: [component]
---

Template: @${CLAUDE_PLUGIN_ROOT}/templates/docs.md

Generate documentation for $1 following template structure.
`**Multi-script pattern:**`
---
description: Complete build workflow
allowed-tools: Bash(*)
---

Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`
Package: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh`

Review outputs and report workflow status.

Integration with Plugin Components

Agent Integration

Copy
---
description: Deep code review
argument-hint: [file-path]
---

Initiate comprehensive review of @$1 using the code-reviewer agent.

The agent will analyze:
- Code structure
- Security issues
- Performance
- Best practices

Agent uses plugin resources:
- ${CLAUDE_PLUGIN_ROOT}/config/rules.json
- ${CLAUDE_PLUGIN_ROOT}/checklists/review.md

• Agent must exist in plugin/agents/ directory
• Claude uses Task tool to launch agent
• Document agent capabilities
• Reference plugin resources agent uses

Skill Integration

Copy
---
description: Document API with standards
argument-hint: [api-file]
---

Document API in @$1 following plugin standards.

Use the api-docs-standards skill to ensure:
- Complete endpoint documentation
- Consistent formatting
- Example quality
- Error documentation

Generate production-ready API docs.

• Skill must exist in plugin/skills/ directory
• Mention skill name to trigger invocation
• Document skill purpose
• Explain what skill provides

Hook Coordination

• Commands can prepare state for hooks to process
• Hooks execute automatically on tool events
• Commands should document expected hook behavior
• Guide Claude on interpreting hook output

Multi-Component Workflows

Copy
---
description: Comprehensive review workflow
argument-hint: [file]
allowed-tools: Bash(node:*), Read
---

Target: @$1

Phase 1 - Static Analysis:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`

Phase 2 - Deep Review:
Launch code-reviewer agent for detailed analysis.

Phase 3 - Standards Check:
Use coding-standards skill for validation.

Phase 4 - Report:
Template: @${CLAUDE_PLUGIN_ROOT}/templates/review.md

Compile findings into report following template.

• Complex multi-step workflows
• Leverage multiple plugin capabilities
• Require specialized analysis
• Need structured outputs

Validation Patterns

Argument Validation

Copy
---
description: Deploy with validation
argument-hint: [environment]
---

Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)
quot; || echo "INVALID"`

If $1 is valid environment:
  Deploy to $1
Otherwise:
  Explain valid environments: dev, staging, prod
  Show usage: /deploy [environment]
`### File Existence Checks`
---
description: Process configuration
argument-hint: [config-file]
---

Check file exists: !`test -f $1 && echo "EXISTS" || echo "MISSING"`

If file exists:
  Process configuration: @$1
Otherwise:
  Explain where to place config file
  Show expected format
  Provide example configuration
`### Plugin Resource Validation`
---
description: Run plugin analyzer
allowed-tools: Bash(test:*)
---

Validate plugin setup:
- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"`
- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"`

If all checks pass, run analysis.
Otherwise, report missing components.
`### Error Handling`
---
description: Build with error handling
allowed-tools: Bash(*)
---

Execute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo "BUILD_FAILED"`

If build succeeded:
  Report success and output location
If build failed:
  Analyze error output
  Suggest likely causes
  Provide troubleshooting steps

• Validate early in command
• Provide helpful error messages
• Suggest corrective actions
• Handle edge cases gracefully