plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md

Command Frontmatter Reference

Complete reference for YAML frontmatter fields in slash commands.

Frontmatter Overview

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

---
description: Brief description
allowed-tools: Read, Write
model: sonnet
argument-hint: [arg1] [arg2]
---

Command prompt content here...

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:

description: Review code for security issues

description: Deploy to staging environment

description: Generate API documentation

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:

allowed-tools: Read

Multiple tools (comma-separated):

allowed-tools: Read, Write, Edit

Multiple tools (array):

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

Tool Patterns:

Specific tools:

allowed-tools: Read, Grep, Edit

Bash with command filter:

allowed-tools: Bash(git:*)           # Only git commands
allowed-tools: Bash(npm:*)           # Only npm commands
allowed-tools: Bash(docker:*)        # Only docker commands

All tools (not recommended):

allowed-tools: "*"

When to use:

1. Security: Restrict command to safe operations

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

2. Clarity: Document required tools

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

3. Bash execution: Enable bash command output

   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:

model: haiku    # Fast, efficient for simple tasks

model: sonnet   # Balanced performance (default)

model: opus     # Maximum capability for complex tasks

When to use:

Use haiku for:

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

---
description: Format code file
model: haiku
---

Use sonnet for:

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

---
description: Review code changes
model: sonnet
---

Use opus for:

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

---
description: Analyze system architecture
model: opus
---

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:

argument-hint: [arg1] [arg2] [optional-arg]

Examples:

Single argument:

argument-hint: [pr-number]

Multiple required arguments:

argument-hint: [environment] [version]

Optional arguments:

argument-hint: [file-path] [options]

Descriptive names:

argument-hint: [source-branch] [target-branch] [commit-message]

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: ```yaml

description: Fix issue by number argument-hint: [issue-number]

Fix issue #$1...

**Multi-argument:**
```yaml
---
description: Deploy to environment
argument-hint: [app-name] [environment] [version]
---

Deploy $1 to $2 using version $3...

With options: ```yaml

description: Run tests with options argument-hint: [test-pattern] [options]

Run tests matching $1 with options: $2

### disable-model-invocation

**Type:** Boolean
**Required:** No
**Default:** false

**Purpose:** Prevent SlashCommand tool from programmatically invoking command

**Examples:**
```yaml
disable-model-invocation: true

When to use:

1. Manual-only commands: Commands requiring user judgment ```yaml

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

2. Destructive operations: Commands with irreversible effects ```yaml

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

3. Interactive workflows: Commands needing user input ```yaml

   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:

Review this code for common issues and suggest improvements.

Simple Command

Just description:

---
description: Review code for issues
---

Review this code for common issues and suggest improvements.

Standard Command

Description and tools:

---
description: Review Git changes
allowed-tools: Bash(git:*), Read
---

Current changes: !`git diff --name-only`

Review each changed file for:
- Code quality
- Potential bugs
- Best practices

Complex Command

All common fields:

---
description: Deploy application to environment
argument-hint: [app-name] [environment] [version]
allowed-tools: Bash(kubectl:*), Bash(helm:*), Read
model: sonnet
---

Deploy $1 to $2 environment using version $3

Pre-deployment checks:
- Verify $2 configuration
- Check cluster status: !`kubectl cluster-info`
- Validate version $3 exists

Proceed with deployment following deployment runbook.

Manual-Only Command

Restricted invocation:

---
description: Approve production deployment
argument-hint: [deployment-id]
disable-model-invocation: true
allowed-tools: Bash(gh:*)
---

<!--
MANUAL APPROVAL REQUIRED
This command requires human judgment and cannot be automated.
-->

Review deployment $1 for production approval:

Deployment details: !`gh api /deployments/$1`

Verify:
- All tests passed
- Security scan clean
- Stakeholder approval
- Rollback plan ready

Type "APPROVED" to confirm deployment.

Validation

Common Errors

Invalid YAML syntax: ```yaml

description: Missing quote allowed-tools: Read, Write model: sonnet --- # ❌ Missing closing quote above

**Fix:** Validate YAML syntax

**Incorrect tool specification:**
```yaml
allowed-tools: Bash  # ❌ Missing command filter

Fix: Use Bash(git:*) format

Invalid model name:

model: gpt4  # ❌ Not a valid Claude model

Fix: Use sonnet, opus, or haiku

Validation Checklist

Before committing command:

• YAML syntax valid (no errors)
• Description under 60 characters
• allowed-tools uses proper format
• model is valid value if specified
• argument-hint matches positional arguments
• 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