> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/anthropics/skills/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
```yaml theme={null}
---
name: skill-name
description: What the skill does and when to use it
compatibility: [optional]
license: [optional]
---
```
## Required Fields
### name
Unique identifier for the skill.
**Format:**
* Lowercase letters, numbers, and hyphens only
* No spaces or special characters
* Should be descriptive and memorable
**Examples:**
```yaml theme={null}
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
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:**
```yaml theme={null}
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:**
```yaml theme={null}
description: How to build a dashboard to display data.
```
**Better:**
```yaml theme={null}
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:**
```yaml theme={null}
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:**
```yaml theme={null}
description: Format git commit messages following conventional commits specification. Use when creating commits, formatting commit messages, or standardizing repository commit history.
```
## Optional Fields
### compatibility
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:
```yaml theme={null}
compatibility: Requires WebFetch tool for loading API documentation
```
Multiple requirements:
```yaml theme={null}
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 information for the skill.
**Formats:**
Direct license name:
```yaml theme={null}
license: Apache 2.0
```
Reference to license file:
```yaml theme={null}
license: Complete terms in LICENSE.txt
```
Custom license:
```yaml theme={null}
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
```yaml theme={null}
---
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](/creating-skills/overview) for details on description optimization.
### Description Anti-Patterns
**Problem:**
```yaml theme={null}
description: Helps with documents
```
**Better:**
```yaml theme={null}
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.
```
**Problem:**
```yaml theme={null}
description: A skill for building MCP servers
```
**Better:**
```yaml theme={null}
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"
**Problem:**
```yaml theme={null}
description: Can help format commit messages
```
**Better:**
```yaml theme={null}
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.
```
**Problem:**
```yaml theme={null}
description: Creates internal communication documents following company guidelines
```
**Better:**
```yaml theme={null}
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
```bash theme={null}
# 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:**
```yaml theme={null}
# 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
Learn about the full SKILL.md structure
Understand how skills are loaded progressively
Build your first skill with best practices