architecture/skills/capability-writing/reference/frontmatter-fields.md

# Frontmatter Fields Reference

Complete documentation of all available frontmatter fields for skills and agents.

## Skill Frontmatter

### Required Fields

#### `name`
- **Type:** string
- **Required:** Yes
- **Format:** Lowercase, hyphens only, no spaces
- **Max length:** 64 characters
- **Must match:** Directory name
- **Cannot contain:** XML tags, reserved words ("anthropic", "claude")
- **Example:** `work-issue`, `code-review`, `gitea`

#### `description`
- **Type:** string (multiline supported with `>`)
- **Required:** Yes
- **Max length:** 1024 characters
- **Cannot contain:** XML tags
- **Should include:**
  - What the skill does
  - When to use it
  - Trigger conditions
- **Example:**
  ```yaml
  description: >
    View, create, and manage Gitea issues and pull requests.
    Use when working with issues, PRs, or when user mentions tea, gitea, issue numbers.
  ```

#### `user-invocable`
- **Type:** boolean
- **Required:** Yes
- **Values:** `true` or `false`
- **Usage:**
  - `true`: User can trigger with `/skill-name`
  - `false`: Background skill, auto-loaded when needed

### Optional Fields

#### `model`
- **Type:** string
- **Required:** No
- **Values:** `haiku`, `sonnet`, `opus`
- **Default:** Inherits from parent (usually haiku)
- **Guidance:** Default to `haiku`, only upgrade if needed
- **Example:**
  ```yaml
  model: haiku  # 12x cheaper than sonnet
  ```

#### `argument-hint`
- **Type:** string
- **Required:** No (only for user-invocable skills)
- **Format:** `<required>` for required params, `[optional]` for optional
- **Shows in UI:** Helps users know what arguments to provide
- **Example:**
  ```yaml
  argument-hint: <issue-number>
  argument-hint: <issue-number> [optional-title]
  ```

#### `context`
- **Type:** string
- **Required:** No
- **Values:** `fork`
- **Usage:** Set to `fork` for skills needing isolated context
- **When to use:** Heavy exploration tasks that would pollute main context
- **Example:**
  ```yaml
  context: fork  # For arch-review-repo, deep exploration
  ```

#### `allowed-tools`
- **Type:** list of strings
- **Required:** No
- **Usage:** Restrict which tools the skill can use
- **Example:**
  ```yaml
  allowed-tools:
    - Read
    - Bash
    - Grep
  ```
- **Note:** Rarely used, most skills have all tools

## Agent Frontmatter

### Required Fields

#### `name`
- **Type:** string
- **Required:** Yes
- **Same rules as skill name**

#### `description`
- **Type:** string
- **Required:** Yes
- **Should include:**
  - What the agent does
  - When to spawn it
- **Example:**
  ```yaml
  description: >
    Automated code review of pull requests for quality, bugs, security, and style.
    Spawn when reviewing PRs or checking code quality.
  ```

### Optional Fields

#### `model`
- **Type:** string
- **Required:** No
- **Values:** `haiku`, `sonnet`, `opus`, `inherit`
- **Default:** `inherit` (uses parent's model)
- **Guidance:**
  - Default to `haiku` for simple agents
  - Use `sonnet` for balanced performance
  - Reserve `opus` for deep reasoning
- **Example:**
  ```yaml
  model: haiku  # Fast and cheap for code review checklist
  ```

#### `skills`
- **Type:** comma-separated list of skill names (not paths)
- **Required:** No
- **Usage:** Auto-load these skills when agent spawns
- **Format:** Just skill names, not paths
- **Example:**
  ```yaml
  skills: gitea, issue-writing, code-review
  ```
- **Note:** Agent runtime loads skills automatically

#### `disallowedTools`
- **Type:** list of tool names
- **Required:** No
- **Common use:** Make agents read-only
- **Example:**
  ```yaml
  disallowedTools:
    - Edit
    - Write
  ```
- **When to use:** Analysis agents that shouldn't modify code

#### `permissionMode`
- **Type:** string
- **Required:** No
- **Values:** `default`, `bypassPermissions`
- **Usage:** Rarely used, for agents that need to bypass permission prompts
- **Example:**
  ```yaml
  permissionMode: bypassPermissions
  ```

## Examples

### Minimal User-Invocable Skill

```yaml
---
name: dashboard
description: Show open issues, PRs, and CI status.
user-invocable: true
---
```

### Full-Featured Skill

```yaml
---
name: work-issue
description: >
  Implement a Gitea issue with full workflow: branch, plan, code, PR, review.
  Use when implementing issues or when user says /work-issue.
model: haiku
argument-hint: <issue-number>
user-invocable: true
---
```

### Background Skill

```yaml
---
name: gitea
description: >
  View, create, and manage Gitea issues and PRs using tea CLI.
  Use when working with issues, PRs, viewing issue details, or when user mentions tea, gitea, issue numbers.
user-invocable: false
---
```

### Read-Only Agent

```yaml
---
name: code-reviewer
description: >
  Automated code review of pull requests for quality, bugs, security, style, and test coverage.
model: sonnet
skills: gitea, code-review
disallowedTools:
  - Edit
  - Write
---
```

### Implementation Agent

```yaml
---
name: issue-worker
description: >
  Autonomously implements a single issue in an isolated git worktree.
model: haiku
skills: gitea, issue-writing, software-architecture
---
```

## Validation Rules

### Name Validation
- Must be lowercase
- Must use hyphens (not underscores or spaces)
- Cannot contain: `anthropic`, `claude`
- Cannot contain XML tags `<`, `>`
- Max 64 characters
- Must match directory name exactly

### Description Validation
- Cannot be empty
- Max 1024 characters
- Cannot contain XML tags
- Should end with period

### Model Validation
- Must be one of: `haiku`, `sonnet`, `opus`, `inherit`
- Case-sensitive (must be lowercase)

## Common Mistakes

**Bad: Using paths in skills field**
```yaml
skills: ~/.claude/skills/gitea/SKILL.md  # Wrong!
```

**Good: Just skill names**
```yaml
skills: gitea, issue-writing
```

**Bad: Reserved word in name**
```yaml
name: claude-helper  # Contains "claude"
```

**Good: Descriptive name**
```yaml
name: code-helper
```

**Bad: Vague description**
```yaml
description: Helps with stuff
```

**Good: Specific description**
```yaml
description: >
  Analyze Excel spreadsheets, create pivot tables, generate charts.
  Use when analyzing Excel files, spreadsheets, or .xlsx files.
```