Claude Code Command Builder

Purpose

Guide users through creating effective Claude Code slash commands with proper structure, argument handling, and workflow design. Auto-invokes when users want to create or modify custom commands.

When to Use

Auto-invoke when users mention:

Creating commands - "create command", "make command", "new slash command"
Command structure - "command template", "command format", "command frontmatter"
Arguments - "$ARGUMENTS", "$1", "$2", "command parameters", "positional args"
Workflows - "command workflow", "command steps", "command process"
Bash execution - "!
```
command
```
", "execute bash in command", "command with bash"

Knowledge Base

Official docs:

.claude/skills/ai/claude-code/docs/code_claude_com/docs_en_slash-commands.md

Project guide:
```
.claude/docs/creating-components.md
```
Examples in repository:
```
.claude/commands/
```

Process

1. Gather Requirements

Ask the user:

Let me help you create a Claude Code slash command! I need a few details:

1. **Command name** (lowercase-with-hyphens):
   Example: deploy, review-pr, commit, analyze-tokens
   This will be invoked as: /your-command-name

2. **What does this command do?**
   Describe the workflow in 1-2 sentences.

3. **Does it need arguments?**
   - None (simple prompt)
   - All arguments: $ARGUMENTS
   - Positional: $1, $2, $3, etc.

4. **Does it need bash execution?**
   Commands that run before the slash command (e.g., !`git status`)

5. **Scope:**
   - Personal (`~/.claude/commands/`) - just for you
   - Project (`.claude/commands/`) - shared with team

6. **Namespace/subdirectory?**
   Example: git/, deploy/, testing/
   Helps organize related commands

2. Validate Input

Check the command name:

Must be valid filename (no spaces, special chars except hyphen)
Descriptive and memorable
Won't conflict with built-in commands
Use hyphens (not underscores)

Validate arguments:

Define expected arguments
Provide defaults if needed
Document argument order

3. Determine Command Type

Simple Prompt (no frontmatter):

markdown

Analyze this code for performance issues and suggest optimizations.

With Arguments:

markdown

---
argument-hint: [file-path]
description: Analyze file for performance issues
---

Analyze the file at $1 for performance issues and suggest optimizations.

With Bash Execution:

markdown

---
allowed-tools: Bash(git status:*), Bash(git diff:*)
description: Create a git commit
---

## Current State

- Git status: !`git status`
- Staged changes: !`git diff --staged`
- Recent commits: !`git log --oneline -5`

## Your Task

Based on the above changes, create a git commit with a clear, conventional commit message.

Full-Featured:

markdown

---
allowed-tools: Bash(npm run:*), Bash(git add:*), Bash(git commit:*)
argument-hint: [component-name]
description: Create a new React component with tests
model: sonnet
---

# Create React Component

Component name: $1

Execute the following workflow:

1. **Validate Input**
   !`test -n "$1" && echo "Creating component: $1" || echo "Error: Component name required"`

2. **Check Existing Files**
   !`ls src/components/$1.tsx 2>/dev/null || echo "Component does not exist"`

3. **Create Files**
   Create the following files:
   - `src/components/$1.tsx`
   - `src/components/$1.test.tsx`
   - `src/components/$1.module.css`

4. **Run Tests**
   After creation, run: !`npm run test -- $1`

4. Generate Command File

Create command structure based on complexity:

Template for Simple Command:

markdown

Brief description of what the command does.

[Prompt instructions for Claude]

Template for Command with Frontmatter:

markdown

---
argument-hint: [arg1] [arg2]
description: Brief description shown in /help
allowed-tools: Bash(command:*), Read, Write
model: sonnet
disable-model-invocation: false
---

# Command Name

Usage: /command-name [args]

[Detailed instructions]

5. Build Command Workflow

Structure the workflow with clear steps:

markdown

Execute the following workflow:

1. **Step Name**
   ```bash
   # Bash command (if needed)
   command arg1 arg2

What this step does
Validation checks
Error handling

Next Step [Instructions for Claude]
- What to check
- How to proceed
- What to output
Final Step
- Summary of results
- Next actions for user
- Success criteria


### 6. Add Argument Handling

**All Arguments ($ARGUMENTS):**
```markdown
Fix issue #$ARGUMENTS following our coding standards.

User runs:

/fix-issue 123 high-priority

Becomes: "Fix issue #123 high-priority following our coding standards."

Positional Arguments ($1, $2, $3):

