Skills

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

File format

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

My Skill        ← uppercase and space
--debug         ← leading hyphens
sql_helper      ← underscore not allowed
UPPERCASE       ← not lowercase
my--skill       ← consecutive hyphens

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

Skills work best when they are attached to a focused agent or a repeatable workflow, then paired with the right integrations.

Get started

Core concepts

Automate

Claw

Examples

Tutorials

More

Limits

File format

Frontmatter fields

Required

Optional

Name rules

Structure requirements

Minimal valid example

Common validation errors

​Limits

​File format

​Frontmatter fields

​Required

​Optional

​Name rules

​Structure requirements

​Minimal valid example

​Common validation errors

Limits

File format

Frontmatter fields

Required

Optional

Name rules

Structure requirements

Minimal valid example

Common validation errors