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:

  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:

  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:

  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:

  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:

  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:

  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:

  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:

  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:

  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:

  permissionMode: bypassPermissions
  

Examples

Minimal User-Invocable Skill

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

Full-Featured Skill

---
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

---
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

---
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

---
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

skills: ~/.claude/skills/gitea/SKILL.md  # Wrong!

Good: Just skill names

skills: gitea, issue-writing

Bad: Reserved word in name

name: claude-helper  # Contains "claude"

Good: Descriptive name

name: code-helper

Bad: Vague description

description: Helps with stuff

Good: Specific description

description: >
  Analyze Excel spreadsheets, create pivot tables, generate charts.
  Use when analyzing Excel files, spreadsheets, or .xlsx files.