Claude Code Commands

Claude Code Commands

Guide for creating custom slash commands that extend Claude Code functionality.

When to Use This Skill

Activate this skill when:

• Creating new custom slash commands
• Understanding command structure and syntax
• Organizing commands for plugins
• Implementing command workflows
• Debugging command execution

What Are Commands?

Commands are custom slash commands (like /​commit, /​review) that users can invoke to trigger specific workflows or expand prompts. They are markdown files that can contain:

• Static prompt text
• Dynamic content based on arguments
• Multi-step workflows
• Integration with tools and scripts

Command File Structure

Location

Commands are defined in markdown files located in:

• Plugin: <plugin-root>/​commands/
• User-level: .claude/​commands/

File Naming

• Use kebab-case: my-command.md
• File name becomes the command name: my-command.md → /​my-command
• Avoid conflicts with built-in commands

Basic Command Format

Simple Static Command

# /​my-command

This is the prompt that will be expanded when the user types /​my-command.

The entire content of this file will replace the slash command in the conversation.

Command with Description

<!--
description: Brief description of what this command does
-->

# /​my-command

Command prompt goes here...

Command Arguments

Commands can accept arguments that users provide when invoking the command.

Single Argument

# /​greet

Hello, {{arg}}! Welcome to the project.

Usage: /​greet Alice → "Hello, Alice! Welcome to the project."

Multiple Arguments

# /​create-file

Create a new file at {{arg1}} with the following content:

{{arg2}}

Usage: /​create-file src/​main.rs "fn main() {}"

Named Arguments

# /​deploy

Deploy {{environment}} environment to {{region}}.

Configuration:
- Environment: {{environment}}
- Region: {{region}}
- Branch: {{branch}}

Usage: /​deploy --environment=production --region=us-east-1 --branch=main

Advanced Features

Conditional Content

# /​analyze

Analyze the {{language}} codebase.

{{#if verbose}}
Provide detailed analysis including:
- Code complexity metrics
- Dependency analysis
- Security vulnerabilities
{{else}}
Provide a summary analysis.
{{/​if}}

Including Files

Reference other files or command outputs:

# /​context

Here is the current project structure:

{{file:PROJECT_STRUCTURE.md}}

And the current git status:

{{shell:git status}}

Multi-Step Workflows

# /​full-review

I'll perform a comprehensive code review:

1. First, let me check the git diff:
{{shell:git diff}}

2. Now analyzing code quality...

3. Checking for security issues...

4. Final recommendations:

Best Practices

Clear Command Names

• Use descriptive, action-oriented names
• /​analyze-security not /​sec
• /​create-component not /​comp

Provide Context

Always include what the command will do:

# /​commit

I'll analyze the current git changes and create a conventional commit message.

Current changes:
{{shell:git diff --staged}}

Based on these changes, here's my suggested commit message:

Handle Edge Cases

# /​deploy

{{#if staging}}
Deploying to staging environment (safe for testing)
{{else if production}}
⚠️ WARNING: Deploying to PRODUCTION
Are you sure you want to continue? This will affect live users.
{{else}}
Error: Unknown environment. Please specify --staging or --production
{{/​if}}

Document Arguments

<!--
description: Deploy application to specified environment
usage: /​deploy [--environment=<env>] [--region=<region>]
arguments:
  - environment: Target environment (staging, production)
  - region: AWS region (us-east-1, eu-west-1, etc.)
-->

# /​deploy

Command Organization

Plugin Commands

In plugin.json:

{
  "commands": [
    "./​commands/​deploy.md",
    "./​commands/​analyze.md",
    "./​commands/​review.md"
  ]
}

Directory-Based Commands

{
  "commands": ["./​commands"]
}

This loads all .md files in the commands/ directory.

Namespaced Commands

Organize related commands in subdirectories:

commands/
├── git/
│   ├── commit.md
│   ├── review.md
│   └── cleanup.md
├── deploy/
│   ├── staging.md
│   └── production.md

Common Command Patterns

Git Commit Message Generator

# /​gcm

I'll analyze the staged changes and generate a conventional commit message.

{{shell:git diff --staged}}

Based on these changes, here's my commit message:

Code Review Command

# /​review-pr

I'll review the pull request changes.

PR Number: {{pr_number}}

{{shell:gh pr diff {{pr_number}}}}

Review checklist:
- [ ] Code quality and style
- [ ] Security considerations
- [ ] Test coverage
- [ ] Documentation updates

Project Scaffolding

# /​new-component

Creating a new {{component_type}} component named {{name}}.

I'll create:
1. Component file at src/​components/​{{name}}.tsx
2. Test file at src/​components/​{{name}}.test.tsx
3. Storybook file at src/​components/​{{name}}.stories.tsx

Testing Commands

Manual Testing

1. Install the plugin locally
2. Reload Claude Code
3. Type your command in the chat
4. Verify the expansion is correct

Debugging

If a command doesn't work:

1. Check file location matches plugin.json
2. Verify markdown syntax
3. Test argument substitution
4. Check for conflicts with existing commands

Command Templates

Analysis Command Template

<!--
description: Analyze {{target}} for {{criteria}}
-->

# /​analyze-{{target}}

I'll analyze the {{target}} codebase for {{criteria}}.

{{shell:find {{target}} -type f -name "*.{{extension}}"}}

Analysis results:

Workflow Command Template

<!--
description: Execute {{workflow}} workflow
-->

# /​{{workflow}}

Starting {{workflow}} workflow...

Step 1: {{step1_description}}
{{step1_action}}

Step 2: {{step2_description}}
{{step2_action}}

Workflow complete!

Integration with Skills

Commands can reference skills:

# /​elixir-review

I'll review this Elixir code using my Phoenix and OTP knowledge.

Please provide the code to review, and I'll check for:
- Phoenix best practices
- OTP design patterns
- Elixir anti-patterns
- Performance considerations

Security Considerations

Avoid Sensitive Data

Never hardcode:

• API keys
• Passwords
• Tokens
• Private URLs

Validate Input

# /​deploy

{{#unless environment}}
Error: --environment is required
{{/​unless}}

{{#if (validate_environment environment)}}
Proceeding with deployment...
{{else}}
Error: Invalid environment. Must be staging or production.
{{/​if}}

Safe Shell Commands

Be cautious with shell command execution:

# /​safe-deploy

<!-- Only allow whitelisted commands -->
{{shell:./​scripts/​deploy.sh {{environment}}}}

References

For more information about Claude Code commands:

• Claude Code Documentation: https://code.claude.com/docs/en/commands
• Example Commands: https://github.com/anthropics/claude-code/tree/main/examples/commands