8.0 KiB

Raw Blame History

Command Frontmatter Reference

Complete reference for all frontmatter fields in Claude Code slash commands.

Overview

Frontmatter is optional YAML metadata at the start of command files. It configures how the command appears in /help, what tools it can use, and how it behaves.

---
description: Brief description for /help
argument-hint: <required> [optional]
allowed-tools: Read, Grep, Glob
model: haiku
disable-model-invocation: true
---

Fields

`description`

Type: string Default: First line of command content Purpose: Brief explanation shown in /help list

description: Deploy application to target environment with health checks

Best practices:

Keep under 80 characters
Action-oriented (start with verb)
Specific about what it does
Avoid vague terms like "helps with" or "stuff"

Examples:

# Good
description: Create git commit from staged changes with conventional format
description: Review PR for security vulnerabilities and best practices
description: Generate API documentation from TypeScript source files

# Bad
description: Deploy stuff
description: Helps with git
description: Command for reviewing things

`argument-hint`

Type: string Default: none Purpose: Show expected arguments in autocomplete

argument-hint: <environment> [--skip-tests] [--no-notify]

Conventions:

<required> - Required arguments (angle brackets)
[optional] - Optional arguments (square brackets)
--flag - Boolean flags
<arg1|arg2> - Alternatives (pipe-separated)

Examples:

# Single required argument
argument-hint: <issue-number>

# Multiple arguments
argument-hint: <file1> <file2>

# Optional with defaults
argument-hint: [environment=staging]

# Flags
argument-hint: <branch> [--force] [--no-verify]

# Alternatives
argument-hint: <staging|production>

`allowed-tools`

Type: string (comma-separated) Default: Inherits from conversation Purpose: Restrict which tools Claude can use

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

Tool names (case-sensitive):

File Operations

Tool	Purpose	Returns
`Read`	Read file contents, images, PDFs, Jupyter notebooks	File content with line numbers
`Write`	Create new files or overwrite existing files	Confirmation
`Edit`	Make targeted string replacements in existing files	Updated file snippet
`MultiEdit`	Multiple edits to a single file in one atomic operation	Updated file
`NotebookEdit`	Edit, insert, or delete Jupyter notebook cells	Updated notebook
`LS`	List directory contents	Directory listing

Search & Discovery

Tool	Purpose	Returns
`Grep`	Search file contents using regex patterns	Matching lines, file paths, or counts
`Glob`	Find files by name/path glob patterns (e.g., `*/.ts`)	List of matching file paths

Execution

Tool	Purpose	Returns
`Bash`	Execute shell commands with optional timeout	Command stdout/stderr
`Task`	Launch subagents for complex, parallel, or specialized work	Agent result or task ID (if background)
`TaskOutput`	Retrieve output from background tasks	Task output and status
`KillShell`	Terminate a running background shell process	Confirmation

Context & Skills

Tool	Purpose	Returns
`Skill`	Load a skill's instructions into context	Skill content
`TaskCreate`	Create tasks for tracking progress	Task ID
`TaskUpdate`	Update task status (in_progress, completed)	Confirmation
`TaskList`	List all tasks	Task summaries
`TaskGet`	Get full task details	Task details

Planning

Tool	Purpose	Returns
`EnterPlanMode`	Transition to plan mode for complex implementation tasks	User approval prompt
`ExitPlanMode`	Signal plan completion and request user approval	Plan review prompt

User Interaction

Tool	Purpose	Returns
`AskUserQuestion`	Present choices or gather input with structured options	User's selection(s) or custom input
`SlashCommand`	Invoke slash commands programmatically (controlled via `disable-model-invocation`)	Command result

Web

Tool	Purpose	Returns
`WebSearch`	Search the web for current information	Search results with URLs
`WebFetch`	Fetch URL content and process with AI	Processed/summarized content

MCP Tools

MCP (Model Context Protocol) tools follow the naming pattern mcp__<server>__<tool>. Examples:

mcp__github__create_issue - GitHub MCP server
mcp__memory__search - Memory MCP server
mcp__filesystem__read - Filesystem MCP server

Use regex patterns to match MCP tools: mcp__.*__.* matches all MCP tools.

Bash patterns:

# All bash commands
allowed-tools: Bash(*)

# All git commands
allowed-tools: Bash(git *)

# Specific git commands only
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git status:*)

# Multiple command types
allowed-tools: Bash(git *), Bash(npm *), Bash(bun *)

Common patterns:

# Read-only analysis
allowed-tools: Read, Grep, Glob

# Git workflow
allowed-tools: Read, Write, Edit, Bash(git *)

# Safe code review
allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git show:*)

# Full development
allowed-tools: Read, Write, Edit, Bash(*), Grep, Glob

Behavior:

Without allowed-tools: inherits conversation permissions
With allowed-tools: only listed tools allowed without asking
Other tools blocked or require explicit permission

`model`

Type: string Default: Inherits from conversation Purpose: Override model for this command

model: haiku

Available models:

# Fast, low-cost (simple tasks)
model: haiku

# Balanced (default for most)
model: sonnet

# Most capable (complex analysis)
model: opus

Use cases:

Simple commands (formatting, simple lookups) -> haiku
Standard development tasks -> sonnet (default)
Complex analysis, security review -> opus

`disable-model-invocation`

Type: boolean Default: false Purpose: Prevent SlashCommand tool from invoking this command automatically

disable-model-invocation: true

When to use:

Interactive commands requiring user input
Destructive operations (delete, deploy to production)
Commands with side effects that shouldn't be automated
Testing or debugging commands

Behavior:

When true: Command can only be invoked explicitly by user
When false (default): Claude can invoke via SlashCommand tool

Complete Example

---
description: Deploy application with full validation pipeline
argument-hint: <environment> [--skip-tests] [--force]
allowed-tools: Read, Bash(kubectl *), Bash(docker *), Bash(git *)
model: sonnet
disable-model-invocation: true
---

# Deployment Pipeline

Environment: $1
Options: $ARGUMENTS

## Pre-flight Checks
...

Validation Checklist

Frontmatter opens with --- on line 1
Frontmatter closes with --- before content
Uses spaces, not tabs
Special characters in strings are quoted
Field names are lowercase with hyphens
Tool names in allowed-tools are case-sensitive
Model identifier is valid if specified
Description is action-oriented and specific

Common Errors

Tab characters:

# Bad (tabs)
description: Deploy to staging

# Good (spaces)
description: Deploy to staging

Unquoted special characters:

# Bad (colon in value)
description: Review: code quality check

# Good (quoted)
description: "Review: code quality check"

Wrong tool names:

# Bad (lowercase)
allowed-tools: read, grep, glob

# Good (proper case)
allowed-tools: Read, Grep, Glob

Invalid model:

# Bad (non-existent)
model: gpt-4

# Good (valid Claude model)
model: haiku

8.0 KiB Raw Blame History