Metadata Schema Reference

Complete schema reference for SKILL.md YAML frontmatter fields, including required and optional metadata for skill discovery and triggering.

The YAML frontmatter in SKILL.md contains metadata that controls skill discovery and triggering. This page documents the complete schema.

Schema Overview

The frontmatter uses YAML syntax and must be enclosed in --- delimiters at the top of the SKILL.md file:

---
name: skill-name
description: What the skill does and when to use it
compatibility: [optional]
license: [optional]
---

Required Fields

name

name · string · required

Unique identifier for the skill.

Format:

• Lowercase letters, numbers, and hyphens only
• No spaces or special characters
• Should be descriptive and memorable

Examples:

name: mcp-builder
name: commit-message-formatter
name: internal-comms
name: skill-creator

Usage:

• Used as the skill’s identifier in skill loading systems
• Appears in skill lists and management interfaces
• Should match the skill folder name by convention

description

description · string · required

Complete description of what the skill does and when to use it.

Purpose:

• Primary triggering mechanism - AI agents use this to decide when to invoke the skill
• All “when to use” information should be in the description, not the body
• Should be comprehensive but concise (~50-200 words)

Best Practices:

1. Include both capabilities and contexts:

   description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
   

2. Be “pushy” to combat under-triggering:

   Agents tend to under-use skills, so make the description explicitly mention when to use it:

   Less effective:

   description: How to build a dashboard to display data.
   

   Better:

   description: How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'
   

3. List specific trigger keywords and scenarios:

   description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
   

4. Mention file types, frameworks, or domains:

   description: Format git commit messages following conventional commits specification. Use when creating commits, formatting commit messages, or standardizing repository commit history.
   

Optional Fields

compatibility

compatibility · string | array

Required tools, dependencies, or platform requirements.

When to use:

• Skill requires specific tools (e.g., WebFetch, specific CLI tools)
• Skill has platform dependencies (e.g., only works on Linux)
• Skill needs external services or credentials

Examples:

Single requirement:

compatibility: Requires WebFetch tool for loading API documentation

Multiple requirements:

compatibility:
  - Requires Docker for container operations
  - Requires AWS credentials in environment
  - Linux or macOS only

The compatibility field is rarely needed. Most skills work across platforms and don’t have special requirements.

license

license · string

License information for the skill.

Formats:

Direct license name:

license: Apache 2.0

Reference to license file:

license: Complete terms in LICENSE.txt

Custom license:

license: Proprietary - Internal use only

Common Licenses:

• Apache 2.0 - Open source, permissive
• MIT - Open source, very permissive
• Source available - Code visible but restricted use
• Proprietary - Closed source

Complete Schema Example

---
name: mcp-builder
description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
compatibility: Requires WebFetch tool for loading external documentation
license: Complete terms in LICENSE.txt
---

Description Optimization

Since the description field is the primary triggering mechanism, optimizing it is crucial for skill effectiveness.

How Triggering Works

Skills appear in the agent’s available_skills list with their name and description. The agent decides whether to use a skill based on:

1. Match between user request and description - Keywords, concepts, contexts
2. Task complexity - Simple one-step tasks may not trigger skills even if description matches
3. Agent capability - Agent only triggers skills for tasks where the skill provides value

Simple queries like “read this PDF” may not trigger a PDF skill even if the description matches perfectly, because the agent can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches.

Testing Trigger Accuracy

The skill-creator skill includes a description optimization system that:

1. Generates 20 test queries (mix of should-trigger and should-not-trigger)
2. Evaluates current description’s trigger accuracy
3. Uses extended thinking to propose improvements
4. Iteratively refines the description
5. Reports final accuracy on held-out test set

See the Creating Skills guide for details on description optimization.

Description Anti-Patterns

Too Vague

Problem:

description: Helps with documents

Better:

description: Create and edit Microsoft Word documents (.docx) with precise formatting, styles, headers, footers, tables, and images. Use when users want to create professional documents, generate reports, format existing documents, or work with Word files.

Missing Trigger Keywords

Problem:

description: A skill for building MCP servers

Better:

description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

Notice the addition of: “MCP”, “Model Context Protocol”, “external services”, “APIs”, “Python”, “FastMCP”, “Node”, “TypeScript”, “MCP SDK”

Not Pushy Enough

Problem:

description: Can help format commit messages

Better:

description: Format git commit messages following conventional commits specification. Use when creating commits, formatting commit messages, standardizing repository commit history, or any time the user is working with git commits.

Only What, No When

Problem:

description: Creates internal communication documents following company guidelines

Better:

description: Creates internal communication documents following company guidelines including newsletters, FAQ answers, general announcements, and third-party updates. Use when drafting company communications, employee announcements, internal newsletters, FAQ responses, or any internal-facing written communication.

Validation

While there’s no formal schema validator, you can check your frontmatter:

Required Fields Check

# Both name and description must be present
grep -E "^name:" SKILL.md
grep -E "^description:" SKILL.md

Format Check

• Frontmatter must start with --- on line 1
• Frontmatter must end with --- before the markdown body
• Each field must be on its own line
• Field names must be lowercase
• Values should be properly quoted if they contain special characters

Common Mistakes

Frontmatter not at the start: The YAML frontmatter must be the very first thing in the file. No blank lines or comments before the opening ---.

Invalid YAML syntax:

# Wrong - colon in description breaks parsing
description: Use this when: you need to format commits

# Right - quote strings with special characters  
description: "Use this when: you need to format commits"

Missing required fields: Both name and description are required. Skills without these fields may fail to load.

Next Steps

SKILL.md Format

Learn about the full SKILL.md structure

Loading System

Understand how skills are loaded progressively

Creating Skills

Build your first skill with best practices