name	claude-command-builder
description	Interactive slash command creator for Claude Code. Triggers when user mentions creating commands, slash commands, command templates, command arguments, or wants to build a new command workflow.
allowed-tools	Read, Write, Edit, Grep, Glob, Bash
model	sonnet

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

Analyze this code for performance issues and suggest optimizations.

With Arguments:

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

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

With Bash Execution:

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

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

Brief description of what the command does.

[Prompt instructions for Claude]

Template for Command with Frontmatter:

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

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

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:

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

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

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:

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:

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

Project command:

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

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

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

Run tests for: $ARGUMENTS

Usage: /test users api database Becomes: "Run tests for: users api database"

Pattern 2: Positional

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

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

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

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

Pattern 4: With Defaults

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

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

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

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

3. Analysis Tool

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

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

4. Deployment Helper

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

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

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

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

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

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

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

Bash Commands Not Executing