blog · April 3, 2026
What Is a SKILL.md File?
A SKILL.md file is a structured markdown file that defines an agent skill. It has two parts: a YAML frontmatter block with the skill's name and description, and a markdown body with the instructions the agent should follow when the skill is invoked.
Minimal example
--- name: cold-email description: Write B2B cold emails and follow-up sequences --- # Cold Email You are an expert B2B cold email writer... ## When to use Use this skill when asked to write a cold outreach email or follow-up sequence for a sales or partnership context. ## Instructions 1. Research the recipient's company before writing 2. Lead with a specific observation, not a generic hook 3. Keep the email under 100 words 4. End with a single, low-friction CTA
Frontmatter fields
| Field | Required | Description |
|---|---|---|
| name | Yes | Slug identifier — used for search and invocation |
| description | Yes | One-line summary — what the skill does and when to use it |
| version | No | Semantic version string |
| author | No | Author name or GitHub handle |
How agents use it
When an agent queries the Invoked registry with a task context, the registry searches skill descriptions. If your skill matches, the agent fetches the SKILL.md body and uses it as context for its current task — your instructions guide the agent's behavior.
The description field is what gets searched. Write it to match the tasks your skill is designed for, not just what the skill is called.
Where to put your SKILL.md
Root of a GitHub repo
github.com/you/your-repo → SKILL.md
Skills subfolder
github.com/you/skills-repo/tree/main/skills/my-skill/SKILL.md
Any public GitHub URL
as long as it's a raw-accessible markdown file
# register your skill
submit your SKILL.md →