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.

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

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

Bad: Too vague

---
name: dashboard-builder
description: How to build a simple fast dashboard.
---

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

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

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

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

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

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

1. Generate Test Queries

   Create 20 evaluation queries - mix of should-trigger and should-not-trigger cases

2. Review with User

   Present queries in an HTML interface for editing and validation

3. Run Optimization Loop

   Automatically test descriptions and improve based on results

4. Apply Best Result

   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:

YAML Syntax

• 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

Required Fields Present

• name must be present and non-empty
• description must be present and comprehensive
• Both should appear exactly once

Name Format

• 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

Skill Structure

Learn how to organize your skill files

Best Practices

Guidelines for writing effective descriptions