Skills are reusable, self-contained instruction files you can attach to your agents. Each skill is a single Markdown file with a YAML frontmatter block that defines its metadata.
Limits
- Maximum 10 skills per account
- Maximum 10 KB per skill file
A skill is a SKILL.md file. It must start with a YAML frontmatter block followed by the skill content in Markdown.
---
name: my-skill-name
description: A short description of what this skill does.
allowed-tools:
- web-search
license: MIT
compatibility: Works best with Claude 3+
metadata:
author: Jane Doe
version: "1.0"
---
## Skill Instructions
Write your skill instructions here in plain Markdown...
Frontmatter fields
Required
| Field | Type | Description |
|---|
name | string | Unique skill identifier. See name rules. |
description | string | What the skill does. Max 1024 characters. |
Optional
| Field | Type | Description |
|---|
allowed-tools | list of strings | Tools this skill is permitted to use. |
license | string | License identifier (e.g. MIT). |
compatibility | string | Notes on model or platform compatibility. Max 500 characters. |
metadata | dictionary | Arbitrary key-value metadata (e.g. author, version). |
No other fields are allowed. Any unexpected frontmatter fields will cause a validation error.
Name rules
The name field has strict formatting requirements:
- Lowercase only — no uppercase letters allowed
- Allowed characters — letters (
a-z), digits (0-9), and hyphens (-)
- No leading or trailing hyphens —
-my-skill and my-skill- are invalid
- No consecutive hyphens —
my--skill is invalid
- Maximum 64 characters
summarizer
web-researcher
code-review2
sql-helper
Structure requirements
The SKILL.md file must:
- Start with
--- to open the YAML frontmatter
- Close the frontmatter with a second
---
- Contain valid YAML inside the frontmatter block
- Have the frontmatter parse as a YAML mapping (not a list or scalar)
Minimal valid example
---
name: summarizer
description: Summarizes long text into bullet points.
---
When asked to summarize, extract the key points and present them as a concise bulleted list.
Common validation errors
| Error | Fix |
|---|
Missing required field: name | Add a name field to the frontmatter |
Missing required field: description | Add a description field to the frontmatter |
Skill name must be lowercase | Use all lowercase in the name |
Skill name contains invalid characters | Use only letters, digits, and hyphens |
Skill name cannot start or end with a hyphen | Remove leading or trailing hyphens |
Skill name cannot contain consecutive hyphens | Replace -- with - |
Unexpected fields in frontmatter | Remove fields not in the allowed list |
SKILL.md must start with YAML frontmatter | Ensure the file starts with --- |
Description exceeds 1024 character limit | Shorten the description |
allowed-tools must be a list | Use YAML list syntax for allowed-tools |
File too large | Keep the skill file under 10 KB |
Limit reached | You can have at most 10 skills per account |
