How to write a SKILL.md: the six spec fields and an example

What a skill is made of

A skill is a folder whose name matches the name field. Inside:

my-skill/
  SKILL.md          instructions with frontmatter
  scripts/          code the agent runs
  references/       docs the agent reads when needed
  assets/           templates, images, data

The standard lives at agentskills.io. Anthropic developed it originally; today Claude Code, claude.ai and the Claude API, Codex, Cursor, GitHub Copilot, Gemini CLI, Kiro, OpenCode, Zed and Windsurf (documented now as Devin Desktop) all read it. The spec repo agentskills/agentskills had 26,552 stars on 24 October 2026, under Apache-2.0.

The six fields of the spec

claude.ai and the Claude API are stricter: the name cannot contain anthropic, claude or XML tags, and any field beyond these six is a hard upload error. Copilot silently skips a skill with an invalid name. Validate before publishing with the spec tool: skills-ref validate ./my-skill.

Can you show an example of a SKILL.md file?

An illustrative sketch, not a real skill from our catalog:

---
name: release-notes
description: Writes release notes from git log between two tags. Use when asked for a changelog, release notes or a list of changes in a version.
license: MIT
metadata:
  author: your-team
  version: "1.0"
---

# Release notes

1. Find the two latest tags: git tag --sort=-creatordate | head -2
2. Collect commits between them: git log --oneline A..B
3. Group into Added / Changed / Fixed. Template in references/template.md.
4. Do not invent items that are not in the log.

Look at the description. The first sentence says what the skill does; the second lists the words that tell the agent it is time to use it. The agent decides on this field alone, because it has not seen the body yet.

Progressive disclosure: why size matters

Skills load in three steps. At startup only the name and description of every skill enter context, about 100 tokens each. When a skill activates, the SKILL.md body is read. Files in references/ and scripts/ are opened only if the body points to them.

Hence the spec limits: keep the body under 5,000 tokens and 500 lines, and keep file references one level deep. A 2,000-line reference belongs in references/, linked from SKILL.md.

The list has a budget too. In Claude Code all skill listings share up to 1 % of the context window, and description plus when_to_use is cut at 1,536 characters. Codex gives the list 2 % of the window or 8,000 characters. When space is short, descriptions get trimmed, so put the important words first.

Platform extensions and staying portable

Each platform added its own fields:

• Claude Code: when_to_use, argument-hint, disable-model-invocation, user-invocable, model, effort, context: fork, paths, hooks and more. It accepts license, compatibility and metadata but does not use them.
• Codex: a separate agents/openai.yaml for UI metadata and implicit invocation policy.
• Cursor: disable-model-invocation, icon, color, legacy paths.
• Copilot: argument-hint, user-invocable, disable-model-invocation, experimental context: fork.

Our take: for a public skill, keep only the six standard fields. It will then load everywhere, strict claude.ai included. Platform fields make sense in a private skill for one agent.

Checklist before you publish

• Folder name and name match, with no capital letters.
• The description answers two questions: what it does and when to use it.
• Scripts do not call the network without reason or read files outside the project. GitHub warns that nobody verifies third-party skills.
• There is a LICENSE file. Without one, nobody can legally copy your skill, and catalogs like ours will show it as a link only.

Installing ready-made skills is covered for Claude Code, Codex and Cursor. For examples to study, browse the skills catalog.