Frontmatter Reference

YAML frontmatter is optional metadata at the start of command files:

All fields are optional. Commands work without any frontmatter.

Field Specifications

description

Type: String Required: No Default: First line of command prompt Max Length: ~60 characters recommended for /help display

Purpose: Describes what the command does, shown in /help output

Examples:

Best practices:

• Keep under 60 characters for clean display
• Start with verb (Review, Deploy, Generate)
• Be specific about what command does
• Avoid redundant “command” or “slash command”

Good:

• ✅ “Review PR for code quality and security”
• ✅ “Deploy application to specified environment”
• ✅ “Generate comprehensive API documentation”

Bad:

• ❌ “This command reviews PRs” (unnecessary “This command”)
• ❌ “Review” (too vague)
• ❌ “A command that reviews pull requests for code quality, security issues, and best practices” (too long)

allowed-tools

Type: String or Array of strings Required: No Default: Inherits from conversation permissions

Purpose: Restrict or specify which tools command can use

Formats:

Single tool:

Multiple tools (comma-separated):

Multiple tools (array):

Tool Patterns:

Specific tools:

Bash with command filter:

All tools (not recommended):

When to use:

1. Security: Restrict command to safe operations

   yamlCopy

   allowed-tools: Read, Grep  # Read-only command

2. Clarity: Document required tools

   yamlCopy

   allowed-tools: Bash(git:*), Read

3. Bash execution: Enable bash command output

   yamlCopy

   allowed-tools: Bash(git status:*), Bash(git diff:*)

Best practices:

• Be as restrictive as possible
• Use command filters for Bash (e.g., git:* not *)
• Only specify when different from conversation permissions
• Document why specific tools are needed

model

Type: String Required: No Default: Inherits from conversation Values: sonnet, opus, haiku

Purpose: Specify which Claude model executes the command

Examples:

When to use:

Use haiku for:

• Simple, formulaic commands
• Fast execution needed
• Low complexity tasks
• Frequent invocations

Use sonnet for:

• Standard commands (default)
• Balanced speed/quality
• Most common use cases

Use opus for:

• Complex analysis
• Architectural decisions
• Deep code understanding
• Critical tasks

Best practices:

• Omit unless specific need
• Use haiku for speed when possible
• Reserve opus for genuinely complex tasks
• Test with different models to find right balance

argument-hint

Type: String Required: No Default: None

Purpose: Document expected arguments for users and autocomplete

Format:

Examples:

Single argument:

Multiple required arguments:

Optional arguments:

Descriptive names:

Best practices:

• Use square brackets [] for each argument
• Use descriptive names (not arg1, arg2)
• Indicate optional vs required in description
• Match order to positional arguments in command
• Keep concise but clear

Examples by pattern:

Simple command:

Multi-argument:

With options:

disable-model-invocation

Type: Boolean Required: No Default: false

Purpose: Prevent SlashCommand tool from programmatically invoking command

Examples:

When to use:

1. Manual-only commands: Commands requiring user judgment

   yamlCopy

   ---
   description: Approve deployment to production
   disable-model-invocation: true
   ---

2. Destructive operations: Commands with irreversible effects

   yamlCopy

   ---
   description: Delete all test data
   disable-model-invocation: true
   ---

3. Interactive workflows: Commands needing user input

   yamlCopy

   ---
   description: Walk through setup wizard
   disable-model-invocation: true
   ---

Default behavior (false):

• Command available to SlashCommand tool
• Claude can invoke programmatically
• Still available for manual invocation

When true:

• Command only invokable by user typing /command
• Not available to SlashCommand tool
• Safer for sensitive operations

Best practices:

• Use sparingly (limits Claude’s autonomy)
• Document why in command comments
• Consider if command should exist if always manual

Complete Examples

Minimal Command

No frontmatter needed:

Simple Command

Just description:

Standard Command

Description and tools:

Complex Command

All common fields:

Manual-Only Command

Restricted invocation:

Validation

Common Errors

Invalid YAML syntax:

Fix: Validate YAML syntax

Incorrect tool specification:

Fix: Use Bash(git:*) format

Invalid model name:

Fix: Use sonnet, opus, or haiku

Validation Checklist

Before committing command:

• Not done: YAML syntax valid (no errors)
• Not done: Description under 60 characters
• Not done: allowed-tools uses proper format
• Not done: model is valid value if specified
• Not done: argument-hint matches positional arguments
• Not done: disable-model-invocation used appropriately

Best Practices Summary

1. Start minimal: Add frontmatter only when needed
2. Document arguments: Always use argument-hint with arguments
3. Restrict tools: Use most restrictive allowed-tools that works
4. Choose right model: Use haiku for speed, opus for complexity
5. Manual-only sparingly: Only use disable-model-invocation when necessary
6. Clear descriptions: Make commands discoverable in /help
7. Test thoroughly: Verify frontmatter works as expected