> ## 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.
# YAML Frontmatter
> Understanding frontmatter fields: name, description, license, compatibility, and how they control skill behavior
# YAML Frontmatter
The YAML frontmatter at the top of SKILL.md contains metadata that controls how Claude discovers, loads, and uses your skill.
## Required Fields
Every skill must include these two fields:
### name
A unique identifier for your skill using lowercase letters and hyphens.
```yaml theme={null}
---
name: my-skill-name
---
```
**Guidelines:**
* Use lowercase only
* Separate words with hyphens (kebab-case)
* Keep it concise but descriptive
* Avoid generic names that might conflict with other skills
**Examples:**
* `skill-creator` - Creates and improves skills
* `mcp-builder` - Builds MCP servers
* `brand-guidelines` - Applies brand styling
* `webapp-testing` - Tests web applications
### description
A comprehensive description of what the skill does **and when to use it**. This is the primary triggering mechanism.
```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).
---
```
The description field is critical! Claude uses it to decide whether to invoke your skill. A poorly written description means your skill won't trigger when needed.
**Best Practices:**
* Include both **what** the skill does and **when** to use it
* List specific keywords and contexts that should trigger the skill
* Be slightly "pushy" - skills tend to under-trigger rather than over-trigger
* Mention alternative phrasings users might use
* Keep it under 100 words but be comprehensive
**Good vs. Bad Descriptions:**
```yaml Bad: Too vague theme={null}
---
name: dashboard-builder
description: How to build a simple fast dashboard.
---
```
```yaml Good: Specific and comprehensive theme={null}
---
name: dashboard-builder
description: How to build a simple fast dashboard to display internal Anthropic data. 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.'
---
```
## Optional Fields
### license
Specify the license or reference a LICENSE.txt file:
```yaml theme={null}
---
name: skill-creator
description: Create new skills, modify and improve existing skills...
license: Complete terms in LICENSE.txt
---
```
Common patterns:
* `license: Complete terms in LICENSE.txt` - Reference external file
* `license: Apache 2.0` - Open source
* `license: Proprietary. LICENSE.txt has complete terms` - Closed source with details
Many skills in Anthropic's repository use Apache 2.0 license. Document creation skills (docx, pdf, pptx, xlsx) are source-available but proprietary.
### compatibility
List required tools, dependencies, or environment requirements (rarely needed):
```yaml theme={null}
---
name: advanced-skill
description: Does advanced things...
compatibility: Requires Python 3.8+, pandoc, and LibreOffice
---
```
Most skills don't need this field. Include it only when:
* Specific software versions are required
* The skill depends on external tools not commonly available
* Certain platforms or environments are needed
## Complete Frontmatter Examples
### Minimal Skill
```yaml theme={null}
---
name: template-skill
description: Replace with description of the skill and when Claude should use it.
---
```
This is the absolute minimum from the template skill.
### Production Skill
```yaml theme={null}
---
name: skill-creator
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.
license: Complete terms in LICENSE.txt
---
```
From the skill-creator skill - comprehensive description with multiple trigger contexts.
### Document Skill
```yaml theme={null}
---
name: docx
description: "Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation."
license: Proprietary. LICENSE.txt has complete terms
---
```
From the docx skill - extremely detailed description with both positive triggers ("use when...") and negative triggers ("Do NOT use for...").
## Description Optimization
After creating a skill, you can optimize the description for better triggering accuracy using the skill-creator skill:
Create 20 evaluation queries - mix of should-trigger and should-not-trigger cases
Present queries in an HTML interface for editing and validation
Automatically test descriptions and improve based on results
Update SKILL.md with the optimized description
This process splits queries into train/test sets and uses extended thinking to propose improvements based on what failed, avoiding overfitting.
## How Skill Triggering Works
Understanding the triggering mechanism helps you write better descriptions:
1. **Skills appear in available\_skills list** with their name + description
2. **Claude decides whether to consult a skill** based on the description
3. **Simple tasks may not trigger skills** even with perfect descriptions - Claude handles them directly
4. **Complex, multi-step, specialized tasks reliably trigger skills** when the description matches
Write descriptions for substantial tasks, not simple one-step operations. "Read this PDF" won't trigger a PDF skill (Claude can do it directly), but "Extract all form fields from this PDF and create a filled version with the data from this CSV" will.
## Frontmatter Validation
When creating a skill, validate your frontmatter:
* Use `---` to open and close the frontmatter block
* Colon separates keys from values: `name: value`
* Quote values containing special characters: `description: "Use when: ..."`
* No tabs - use spaces for indentation
* `name` must be present and non-empty
* `description` must be present and comprehensive
* Both should appear exactly once
* Lowercase letters, numbers, and hyphens only
* No spaces or special characters
* Examples: `skill-creator`, `mcp-builder`, `brand-guidelines`
## Common Mistakes
**Too Brief**: `description: Creates skills` - Missing trigger contexts
**Too Generic**: `description: A helper for various tasks` - Claude won't know when to use it
**Missing "When"**: `description: Builds MCP servers` - Says what but not when
**Wrong Name Format**: `name: Skill Creator` - Use `skill-creator` instead
## Next Steps
Learn how to organize your skill files
Guidelines for writing effective descriptions