# Skill Frontmatter Reference

Complete reference for all SKILL.md YAML frontmatter fields, based on the official Claude Code documentation.

Source: https://code.claude.com/docs/en/skills

## Required Fields

### `name`
- **Type:** string
- **Required:** YES
- **Constraints:** lowercase, max 64 characters, kebab-case
- **Purpose:** Unique identifier. Becomes the `/name` command.
- **Examples:**
  ```yaml
  name: my-skill
  name: code-review
  name: deploy-staging
  ```

### `description`
- **Type:** string (multi-line supported)
- **Required:** YES
- **Purpose:** Claude uses this to decide when to auto-invoke the skill. Include trigger keywords.
- **Examples:**
  ```yaml
  description: Generate API controllers following REST conventions.

  description: |
    Deploy application to staging environment.
    Use this skill when:
    - User mentions "deploy", "staging", "release"
    - User wants to push changes to staging
    - Deployment pipeline needs to be triggered
  ```

## Optional Fields

### `disable-model-invocation`
- **Type:** boolean
- **Default:** false
- **Purpose:** When `true`, only the user can invoke via `/name`. Claude will never auto-invoke.
- **Use for:** Side-effect operations (deploy, commit, publish, delete)
- **Example:**
  ```yaml
  disable-model-invocation: true
  ```

### `user-invocable`
- **Type:** boolean
- **Default:** true
- **Purpose:** When `false`, skill is hidden from /menu. Used for background knowledge injection.
- **Example:**
  ```yaml
  user-invocable: false
  ```

### `allowed-tools`
- **Type:** string (comma-separated)
- **Default:** (none)
- **Purpose:** Tools the skill can use without triggering permission prompts.
- **Valid tools:** Read, Write, Edit, Bash, Glob, Grep, Task, WebFetch, WebSearch, NotebookEdit, AskUserQuestion, TodoWrite, Skill, ToolSearch
- **Example:**
  ```yaml
  allowed-tools: "Read, Grep, Glob, WebSearch, WebFetch"
  ```

### `model`
- **Type:** string
- **Default:** inherit
- **Valid values:** inherit, sonnet, opus, haiku
- **Purpose:** Override the model used when this skill runs.
- **Guidance:**
  - `haiku` - Fast, cheap. Simple tasks.
  - `sonnet` - Balanced. Most tasks.
  - `opus` - Most capable. Complex reasoning.
  - `inherit` - Use user's configured model.
- **Example:**
  ```yaml
  model: haiku
  ```

### `context`
- **Type:** string
- **Valid values:** fork
- **Purpose:** Run skill in an isolated subagent context. Separate conversation, clean state.
- **Example:**
  ```yaml
  context: fork
  ```

### `agent`
- **Type:** string
- **Purpose:** Which subagent type to use when `context: fork`.
- **Valid values:** Explore, Plan, general-purpose, Bash, or any custom agent name
- **Example:**
  ```yaml
  context: fork
  agent: Explore
  ```

### `argument-hint`
- **Type:** string
- **Purpose:** Autocomplete hint shown in the /menu.
- **Example:**
  ```yaml
  argument-hint: "<command> [options]"
  argument-hint: "[filename]"
  argument-hint: "<create|update> [name]"
  ```

### `hooks`
- **Type:** object
- **Purpose:** Lifecycle hooks scoped to this skill.
- **Events:** PreToolUse, PostToolUse, Stop, SessionStart, etc.
- **Example:**
  ```yaml
  hooks:
    PreToolUse:
      - matcher: "Bash"
        hooks:
          - type: command
            command: "./scripts/validate.sh"
  ```

## Dynamic Placeholders

Available in SKILL.md content (not frontmatter):

| Placeholder | Description |
|-------------|-------------|
| `$ARGUMENTS` | All arguments passed to skill |
| `$1`, `$2`, ... | Positional arguments |
| `$ARGUMENTS[0]` | Same as $1 |
| `${CLAUDE_SESSION_ID}` | Current session ID |
| `` !`command` `` | Run shell command, inject output |

## Examples

### Minimal Skill
```yaml
---
name: hello
description: Greet the user
---

Say hello to the user: $ARGUMENTS
```

### Side-Effect Skill
```yaml
---
name: deploy
description: Deploy to staging
disable-model-invocation: true
argument-hint: "[environment]"
---
```

### Research Skill
```yaml
---
name: search-code
description: Search codebase for patterns
context: fork
agent: Explore
allowed-tools: "Read, Grep, Glob"
argument-hint: "<query>"
---
```

### Complex Workflow
```yaml
---
name: generate-api
description: |
  Generate API endpoints. Use when:
  - Creating new API routes
  - Adding CRUD operations
argument-hint: "<entity> [--with-tests]"
---
```
