surshar / claude-code
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.
Built by Anthropic · github.com/anthropics
| 1 | # Command Frontmatter Reference |
| 2 | |
| 3 | Complete reference for YAML frontmatter fields in slash commands. |
| 4 | |
| 5 | ## Frontmatter Overview |
| 6 | |
| 7 | YAML frontmatter is optional metadata at the start of command files: |
| 8 | |
| 9 | ```markdown |
| 10 | --- |
| 11 | description: Brief description |
| 12 | allowed-tools: Read, Write |
| 13 | model: sonnet |
| 14 | argument-hint: [arg1] [arg2] |
| 15 | --- |
| 16 | |
| 17 | Command prompt content here... |
| 18 | ``` |
| 19 | |
| 20 | All fields are optional. Commands work without any frontmatter. |
| 21 | |
| 22 | ## Field Specifications |
| 23 | |
| 24 | ### description |
| 25 | |
| 26 | **Type:** String |
| 27 | **Required:** No |
| 28 | **Default:** First line of command prompt |
| 29 | **Max Length:** ~60 characters recommended for `/help` display |
| 30 | |
| 31 | **Purpose:** Describes what the command does, shown in `/help` output |
| 32 | |
| 33 | **Examples:** |
| 34 | ```yaml |
| 35 | description: Review code for security issues |
| 36 | ``` |
| 37 | ```yaml |
| 38 | description: Deploy to staging environment |
| 39 | ``` |
| 40 | ```yaml |
| 41 | description: Generate API documentation |
| 42 | ``` |
| 43 | |
| 44 | **Best practices:** |
| 45 | - Keep under 60 characters for clean display |
| 46 | - Start with verb (Review, Deploy, Generate) |
| 47 | - Be specific about what command does |
| 48 | - Avoid redundant "command" or "slash command" |
| 49 | |
| 50 | **Good:** |
| 51 | - ✅ "Review PR for code quality and security" |
| 52 | - ✅ "Deploy application to specified environment" |
| 53 | - ✅ "Generate comprehensive API documentation" |
| 54 | |
| 55 | **Bad:** |
| 56 | - ❌ "This command reviews PRs" (unnecessary "This command") |
| 57 | - ❌ "Review" (too vague) |
| 58 | - ❌ "A command that reviews pull requests for code quality, security issues, and best practices" (too long) |
| 59 | |
| 60 | ### allowed-tools |
| 61 | |
| 62 | **Type:** String or Array of strings |
| 63 | **Required:** No |
| 64 | **Default:** Inherits from conversation permissions |
| 65 | |
| 66 | **Purpose:** Restrict or specify which tools command can use |
| 67 | |
| 68 | **Formats:** |
| 69 | |
| 70 | **Single tool:** |
| 71 | ```yaml |
| 72 | allowed-tools: Read |
| 73 | ``` |
| 74 | |
| 75 | **Multiple tools (comma-separated):** |
| 76 | ```yaml |
| 77 | allowed-tools: Read, Write, Edit |
| 78 | ``` |
| 79 | |
| 80 | **Multiple tools (array):** |
| 81 | ```yaml |
| 82 | allowed-tools: |
| 83 | - Read |
| 84 | - Write |
| 85 | - Bash(git:*) |
| 86 | ``` |
| 87 | |
| 88 | **Tool Patterns:** |
| 89 | |
| 90 | **Specific tools:** |
| 91 | ```yaml |
| 92 | allowed-tools: Read, Grep, Edit |
| 93 | ``` |
| 94 | |
| 95 | **Bash with command filter:** |
| 96 | ```yaml |
| 97 | allowed-tools: Bash(git:*) # Only git commands |
| 98 | allowed-tools: Bash(npm:*) # Only npm commands |
| 99 | allowed-tools: Bash(docker:*) # Only docker commands |
| 100 | ``` |
| 101 | |
| 102 | **All tools (not recommended):** |
| 103 | ```yaml |
| 104 | allowed-tools: "*" |
| 105 | ``` |
| 106 | |
| 107 | **When to use:** |
| 108 | |
| 109 | 1. **Security:** Restrict command to safe operations |
| 110 | ```yaml |
| 111 | allowed-tools: Read, Grep # Read-only command |
| 112 | ``` |
| 113 | |
| 114 | 2. **Clarity:** Document required tools |
| 115 | ```yaml |
| 116 | allowed-tools: Bash(git:*), Read |
| 117 | ``` |
| 118 | |
| 119 | 3. **Bash execution:** Enable bash command output |
| 120 | ```yaml |
| 121 | allowed-tools: Bash(git status:*), Bash(git diff:*) |
| 122 | ``` |
| 123 | |
| 124 | **Best practices:** |
| 125 | - Be as restrictive as possible |
| 126 | - Use command filters for Bash (e.g., `git:*` not `*`) |
| 127 | - Only specify when different from conversation permissions |
| 128 | - Document why specific tools are needed |
| 129 | |
| 130 | ### model |
| 131 | |
| 132 | **Type:** String |
| 133 | **Required:** No |
| 134 | **Default:** Inherits from conversation |
| 135 | **Values:** `sonnet`, `opus`, `haiku` |
| 136 | |
| 137 | **Purpose:** Specify which Claude model executes the command |
| 138 | |
| 139 | **Examples:** |
| 140 | ```yaml |
| 141 | model: haiku # Fast, efficient for simple tasks |
| 142 | ``` |
| 143 | ```yaml |
| 144 | model: sonnet # Balanced performance (default) |
| 145 | ``` |
| 146 | ```yaml |
| 147 | model: opus # Maximum capability for complex tasks |
| 148 | ``` |
| 149 | |
| 150 | **When to use:** |
| 151 | |
| 152 | **Use `haiku` for:** |
| 153 | - Simple, formulaic commands |
| 154 | - Fast execution needed |
| 155 | - Low complexity tasks |
| 156 | - Frequent invocations |
| 157 | |
| 158 | ```yaml |
| 159 | --- |
| 160 | description: Format code file |
| 161 | model: haiku |
| 162 | --- |
| 163 | ``` |
| 164 | |
| 165 | **Use `sonnet` for:** |
| 166 | - Standard commands (default) |
| 167 | - Balanced speed/quality |
| 168 | - Most common use cases |
| 169 | |
| 170 | ```yaml |
| 171 | --- |
| 172 | description: Review code changes |
| 173 | model: sonnet |
| 174 | --- |
| 175 | ``` |
| 176 | |
| 177 | **Use `opus` for:** |
| 178 | - Complex analysis |
| 179 | - Architectural decisions |
| 180 | - Deep code understanding |
| 181 | - Critical tasks |
| 182 | |
| 183 | ```yaml |
| 184 | --- |
| 185 | description: Analyze system architecture |
| 186 | model: opus |
| 187 | --- |
| 188 | ``` |
| 189 | |
| 190 | **Best practices:** |
| 191 | - Omit unless specific need |
| 192 | - Use `haiku` for speed when possible |
| 193 | - Reserve `opus` for genuinely complex tasks |
| 194 | - Test with different models to find right balance |
| 195 | |
| 196 | ### argument-hint |
| 197 | |
| 198 | **Type:** String |
| 199 | **Required:** No |
| 200 | **Default:** None |
| 201 | |
| 202 | **Purpose:** Document expected arguments for users and autocomplete |
| 203 | |
| 204 | **Format:** |
| 205 | ```yaml |
| 206 | argument-hint: [arg1] [arg2] [optional-arg] |
| 207 | ``` |
| 208 | |
| 209 | **Examples:** |
| 210 | |
| 211 | **Single argument:** |
| 212 | ```yaml |
| 213 | argument-hint: [pr-number] |
| 214 | ``` |
| 215 | |
| 216 | **Multiple required arguments:** |
| 217 | ```yaml |
| 218 | argument-hint: [environment] [version] |
| 219 | ``` |
| 220 | |
| 221 | **Optional arguments:** |
| 222 | ```yaml |
| 223 | argument-hint: [file-path] [options] |
| 224 | ``` |
| 225 | |
| 226 | **Descriptive names:** |
| 227 | ```yaml |
| 228 | argument-hint: [source-branch] [target-branch] [commit-message] |
| 229 | ``` |
| 230 | |
| 231 | **Best practices:** |
| 232 | - Use square brackets `[]` for each argument |
| 233 | - Use descriptive names (not `arg1`, `arg2`) |
| 234 | - Indicate optional vs required in description |
| 235 | - Match order to positional arguments in command |
| 236 | - Keep concise but clear |
| 237 | |
| 238 | **Examples by pattern:** |
| 239 | |
| 240 | **Simple command:** |
| 241 | ```yaml |
| 242 | --- |
| 243 | description: Fix issue by number |
| 244 | argument-hint: [issue-number] |
| 245 | --- |
| 246 | |
| 247 | Fix issue #$1... |
| 248 | ``` |
| 249 | |
| 250 | **Multi-argument:** |
| 251 | ```yaml |
| 252 | --- |
| 253 | description: Deploy to environment |
| 254 | argument-hint: [app-name] [environment] [version] |
| 255 | --- |
| 256 | |
| 257 | Deploy $1 to $2 using version $3... |
| 258 | ``` |
| 259 | |
| 260 | **With options:** |
| 261 | ```yaml |
| 262 | --- |
| 263 | description: Run tests with options |
| 264 | argument-hint: [test-pattern] [options] |
| 265 | --- |
| 266 | |
| 267 | Run tests matching $1 with options: $2 |
| 268 | ``` |
| 269 | |
| 270 | ### disable-model-invocation |
| 271 | |
| 272 | **Type:** Boolean |
| 273 | **Required:** No |
| 274 | **Default:** false |
| 275 | |
| 276 | **Purpose:** Prevent SlashCommand tool from programmatically invoking command |
| 277 | |
| 278 | **Examples:** |
| 279 | ```yaml |
| 280 | disable-model-invocation: true |
| 281 | ``` |
| 282 | |
| 283 | **When to use:** |
| 284 | |
| 285 | 1. **Manual-only commands:** Commands requiring user judgment |
| 286 | ```yaml |
| 287 | --- |
| 288 | description: Approve deployment to production |
| 289 | disable-model-invocation: true |
| 290 | --- |
| 291 | ``` |
| 292 | |
| 293 | 2. **Destructive operations:** Commands with irreversible effects |
| 294 | ```yaml |
| 295 | --- |
| 296 | description: Delete all test data |
| 297 | disable-model-invocation: true |
| 298 | --- |
| 299 | ``` |
| 300 | |
| 301 | 3. **Interactive workflows:** Commands needing user input |
| 302 | ```yaml |
| 303 | --- |
| 304 | description: Walk through setup wizard |
| 305 | disable-model-invocation: true |
| 306 | --- |
| 307 | ``` |
| 308 | |
| 309 | **Default behavior (false):** |
| 310 | - Command available to SlashCommand tool |
| 311 | - Claude can invoke programmatically |
| 312 | - Still available for manual invocation |
| 313 | |
| 314 | **When true:** |
| 315 | - Command only invokable by user typing `/command` |
| 316 | - Not available to SlashCommand tool |
| 317 | - Safer for sensitive operations |
| 318 | |
| 319 | **Best practices:** |
| 320 | - Use sparingly (limits Claude's autonomy) |
| 321 | - Document why in command comments |
| 322 | - Consider if command should exist if always manual |
| 323 | |
| 324 | ## Complete Examples |
| 325 | |
| 326 | ### Minimal Command |
| 327 | |
| 328 | No frontmatter needed: |
| 329 | |
| 330 | ```markdown |
| 331 | Review this code for common issues and suggest improvements. |
| 332 | ``` |
| 333 | |
| 334 | ### Simple Command |
| 335 | |
| 336 | Just description: |
| 337 | |
| 338 | ```markdown |
| 339 | --- |
| 340 | description: Review code for issues |
| 341 | --- |
| 342 | |
| 343 | Review this code for common issues and suggest improvements. |
| 344 | ``` |
| 345 | |
| 346 | ### Standard Command |
| 347 | |
| 348 | Description and tools: |
| 349 | |
| 350 | ```markdown |
| 351 | --- |
| 352 | description: Review Git changes |
| 353 | allowed-tools: Bash(git:*), Read |
| 354 | --- |
| 355 | |
| 356 | Current changes: !`git diff --name-only` |
| 357 | |
| 358 | Review each changed file for: |
| 359 | - Code quality |
| 360 | - Potential bugs |
| 361 | - Best practices |
| 362 | ``` |
| 363 | |
| 364 | ### Complex Command |
| 365 | |
| 366 | All common fields: |
| 367 | |
| 368 | ```markdown |
| 369 | --- |
| 370 | description: Deploy application to environment |
| 371 | argument-hint: [app-name] [environment] [version] |
| 372 | allowed-tools: Bash(kubectl:*), Bash(helm:*), Read |
| 373 | model: sonnet |
| 374 | --- |
| 375 | |
| 376 | Deploy $1 to $2 environment using version $3 |
| 377 | |
| 378 | Pre-deployment checks: |
| 379 | - Verify $2 configuration |
| 380 | - Check cluster status: !`kubectl cluster-info` |
| 381 | - Validate version $3 exists |
| 382 | |
| 383 | Proceed with deployment following deployment runbook. |
| 384 | ``` |
| 385 | |
| 386 | ### Manual-Only Command |
| 387 | |
| 388 | Restricted invocation: |
| 389 | |
| 390 | ```markdown |
| 391 | --- |
| 392 | description: Approve production deployment |
| 393 | argument-hint: [deployment-id] |
| 394 | disable-model-invocation: true |
| 395 | allowed-tools: Bash(gh:*) |
| 396 | --- |
| 397 | |
| 398 | <!-- |
| 399 | MANUAL APPROVAL REQUIRED |
| 400 | This command requires human judgment and cannot be automated. |
| 401 | --> |
| 402 | |
| 403 | Review deployment $1 for production approval: |
| 404 | |
| 405 | Deployment details: !`gh api /deployments/$1` |
| 406 | |
| 407 | Verify: |
| 408 | - All tests passed |
| 409 | - Security scan clean |
| 410 | - Stakeholder approval |
| 411 | - Rollback plan ready |
| 412 | |
| 413 | Type "APPROVED" to confirm deployment. |
| 414 | ``` |
| 415 | |
| 416 | ## Validation |
| 417 | |
| 418 | ### Common Errors |
| 419 | |
| 420 | **Invalid YAML syntax:** |
| 421 | ```yaml |
| 422 | --- |
| 423 | description: Missing quote |
| 424 | allowed-tools: Read, Write |
| 425 | model: sonnet |
| 426 | --- # ❌ Missing closing quote above |
| 427 | ``` |
| 428 | |
| 429 | **Fix:** Validate YAML syntax |
| 430 | |
| 431 | **Incorrect tool specification:** |
| 432 | ```yaml |
| 433 | allowed-tools: Bash # ❌ Missing command filter |
| 434 | ``` |
| 435 | |
| 436 | **Fix:** Use `Bash(git:*)` format |
| 437 | |
| 438 | **Invalid model name:** |
| 439 | ```yaml |
| 440 | model: gpt4 # ❌ Not a valid Claude model |
| 441 | ``` |
| 442 | |
| 443 | **Fix:** Use `sonnet`, `opus`, or `haiku` |
| 444 | |
| 445 | ### Validation Checklist |
| 446 | |
| 447 | Before committing command: |
| 448 | - [ ] YAML syntax valid (no errors) |
| 449 | - [ ] Description under 60 characters |
| 450 | - [ ] allowed-tools uses proper format |
| 451 | - [ ] model is valid value if specified |
| 452 | - [ ] argument-hint matches positional arguments |
| 453 | - [ ] disable-model-invocation used appropriately |
| 454 | |
| 455 | ## Best Practices Summary |
| 456 | |
| 457 | 1. **Start minimal:** Add frontmatter only when needed |
| 458 | 2. **Document arguments:** Always use argument-hint with arguments |
| 459 | 3. **Restrict tools:** Use most restrictive allowed-tools that works |
| 460 | 4. **Choose right model:** Use haiku for speed, opus for complexity |
| 461 | 5. **Manual-only sparingly:** Only use disable-model-invocation when necessary |
| 462 | 6. **Clear descriptions:** Make commands discoverable in `/help` |
| 463 | 7. **Test thoroughly:** Verify frontmatter works as expected |