Frontmatter Reference

Frontmatter Reference

Every SKILL.md file begins with YAML frontmatter between --- delimiters. This page is the complete field reference. For the full skill standard including body structure, progressive disclosure, and grading, see the SKILL.md Specification.

---

Required Fields

Only two fields are strictly required by the AgentSkills.io open standard:

name

• Type: string
• Constraints: 1-64 characters, kebab-case (^[a-z][a-z0-9-]*[a-z0-9]$), no consecutive hyphens
• Must match the skill's directory name
• Naming convention: Gerund preferred -- processing-invoices, analyzing-logs

description

• Type: string
• Constraints: 1-1024 characters (under 200 recommended for token efficiency)
• Voice: Third person always -- "Generates reports..." not "I generate..." or "You can generate..."
• Must include:
  • What the skill does
  • When to use it (Use when...)
  • Trigger phrases (Trigger with '...')

The description is the most important field. It loads into the system prompt at startup and determines whether and when the skill activates.

---

Identity Fields (Marketplace Scored)

These fields are optional per the open standard but scored by the marketplace 100-point validator. Place them at the top level of the frontmatter -- do NOT nest under metadata:.

allowed-tools

• Type: CSV string (not a YAML array)
• Purpose: Declares the security boundary -- which tools the skill may use
• Always scope Bash: Use Bash(git:*), Bash(npm:*) instead of bare Bash
• See Tool Permissions Guide for the full list and best practices

version

• Type: string
• Format: Semver -- 1.0.0, 2.3.1

author

• Type: string
• Format: Name <email> -- e.g., Jeremy Longshore <jeremy@intentsolutions.io>

license

• Type: string
• Format: SPDX identifier -- MIT, Apache-2.0

compatible-with

• Type: string (comma-separated)
• Valid platforms: claude-code, codex, openclaw, cursor, aider, continue, windsurf
• Example: compatible-with: claude-code, codex, openclaw

tags

• Type: YAML array
• Purpose: Discovery tags for marketplace search
• Example: tags: [devops, ci, deployment]

---

Claude Code Extension Fields

Platform-specific fields not in the AgentSkills.io open standard:

model

• Type: string
• Valid values: inherit, sonnet, opus, haiku
• Purpose: Override the LLM model used when the skill activates
• Warning: Never use full model IDs (e.g., claude-sonnet-4-20250514) -- they break on deprecation

context

• Type: string
• Valid values: fork
• Purpose: Run the skill in a forked subagent context, isolating it from the main conversation

agent

• Type: string
• Valid values: Explore, Plan, general-purpose
• Purpose: Specifies the subagent type (requires context: fork)

user-invocable

• Type: boolean
• Default: true
• Purpose: Set to false to hide the skill from the / slash command menu. The skill becomes background knowledge only.

argument-hint

• Type: string
• Purpose: Autocomplete hint shown after /skill-name in the menu
• Example: argument-hint: "<file-path>"

disable-model-invocation

• Type: boolean
• Purpose: When true, the skill only activates via explicit /skill-name invocation, never automatically

hooks

• Type: object
• Purpose: Skill-scoped lifecycle hooks
• Example: hooks: { PreToolUse: ... }

compatibility

• Type: string
• Purpose: Environment requirements (used by AgentSkills.io for filtering)
• Example: compatibility: "Node.js >= 18"

---

Path Variable

Use ${CLAUDE_SKILL_DIR} to reference files within the skill directory. This resolves to the skill's absolute path at runtime and keeps skills portable across installations.

See [implementation details](${CLAUDE_SKILL_DIR}/references/implementation.md) for advanced patterns.

Never use absolute paths or the legacy {baseDir} alias (it still works but ${CLAUDE_SKILL_DIR} is the standard).

---

Recommended Field Order

---
# Required (AgentSkills.io)
name: skill-name
description: |
  What it does. Use when [scenario].
  Trigger with "/skill-name" or "[natural phrase]".

# Tools (recommended)
allowed-tools: "Read, Write, Glob, Grep"

# Identity (top-level -- marketplace validator scores these here)
version: 1.0.0
author: Name <email>
license: MIT

# Claude Code extensions (as needed)
model: inherit
argument-hint: "[arg]"
context: fork
agent: general-purpose

# Discovery (optional)
compatible-with: claude-code, codex, openclaw
tags: [devops, automation]
---

---

Common Pitfalls

Mistake	Consequence	Fix
disable-model-invocation: true + user-invocable: false	Skill is unreachable	Use one or the other, not both
Bare Bash in allowed-tools	Security risk	Scope it: Bash(git:*), Bash(npm:*)
Hardcoded model IDs	Breaks on deprecation	Use inherit, sonnet, opus, haiku
allowed-tools as YAML array	Parse error	Must be a CSV string
Fields nested under metadata:	Marketplace validator misses them	Keep version, author, license, tags at top level

---

Related Pages

• Tool Permissions Guide -- Detailed guide to allowed-tools
• SKILL.md Specification -- Full standard including body structure and grading
• Skill Template -- Copy-paste starter template
• Validation and Grading -- How frontmatter is validated and scored