---
name: command-manager
source: botcore
description: >
  Create, validate, and organize Claude slash commands. Covers frontmatter syntax,
  variable injection, context operators, permissions, and namespace patterns.
  Use when creating commands, debugging invocations, or organizing command libraries.
version: "1.1.0"
triggers:
  - command
  - slash command
  - /command
  - argument
  - allowed-tools
  - "!bash"
  - "@file"
---

# Command Manager

Create and maintain Claude slash commands with consistent patterns and automated validation.

## Capabilities

1. **Create commands** — Templates and format guidance
2. **Validate commands** — Automated linting
3. **Organize commands** — Namespace patterns
4. **Configure permissions** — allowed-tools syntax

## Quick Commands

```powershell
# Lint all commands
.\scripts\command-lint.ps1 -Path ".claude/commands"

# Lint with JSON output
.\scripts\command-lint.ps1 -Path ".claude/commands" -Format json

# Strict mode (warnings = errors)
.\scripts\command-lint.ps1 -Path ".claude/commands" -Strict
```

## Routing Logic

| Request type | Load reference |
|--------------|----------------|
| Frontmatter syntax | [references/format.md](references/format.md) |
| Variable injection ($1, $ARGUMENTS) | [references/variables.md](references/variables.md) |
| Context operators (!, @) | [references/context-injection.md](references/context-injection.md) |
| Tool permissions | [references/permissions.md](references/permissions.md) |
| Directory organization | [references/namespacing.md](references/namespacing.md) |
| Command-level hooks | [references/hooks.md](references/hooks.md) |
| Full specification | [references/commands-specification.md](references/commands-specification.md) |

## Command Format Overview

```markdown
---
description: Brief description for /help menu
argument-hint: [param1] [param2]
allowed-tools: [Bash(git *), Read, Write]
model: claude-3-5-sonnet-20241022
---

# Command Title

Instructions for Claude...

## Context
!git status
@docs/guidelines.md

## Task
Using $ARGUMENTS, perform the requested action.
```

## Key Concepts

### Variable Injection

| Syntax | Description | Example |
|--------|-------------|---------|
| `$ARGUMENTS` | All arguments as string | "fix the login bug" |
| `$1`, `$2` | Positional arguments | `$1`="FRONTEND", `$2`="HIGH" |
| `!command` | Bash stdout injection | `!git diff --staged` |
| `@path` | File content injection | `@docs/STYLE.md` |

### Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `description` | Yes | Shown in `/help` menu |
| `argument-hint` | No | UI hint for parameters |
| `allowed-tools` | No | Tool whitelist |
| `model` | No | Override default model |
| `hooks` | No | Lifecycle hooks |

### Namespace Pattern

Organize commands in subdirectories:
```
.claude/commands/
├── dev/
│   ├── lint.md       → /dev:lint
│   └── review.md     → /dev:review
├── git/
│   └── commit.md     → /git:commit
└── quick-fix.md      → /quick-fix
```

## Core Principles

### 1. Explicit Invocation
Commands are user-triggered macros, not auto-discovered. Design for explicit workflows.

### 2. Context Gathering
Use `!` and `@` operators to gather context before Claude processes — don't ask users to paste.

### 3. Least Privilege
Restrict `allowed-tools` to only what's needed. Use patterns like `Bash(git *)` instead of `Bash(*)`.

### 4. Structured Output
Include output format specifications in prompts (Markdown tables, XML tags, etc.).

## When to Escalate

- **Complex orchestration** — Consider subagents or skills
- **Dynamic tool discovery** — Use MCP instead
- **Cross-project patterns** — Create a skill
- **Security policies** — Use global hooks in settings.json
