Skip to main content

​
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: 
---
name: dashboard-builder
description: How to build a simple fast 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:
  • 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 contextsToo Generic: description: A helper for various tasks - Claude won’t know when to use itMissing “When”: description: Builds MCP servers - Says what but not whenWrong 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

Build docs developers (and LLMs) love

Get started for freeTalk to us