# Command Format

Reference for command file structure and YAML frontmatter syntax.

## File Structure

```markdown
---
# YAML Frontmatter
description: Brief description for /help
argument-hint: [param]
allowed-tools: [Read, Write]
---

# Command Body (Markdown)
Instructions for Claude...
```

## Frontmatter Fields

### Required Fields

| Field | Type | Description |
|-------|------|-------------|
| `description` | string | Shown in `/help` menu, used for discovery |

### Optional Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `argument-hint` | string | - | UI hint showing expected parameters |
| `allowed-tools` | array | all | Tool whitelist (see permissions.md) |
| `model` | string | session | Override model (e.g., `claude-3-5-sonnet-20241022`) |
| `hooks` | object | - | Command-level lifecycle hooks |

## Example: Complete Frontmatter

```yaml
---
description: Generate a detailed code review with security focus
argument-hint: [file-or-directory]
allowed-tools:
  - Read
  - Bash(git diff *)
  - Bash(git log *)
model: claude-3-5-sonnet-20241022
hooks:
  PostToolUse:
    - matcher: Write
      command: "npx prettier --write $FILE"
---
```

## File Naming

| Pattern | Example | Invocation |
|---------|---------|------------|
| Root file | `review.md` | `/review` |
| Nested file | `dev/review.md` | `/dev:review` |
| Hyphenated | `code-review.md` | `/code-review` |

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Missing `---` delimiters | Add `---` before and after frontmatter |
| Using tabs | Use spaces for YAML indentation |
| Empty description | Always provide meaningful description |
| Special characters in description | Quote strings with `:`, `#`, etc. |
