harsh040506/command-development

Command Development for Claude Code

Overview

Slash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions. Understanding command structure, frontmatter options, and dynamic features enables creating powerful, reusable workflows.

Key concepts:

• 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?

A slash command is a Markdown file containing a prompt that Claude executes when invoked. Commands provide:

• 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

Commands are written for agent consumption, not human consumption.

When a user invokes /command-name, the command content is injected into Claude's context as an instruction set — not as a chat message from the user. Claude reads it as its own directive, processes it, and executes. This means the audience of every line in a command file is Claude's planning process, not a human reader.

This distinction matters because the two audiences require fundamentally different language:

• Instructions for Claude are task-framed: what to analyze, what to look for, what format to return
• Messages to a user are explanation-framed: what the command does, what the user will receive

When you write user-facing prose in a command, Claude receives an explanation of what should happen rather than a directive for what to do. It often follows politely anyway, but the ambiguity creates inconsistent behavior — especially when the prose has conditionals, passive voice, or future tense.

Correct approach (instructions for Claude):

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.

Common hybrid mistake (looks like instructions but is framed for the user):

When you run this command, Claude will look for SQL injection, XSS,
and authentication vulnerabilities in your code. The report you receive
will include line numbers and severity ratings for each issue found.

This fails because "when you run this command" and "the report you receive" address the user, not Claude. The passive construction ("will be included") doesn't commit Claude to an action. Reframe every sentence as a direct directive: "Analyze the code for SQL injection, XSS, and authentication vulnerabilities. Report each finding with its line number and severity rating."

Command Locations

Project commands (shared with team):

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

Personal commands (available everywhere):

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

Plugin commands (bundled with plugins):

• 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

Commands are Markdown files with .md extension:

.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

No frontmatter needed for basic commands.

With YAML Frontmatter

Add configuration using YAML frontmatter:

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

Review this code for security vulnerabilities...

YAML Frontmatter Fields

description

Purpose: Brief description shown in /help Type: String Default: First line of command prompt

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

Best practice: Clear, actionable description (under 60 characters)

Why this matters: The description is what users see when they type /help or start typing a / command. A vague description like "Code stuff" means users won't know to invoke the command; a command that never gets invoked provides no value regardless of how well it's written. The description also determines discoverability — users often find commands by browsing /help rather than knowing their exact name.

Decision heuristic: Write the description as if answering "What will this do when I run it?" in one sentence. If you need more than one sentence, the command scope is too broad.

allowed-tools

Purpose: Specify which tools command can use Type: String or Array Default: Inherits from conversation

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

Patterns:

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

Use when: Command requires specific tool access

Why this matters: Without allowed-tools, a command inherits whatever the conversation's current tool permissions are — which may be more or less than the command needs. This creates two failure modes: (1) the command tries to use a tool the conversation has disabled and errors out, or (2) the command has broader tool access than intended, creating security surface. Explicitly scoping tools makes the command self-contained and predictable regardless of where it's invoked.

Decision heuristic: Start with the minimum set that makes the command work. Add Bash(git:*) only if the command reads git history or status. Add Write only if it produces output files. Omit the field only for read-only commands where inheriting context permissions is intentional.

model

Purpose: Specify model for command execution Type: String (sonnet, opus, haiku) Default: Inherits from conversation

---
model: haiku
---

Use cases:

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

Why this matters: Model selection directly determines cost, latency, and capability ceiling for every invocation. A formatting command that specifies opus wastes budget on a task that haiku handles equally well. A complex analysis command that defaults to haiku may produce shallow outputs because the model lacks the reasoning depth the task requires. Explicit model selection locks in predictable cost and performance rather than varying with whatever model the user happens to have active.

Decision heuristic:

| Command type | Recommended model | |--------------|-------------------| | Formatting, templating, simple transforms | haiku | | Standard code generation, analysis, multi-step workflows | sonnet (or omit) | | Deep reasoning, complex design decisions, strategic review | opus | | Commands where accuracy matters more than speed | opus | | Commands where latency matters more than depth | haiku |

argument-hint

Purpose: Document expected arguments for autocomplete Type: String Default: None

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

Benefits:

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

Why this matters: Without an argument-hint, the command appears in /help with no indication of what to type after it. Users either have to read the command source or guess. This is a significant usability gap for commands that take structured arguments like PR numbers, file paths, or flags. The hint acts as an inline signature for the command.

Decision heuristic: Use angle brackets for required args <pr-number>, square brackets for optional ones [priority]. List args in invocation order. Keep it short enough to fit on one line in the /help panel (under 40 characters).

disable-model-invocation

Purpose: Prevent SlashCommand tool from programmatically calling command Type: Boolean Default: false

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

Use when: Command should only be manually invoked

Dynamic Arguments

Using $ARGUMENTS

Capture all arguments as single string:

---
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

Capture individual arguments with $1, $2, $3, etc.:

---
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

Mix positional and remaining arguments:

Deploy $1 to $2 environment with options: $3

Usage:

> /deploy api staging --force --skip-tests

Expands to:

Deploy api to staging environment with options: --force --skip-tests

File References

Using @ Syntax

Include file contents in command:

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

Review @$1 for:
- Code quality
- Best practices
- Potential bugs

Usage:

> /review-file src/api/users.ts

Effect: Claude reads src/api/users.ts before processing command

Multiple File References

Reference multiple files:

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

Identify:
- Breaking changes
- New features
- Bug fixes

Static File References

Reference known files without arguments:

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

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

Bash Execution in Commands

Commands can execute bash commands inline to dynamically gather context before Claude processes the command. This is useful for including repository state, environment information, or project-specific context.

When to use:

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

Implementation details: For complete syntax, examples, and best practices, see references/plugin-features-reference.md section on bash execution. The reference includes the exact syntax and multiple working examples to avoid execution issues

Command Organization

Flat Structure

Simple organization for small command sets:

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

Use when: 5-15 commands, no clear categories

Namespaced Structure

Organize commands in subdirectories:

.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)

Benefits:

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

Use when: 15+ commands, clear categories

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

---
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

---
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

---
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

Command not appearing:

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

Arguments not working:

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

Bash execution failing:

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

File references not working:

• 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

Plugin commands have access to ${CLAUDE_PLUGIN_ROOT}, an environment variable that resolves to the plugin's absolute path.

Purpose:

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

Basic usage:

---
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

Why use it:

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

Plugin Command Organization

Plugin commands discovered automatically from commands/ directory:

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

Namespace benefits:

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

Naming conventions:

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

Plugin Command Patterns

Configuration-based pattern:

---
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.

See references/plugin-features-reference.md for detailed patterns.

Integration with Plugin Components

Commands can integrate with other plugin components for powerful workflows.

Agent Integration

Launch plugin agents for complex tasks:

---
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

Key points:

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

Skill Integration

Leverage plugin skills for specialized knowledge:

---
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.

Key points:

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

Hook Coordination

Design commands that work with plugin hooks:

• 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

See references/plugin-features-reference.md for examples of commands that coordinate with hooks

Multi-Component Workflows

Combine agents, skills, and scripts:

---
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.

When to use:

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

Validation Patterns

Commands should validate inputs and resources before processing.

Argument Validation

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

Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || 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

Best practices:

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

---

For detailed frontmatter field specifications, see references/frontmatter-reference.md. For plugin-specific features and patterns, see references/plugin-features-reference.md. For command pattern examples, see examples/ directory.