# Commands Specification

Complete technical reference for Claude slash commands.

## Command vs Skill

| Aspect | Command | Skill |
|--------|---------|-------|
| Invocation | Explicit (`/command`) | Automatic (model discovers) |
| Structure | Single `.md` file | Directory with `SKILL.md` |
| Context | Pollutes main history | Can fork context |
| Best for | User-driven workflows | Domain expertise |

## File Format

```markdown
---
description: Required description
argument-hint: [optional] [params]
allowed-tools: [Tool1, Tool2]
model: optional-model-override
hooks:
  PostToolUse:
    - matcher: ToolName
      command: "script.sh"
---

# Command Body

Instructions, context injection, prompts...
```

## Frontmatter Schema

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `description` | string | Yes | Help menu text (< 256 chars) |
| `argument-hint` | string | No | Parameter format hint |
| `allowed-tools` | array | No | Tool whitelist |
| `model` | string | No | Model override |
| `hooks` | object | No | Lifecycle hooks |

## Variable Injection

| Syntax | Description |
|--------|-------------|
| `$ARGUMENTS` | Full argument string |
| `$1`, `$2`, ... | Positional arguments |
| `!command` | Bash stdout injection |
| `@path` | File content injection |

## Tool Permission Patterns

| Pattern | Scope |
|---------|-------|
| `Bash(*)` | All bash (dangerous) |
| `Bash(git *)` | Git subcommands |
| `mcp__server__*` | All tools from MCP server |
| `Task(agent)` | Specific subagent |

## Directory Structure

```
.claude/commands/           # Project scope
~/.claude/commands/         # Global scope

# Namespaced
.claude/commands/dev/       # → /dev:*
.claude/commands/git/       # → /git:*
```

## Lifecycle Hooks

| Event | Timing | Use |
|-------|--------|-----|
| `UserPromptSubmit` | Before model | Validation |
| `PreToolUse` | Before tool | Blocking |
| `PostToolUse` | After tool | Automation |
| `Stop` | End of turn | Cleanup |

## Design Principles

### 1. Deterministic Context
Fetch context with `!` and `@` rather than asking users.

### 2. Guided Reasoning
Provide checklists and structured output formats.

### 3. External Standards
Reference project configs (`@.eslintrc.json`, `@tsconfig.json`).

### 4. Least Privilege
Scope `allowed-tools` to minimum required.

## Quality Checklist

- [ ] Description is concise (< 256 chars)
- [ ] `argument-hint` provided if needed
- [ ] `allowed-tools` scoped appropriately
- [ ] `!` commands covered by permissions
- [ ] `@` files exist
- [ ] Output format specified
- [ ] Negative constraints included

## Portability

Commands travel with the repository. When shared:
- Ensure `@` referenced files exist
- Document required tools in README
- Test across environments