markdown

Review PR #$1 with priority $2 and assign to $3.
Focus on: $4

User runs:

/review-pr 456 high alice security

Becomes individual parameters you can reference separately.

With Defaults:

markdown

---
argument-hint: [environment] [branch]
---

Deploy to environment: ${1:-staging}
From branch: ${2:-main}

7. Add Bash Execution (if needed)

Use

prefix to execute commands before processing:

markdown

---
allowed-tools: Bash(git:*)
---

## Context

- Current branch: !`git branch --show-current`
- Status: !`git status --short`
- Recent commits: !`git log --oneline -5`

## Your Task

[Instructions based on the above context]

Important:

Must specify
```
allowed-tools
```
with specific Bash permissions
Output is included in command context
Commands run before Claude processes the prompt

8. Add File References

Use

prefix to reference files:

markdown

Review the implementation in @src/utils/helpers.js

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

Analyze all files in @src/components/

9. Configure Thinking Mode (if needed)

For complex problems, trigger extended thinking:

markdown

Carefully analyze the following code and think through...

Let's approach this step by step...

Consider all edge cases before implementing...

These keywords can trigger extended thinking mode.

10. Create the File

Save to correct location:

Personal command:

bash

~/.claude/commands/command-name.md
~/.claude/commands/category/command-name.md  # With namespace

Project command:

bash

.claude/commands/command-name.md
.claude/commands/category/command-name.md  # With namespace

11. Test the Command

Provide testing instructions:

To test your command:
1. Restart Claude Code or start a new session
2. Type: /help
3. Find your command in the list
4. Try: /your-command-name [args]
5. Verify it behaves as expected

Test cases:

bash

# No arguments
/your-command

# With arguments
/your-command arg1
/your-command arg1 arg2

# Edge cases
/your-command ""
/your-command "with spaces"

Frontmatter Reference

Field	Purpose	Example
`argument-hint`	Show expected arguments in autocomplete	`[pr-number] [priority]`
`description`	Brief description for `/help` menu	`Review pull request`
`allowed-tools`	Tools command can use	`Bash(git:*), Read, Write`
`model`	Specific model to use	`claude-sonnet-4-5-20250929`
`disable-model-invocation`	Prevent SlashCommand tool from calling this	`true`

Bash Tool Permissions

When using

prefix or needing bash execution:

markdown

---
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git push:*)
---

Permission patterns:

```
Bash(git:*)
```
- All git commands
```
Bash(npm run:*)
```
- All npm run scripts
```
Bash(git add:*), Bash(git commit:*)
```
- Specific git commands

Argument Patterns

Pattern 1: All Arguments

markdown

Run tests for: $ARGUMENTS

Usage:

/test users api database

Becomes: "Run tests for: users api database"

Pattern 2: Positional

markdown

Deploy $1 to $2 environment with tag $3

Usage:

/deploy my-app staging v1.2.3

Becomes: "Deploy my-app to staging environment with tag v1.2.3"

Pattern 3: Mixed

markdown

---
argument-hint: <file> [rest of args]
---

Analyze file $1 for: $ARGUMENTS

Usage:

/analyze src/app.js performance security

Becomes: "Analyze file src/app.js for: src/app.js performance security" Note: $ARGUMENTS includes all args, so $1 is duplicated

Better approach:

markdown

Analyze file $1 for: ${2:+${@:2}}

This uses $1 separately and remaining args starting from $2

Pattern 4: With Defaults

markdown

Environment: ${1:-production}
Verbose: ${2:-false}

Command Size Guidelines

✅ Good: < 100 lines
⚠️ Warning: 100-150 lines
❌ Too large: > 250 lines (must refactor)

If too large:

Extract to external script
Split into multiple commands
Use sub-commands pattern

Common Command Types

1. Git Workflow

markdown

---
allowed-tools: Bash(git:*)
description: Create conventional commit
---

## Context
- Status: !`git status --short`
- Diff: !`git diff HEAD`

Create a conventional commit message.

2. Code Generator

markdown

---
argument-hint: [component-name]
description: Generate React component
---

Create a new React component named $1:
- Component file
- Test file
- Storybook story

3. Analysis Tool

markdown

---
argument-hint: [file-path]
description: Analyze code complexity
---

Analyze @$1 for:
- Cyclomatic complexity
- Code smells
- Improvement suggestions

4. Deployment Helper

markdown

