Create Skill

# Frontmatter Options & Patterns Reference

**Authoritative source for skill/command frontmatter.** Keep current with Claude Code
releases — this file is the single source of truth used by create-skill. No live
documentation fetch is performed; accuracy depends on this file being maintained.

Load before writing frontmatter in Phase 1, Step 2. Contains the full field catalog,
description patterns, execution modifiers, tool selection framework, and progressive
disclosure patterns.

---

## Essential Frontmatter

Every skill needs these fields. Start here.

```yaml
# Complete field catalog — most skills only need: name, description, allowed-tools
---
name: identifier                    # Required — unique skill identifier
description: >                      # How it's described/triggered (see patterns below)
  [See description patterns below]
allowed-tools:                      # Restrict available tools (see Tool Selection below)
  - Read
  - Grep
  - Bash(git:*)

# Lifecycle hooks (optional, scoped to this skill's lifetime)
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "scripts/validate-input.sh"
          timeout: 10
          statusMessage: "Validating..."
  PostToolUse:
    - hooks:
        - type: command
          command: "scripts/cleanup.sh"
  Stop:
    - hooks:
        - type: command
          command: "scripts/on-complete.sh"
          once: true                # Skills only: run once, then auto-remove

# Execution context
context: fork                       # Run in a subagent (isolates from conversation)
agent: Explore                      # Subagent type when context: fork (default: general-purpose)
effort: high                        # Override session effort: low | medium | high | max (max: Opus 4.6 only)
paths: "*.py,src/**/*.ts"           # Glob patterns limiting auto-activation to matching files
shell: bash                         # Shell for bang+backtick inline-command blocks: bash (default) or powershell

# Behavior modifiers
user-invocable: true                # Show in /command menu (default true)
disable-model-invocation: true      # Prevent programmatic invocation (commands only)
argument-hint: "[arg1] [arg2]"      # Document expected arguments; quote if value contains [...]
---
```

**`argument-hint` quoting rule:** Values containing `[...]` must be quoted (`"[arg]"`), because YAML treats unquoted `[` as the start of a flow sequence. Values using only `<...>` do not need quoting.

## Advanced Frontmatter

Use when needed — most skills don't require these.

```yaml
# Lifecycle hooks (scoped to this skill's lifetime)
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "scripts/validate-input.sh"
          timeout: 10
          statusMessage: "Validating..."
  PostToolUse:
    - hooks:
        - type: command
          command: "scripts/cleanup.sh"
  Stop:
    - hooks:
        - type: command
          command: "scripts/on-complete.sh"
          once: true                # Skills only: run once, then auto-remove

# Execution context
context: fork                       # Run in a subagent (isolates from conversation)
agent: Explore                      # Subagent type when context: fork (default: general-purpose)
effort: high                        # Override session effort: low | medium | high | max (max: Opus 4.6 only)
paths: "*.py,src/**/*.ts"           # Glob patterns limiting auto-activation to matching files
shell: bash                         # Shell for bang+backtick inline-command blocks: bash (default) or powershell

# Behavior modifiers (commands)
disable-model-invocation: true      # Prevent programmatic invocation (commands only)
```

**Hooks structure:** Each hook event (PreToolUse, PostToolUse, Stop, SessionStart, etc.)
accepts an array of entries. Each entry can have a `matcher` (filter by tool name) and a
`hooks` array with handlers. Handler fields: `type` (command, http, prompt, agent),
`c