directive-synthesis

What this skill does

# 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

2. **Next Step**
   [Instructions for Claude]
   - What to check
   - How to proceed
   - What to output

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