🧾Advanced
YAML Frontmatter
The only thing Claude reads at selection time. Name, description, and trigger phrases decide everything.
Why the Frontmatter Matters Most
Claude decides whether to load your skill based entirely on the YAML frontmatter. The body content never influences selection. Get the name and description right and the rest of the work pays off; get them wrong and nothing else matters.
Minimal Required Fields
yaml
---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---Full Field Reference
yaml
---
name: skill-name-in-kebab-case
description: What it does and when to use it. Include specific trigger phrases.
license: MIT # optional, for open-source skills
allowed-tools: "Bash(python:*) WebFetch" # optional, restrict tool access
compatibility: "Claude.ai + Code Execution Tool beta" # optional
metadata: # optional, custom fields
author: Company Name
version: 1.0.0
mcp-server: server-name
---| Field | Required | Rules |
|---|---|---|
| name | Yes | kebab-case only, no spaces or capitals, must match folder name |
| description | Yes | Under 1024 chars, WHAT + WHEN + trigger phrases, no XML angle brackets |
| license | No | MIT, Apache-2.0, etc. Use if open-source |
| allowed-tools | No | Whitespace-separated tool spec. Restricts what the skill may call |
| compatibility | No | 1–500 chars. Declare environment requirements |
| metadata | No | Free-form key/value. author, version, mcp-server, tags, support |
Writing the Description: Good Examples
The description is the only text Claude sees at selection time. It must answer three questions: what does this do, when should I pick it, and which phrases in the user's message are the trigger.
yaml
# Good — specific and actionable
description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".
# Good — includes trigger phrases
description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets".
# Good — clear value proposition
description: End-to-end customer onboarding workflow for PayFlow. Handles account creation, payment setup, and subscription management. Use when user says "onboard new customer", "set up subscription", or "create PayFlow account".Writing the Description: Bad Examples
yaml
# Bad — too vague, no triggers, nothing for Claude to match
description: Helps with projects.
# Bad — missing triggers
description: Creates sophisticated multi-page documentation systems.
# Bad — too technical, no user-facing language
description: Implements the Project entity model with hierarchical relationships.Security Restrictions
- ▸XML angle brackets (< >) are forbidden in frontmatter. Frontmatter appears in Claude's system prompt, so angle brackets could inject instructions.
- ▸Names starting with "claude" or "anthropic" are reserved and will be rejected.
- ▸YAML is parsed with safe YAML — no code execution is possible from the frontmatter itself.
- ▸Standard YAML types are allowed (strings, numbers, booleans, lists, objects). Custom metadata fields are allowed.
⚠️Warning
If Claude ignores your skill for what look like the right queries, re-read the description aloud. It should sound like something a user would say back to you in plain language.