---
name: slash-command-builder
description: Create slash commands for Claude Code with proper frontmatter, arguments, and bash integration. Use when creating new slash commands, fixing broken command parameters, or debugging command invocation. References complete Anthropic documentation.
---

# Slash Command Builder

Build slash commands that extend Claude Code with standardized prompts, workflows, and team conventions.

## When to Use

- Creating new slash commands for project or personal use
- Fixing broken command parameter passing
- Debugging command invocation issues
- Converting workflows into reusable commands
- Standardizing team workflows

## Quick Start Workflow

### 1. Choose Command Location

**Project commands** (shared with team via git):
```bash
.claude/commands/<command-name>.md
```

**Personal commands** (available across all projects):
```bash
~/.claude/commands/<command-name>.md
```

**Plugin commands** (distributed via marketplace):
```bash
plugins/<plugin-name>/commands/<command-name>.md
```

### 2. Create Command File

Command files are Markdown with YAML frontmatter:

```markdown
---
description: Brief description shown in /help
argument-hint: [param1] [param2] (optional)
allowed-tools: Tool1, Tool2 (optional)
---

# Command Name

Command instructions and prompt here.

Use $ARGUMENTS for all args or $1, $2 for positional args.
```

### 3. Test Invocation

```bash
/<command-name> [arguments]
```

Check `/help` to verify command appears with correct description.

## Essential Patterns

### Pattern 1: Simple Command (No Arguments)

```markdown
---
description: Run type check across workspace
---

Run `pnpm check` to verify TypeScript types across all packages.

Report any errors with file paths and line numbers.
```

**Invocation**: `/typecheck`

### Pattern 2: Parameterized Command (All Arguments)

```markdown
---
description: Create git commit with standard format
argument-hint: [commit-message]
---

Create a git commit with message: $ARGUMENTS

Follow conventional commits format (feat|fix|docs|refactor):
- Use present tense
- Be concise and descriptive
- Reference issue numbers if applicable
```

**Invocation**: `/commit fix: resolve type error in user service`

### Pattern 3: Positional Arguments

```markdown
---
description: Review pull request with priority
argument-hint: [pr-number] [priority]
---

Review PR #$1 with $2 priority.

Focus on:
- Type safety and Effect patterns
- Test coverage
- Documentation updates
```

**Invocation**: `/review-pr 456 high`

### Pattern 4: Bash Integration

```markdown
---
description: Create commit with auto-generated context
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*)
argument-hint: [message]
---

## Current Context

**Status**: !`git status`

**Staged Changes**: !`git diff --cached --stat`

## Task

Create commit with message: $ARGUMENTS

Validate:
- All changes are intentional
- No debug code or secrets
- Clear, descriptive message
```

**Invocation**: `/smart-commit refactor: extract common types`

**How it works**: The `!`command`` syntax executes bash and injects output into context before Claude processes the command.

### Pattern 5: File References

```markdown
---
description: Review file against coding standards
argument-hint: [file-path]
---

Review @$ARGUMENTS against our coding standards:

**Standards**:
- Effect-idiomatic patterns
- Functional purity (no side effects)
- Proper error handling via Effect error channel
- Test coverage for public functions

Provide specific improvement suggestions with line numbers.
```

**Invocation**: `/review-file src/services/auth.ts`

**How it works**: The `@` prefix loads file contents into context.

## Frontmatter Fields Reference

### Required Fields

**description** (recommended, defaults to first line):
```yaml
description: Brief description shown in /help output
```

### Optional Fields

**argument-hint** (document parameters):
```yaml
argument-hint: [param1] [param2] [optional-param]
```

**allowed-tools** (restrict tool access):
```yaml
allowed-tools: Bash(git add:*), Bash(git status:*), Write, Edit
```

**model** (use specific model):
```yaml
model: claude-3-5-haiku-20241022
```

**disable-model-invocation** (prevent autonomous use):
```yaml
disable-model-invocation: true
```

## Common Issues & Fixes

### Issue: Arguments Not Working

❌ **Wrong**:
```markdown
Feature description: {{ARGUMENTS}}
```

✅ **Correct**:
```markdown
Feature description: $ARGUMENTS
```

**Why**: Use shell-style `$ARGUMENTS` not template-style `{{ARGUMENTS}}`.

### Issue: Command Not in `/help`

❌ **Wrong**:
```markdown
# My Command

Command content here.
```

✅ **Correct**:
```markdown
---
description: Brief description of what command does
---

# My Command

Command content here.
```

**Why**: Must have frontmatter with `description` field.

### Issue: Permission Errors

❌ **Wrong**:
```markdown
---
description: Commit changes
---

Status: !`git status`
Commit: $ARGUMENTS
```

✅ **Correct**:
```markdown
---
description: Commit changes
allowed-tools: Bash(git status:*), Bash(git add:*), Bash(git commit:*)
---

Status: !`git status`
Commit: $ARGUMENTS
```

**Why**: Commands using bash execution must list `allowed-tools`.

### Issue: Positional Args Not Parsing

❌ **Wrong**:
```markdown
Review PR $ARGUMENTS with priority $ARGUMENTS
```

✅ **Correct**:
```markdown
Review PR $1 with priority $2
```

**Why**: Use `$1`, `$2`, etc. for individual positional arguments. Use `$ARGUMENTS` for all args as single string.

## Advanced: Namespacing

Organize related commands in subdirectories:

```
.claude/commands/
├── git/
│   ├── commit.md
│   ├── review-pr.md
│   └── sync.md
├── test/
│   ├── spanner.md
│   ├── core.md
│   └── integration.md
└── dev/
    ├── typecheck.md
    └── build.md
```

Commands remain top-level (`/commit` not `/git/commit`), but `/help` shows namespace: "(project:git)".

## Advanced: SlashCommand Tool

Claude can autonomously invoke commands during conversations via the `SlashCommand` tool.

**Enable**: Commands with `description` in frontmatter are auto-enabled.

**Disable specific command**:
```yaml
---
description: Sensitive operation
disable-model-invocation: true
---
```

**Disable all autonomous slash commands** (via settings.json):
```json
{
  "permissions": {
    "deny": ["SlashCommand"]
  }
}
```

## Slash Commands vs Skills

**Use slash commands when**:
- Simple, frequently-invoked prompts
- Quick reminders or templates
- Single-file instructions
- User explicitly invokes with `/command`

**Use skills when**:
- Complex multi-step workflows
- Multiple supporting files (scripts, references, assets)
- Claude should autonomously decide when to use
- Rich documentation and validation logic

**Key difference**: Slash commands are user-invoked (`/command`), skills are model-invoked (Claude decides based on description).

## Testing Workflow

1. **Create command file** with proper frontmatter
2. **Restart Claude Code** (or start new conversation)
3. **Check `/help`** - verify command appears with description
4. **Test without args**: `/<command-name>`
5. **Test with args**: `/<command-name> arg1 arg2`
6. **Verify behavior**: Check arguments pass correctly and bash execution works

## Complete API Reference

For full slash command specification including:
- Complete frontmatter field list
- Plugin command patterns
- MCP slash command integration
- Permission control patterns
- Advanced bash execution patterns
- File reference syntax

See [references/anthropic-slash-commands-docs.md](references/anthropic-slash-commands-docs.md)

## Improving This Skill

Notice gaps, unclear instructions, or better patterns while using this skill?

Use the `continuous-improvement` skill to propose enhancements:
1. Detect the issue
2. Propose specific changes
3. Git branch → commit → surface for approval
4. Update changelog

This skill should evolve with every use.