---
allowed-tools: Bash(npm:*), Bash(git:*)
argument-hint: [environment]
description: Deploy to environment
---

Deploy to ${1:-staging}:
1. Run tests: !`npm test`
2. Build: !`npm run build`
3. Deploy: !`npm run deploy:$1`

5. Documentation Generator

markdown

---
argument-hint: [file-pattern]
description: Generate API documentation
---

Generate documentation for: $1
Include:
- Function signatures
- Parameters
- Return types
- Examples

Examples from TOON Formatter

Simple version:

markdown

# Convert to TOON

Convert the specified JSON file to TOON v2.0 format with automatic optimization and show token savings.

Usage: /convert-to-toon <file>

Advanced version with bash:

markdown

---
allowed-tools: Bash(jq:*), Bash(.claude/utils/toon/zig-out/bin/toon:*)
argument-hint: <file> [--delimiter comma|tab|pipe]
description: Convert JSON to TOON format
---

# Convert to TOON

File: $1
Delimiter: ${2:-comma}

1. **Validate**: !`test -f "$1" && jq empty "$1" 2>&1`
2. **Analyze**: !`jq 'if type == "array" then length else 0 end' "$1"`
3. **Convert**: !`.claude/utils/toon/zig-out/bin/toon encode "$1"`
4. Show savings comparison

Troubleshooting

Command Not Found

Check:

bash

# List all commands
ls ~/.claude/commands/*.md
ls .claude/commands/*.md

# Verify filename
ls .claude/commands/your-command.md

Remember:

Filename (without
```
.md
```
) becomes command name
Hyphens in filename become hyphens in command
Case-sensitive on Linux/Mac

Arguments Not Working

Debug:

markdown

Debug: $ARGUMENTS
Debug $1: "$1"
Debug $2: "$2"

Run command and check output to see what's being passed.

Bash Commands Not Executing

Check:

```
allowed-tools
```
includes correct Bash permissions
Using
```
!
```
prefix:
```
!
```
command``
Backticks are correct: `command` not 'command'
Command is allowed by permissions

Command Not in /help

Possible reasons:

File not in correct location
File doesn't have
```
.md
```
extension
Syntax error in frontmatter
Need to restart Claude Code

Best Practices

DO:

✅ Provide clear argument hints ✅ Include usage examples ✅ Handle errors gracefully ✅ Show progress for long operations ✅ Document expected behavior ✅ Test with various inputs ✅ Use descriptive command names

DON'T:

❌ Make commands too complex (>250 lines) ❌ Forget to specify allowed-tools for Bash ❌ Use unclear argument names ❌ Skip error handling ❌ Hardcode values (use arguments) ❌ Forget to test edge cases

Comparison: Commands vs Skills

Use Commands when:

You want explicit control (manual invocation)
Simple, repetitive prompts
Specific workflow steps
Frequently-used templates

Use Skills when:

Claude should auto-detect need
Complex, multi-file workflows
Comprehensive domain knowledge
Team needs standardized expertise

Can use both:

Command invokes skill explicitly
Skill activates automatically
Command provides quick access
Skill provides deep capability

Resources

Official Command Docs:

.claude/skills/ai/claude-code/docs/code_claude_com/docs_en_slash-commands.md

Project Component Guide:
```
.claude/docs/creating-components.md
```
Command Examples:
```
.claude/commands/
```
directory
Skills vs Commands: Section in slash-commands.md

directive-synthesis

NPX Install

Tags

SKILL.md Content

Claude Code Command Builder

Purpose

When to Use

Knowledge Base

Process

1. Gather Requirements

2. Validate Input

3. Determine Command Type

4. Generate Command File

5. Build Command Workflow

7. Add Bash Execution (if needed)

8. Add File References

9. Configure Thinking Mode (if needed)

10. Create the File

11. Test the Command

Frontmatter Reference

Bash Tool Permissions

Argument Patterns

Pattern 1: All Arguments

Pattern 2: Positional

Pattern 3: Mixed

Pattern 4: With Defaults

Command Size Guidelines

Common Command Types

1. Git Workflow

2. Code Generator

3. Analysis Tool

4. Deployment Helper

5. Documentation Generator

Examples from TOON Formatter

Troubleshooting

Command Not Found

Arguments Not Working

Bash Commands Not Executing

Command Not in /help

Best Practices

DO:

DON'T:

Comparison: Commands vs Skills

Resources