SKILL.md Format: Rules, Examples and 1,792 Skills Checked

On this page
  1. A SKILL.md, line by line
  2. The six fields, and what we found in each
  3. Three readers, three rulebooks
  4. What 1,792 public skills get wrong
  5. The description decides whether the skill is used
  6. How long should a SKILL.md be?
  7. Where each agent looks for skills
  8. A template to copy
  9. Skills for a team, not one laptop
  10. Sources

Your teammate wrote a deploy skill. It works in Claude Code every day. You upload the same folder to claude.ai so the rest of the team can use it, and get this:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Nothing is wrong with the skill. It was written for one reader and sent to another. A SKILL.md file has at least three readers today, and they do not share one rulebook. We ran 1,792 public skills from GitHub through all three to see how often that bites.

Short answer: a SKILL.md is a Markdown file in a folder named after the skill. It starts with YAML frontmatter between --- lines. Two fields are required: name (lowercase letters, digits and hyphens, up to 64 characters, the same as the folder) and description (up to 1,024 characters: what the skill does and when to use it). Four are optional: license, compatibility, metadata and allowed-tools. The instructions follow, ideally under 500 lines. On 18 November 2026 we checked 1,792 public skills: of the 1,601 with frontmatter, 38.2% would be refused by a claude.ai upload, 18.3% break the open spec, and 36.6% never say when to use the skill.

A SKILL.md, line by line

Here is a complete skill. Every line below is there for a reason a reader of the file will check.

---
name: changelog-entries
description: Writes CHANGELOG.md entries in Keep a Changelog format. Use when the
  user finishes a change, asks for release notes, or mentions the changelog, a
  release or a version bump.
license: MIT
metadata:
  author: platform-team
  version: "1.2"
---

# Changelog entries

1. Read CHANGELOG.md and package.json.
2. Add the change under `## [Unreleased]`: Added, Changed, Fixed or Removed.
3. One line per change, past tense, with the issue key if there is one.

## Example

Input: "Fixed the off-by-one in dueDate (PAY-31)"
Output, under ### Fixed: "- Due dates no longer land one day early (PAY-31)."

For the full style rules, see [references/style.md](references/style.md).
  • Line 1 is ---. Claude Code reads the frontmatter “only when the opening --- is the file’s first line”. A blank line or a title above it turns the whole file into instructions with no name.
  • name matches the folder (changelog-entries/SKILL.md). The spec requires it.
  • The description has two halves. What it does, then “Use when” with the words a user would type. The agent sees only this line until it decides to load the skill.
  • The version sits under metadata, quoted. A top-level version: is the most common reason a public skill fails a claude.ai upload (14.5% of our sample).
  • The body is short. Steps, one example, a link one level deep for the rest.

The six fields, and what we found in each

The Agent Skills specification defines six frontmatter fields. The right column is what we saw in 1,601 public skills with frontmatter.

FieldRule in the specIn public skills
namerequired, 1-64 characters, a-z, 0-9 and -, no - at either end, no --, = folder6.9% differ from their folder; 4.2% use capitals, spaces or _
descriptionrequired, 1 to 1,024 characters, “what the skill does and when to use it”median 201 characters; 36.6% say what but not when
licenseoptional, a licence name or a bundled file209 skills set it
compatibilityoptional, up to 500 characters, only if the skill needs a product or a tool44 skills set it
metadataoptional, “a map from string keys to string values”5.7% nest maps or lists in it, which the spec does not allow
allowed-toolsoptional, experimental, a space-separated string1.7% write it as a YAML list (Claude Code takes it, the spec not)

Everything else in the frontmatter is outside the spec. Other agents ignore it; a claude.ai upload refuses it. The extra fields we saw most: version (234 skills), author (111), tags (104), source (95), category (62).

Three readers, three rulebooks

The same folder is read by three kinds of software, and each checks different things.

  1. The open spec. What Codex, GitHub Copilot, Cursor, Gemini CLI and the other agents that adopted Agent Skills follow. Unknown fields are ignored, the name must match the folder.
  2. A claude.ai upload, the Skills API and package_skill.py. Claude Code’s docs are blunt: “If you include any field the spec doesn’t allow, packaging or upload fails with a hard error instead of ignoring the field.” Anthropic’s overview adds two rules for the name: no XML tags and no reserved words, “anthropic” or “claude”. The folder name is not checked.
  3. Claude Code. It accepts every spec field plus fourteen of its own: when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, disallowed-tools, model, effort, context, agent, background, hooks, paths and shell. It is also the most forgiving: a missing name defaults to the folder, a missing description to “the first non-empty line of the markdown content”, and YAML that does not parse still loads “with no fields set”.

That last point hides problems. A skill can work for months in Claude Code and fail the first time someone shares it. In our sample, 129 skills (8.1%) used Claude Code-only fields. Most were written for Claude Code on purpose; the trouble starts when they are shared as if they were portable.

RuleSpecclaude.ai uploadClaude Code
--- on line 1requiredrequiredelse no frontmatter
name formatrequiredrequiredoptional (folder name)
name = folderrequirednot checkednot checked
No “anthropic” or “claude” in namenot checkedrequirednot checked
descriptionrequiredrequiredrecommended
Fields beyond the sixignoredrefused14 more accepted
Under 500 lines, 5,000 tokensrecommendedrecommendedrecommended

What 1,792 public skills get wrong

Horizontal bar chart of 1,601 public SKILL.md files with frontmatter from 1,553 GitHub repositories, checked on 18 November 2026. Refused by a claude.ai upload or the Skills API: 611 files, 38.2 percent. Description says what the skill does but not when to use it: 586, 36.6 percent. Fields outside the Agent Skills spec such as version or author: 492, 30.7 percent. Breaks the Agent Skills spec: 293, 18.3 percent; of those, name not equal to the folder 6.9 percent, metadata not a map of text 5.7 percent, capitals, spaces or underscores in the name 4.2 percent. Instructions over 5,000 tokens: 143, 8.9 percent. Passes all three targets: 932, 58.2 percent. 191 more files named SKILL.md had no frontmatter. Source: Simplify study with the SKILL.md validator.

How we sampled. GitHub’s code search finds millions of files named SKILL.md (its own estimate, copies included, was about 7.5 million on 18 November 2026). We took the first 200 results in each of ten file-size bands, from under 500 bytes to over 20 KB, downloaded each from its default branch, and dropped exact copies: 1,792 skills from 1,553 repositories. Search results are ranked, not random, so read the numbers as a large sample, not a census. Each file went through the same SKILL.md validator you can use for free.

The six mistakes that came up most, with the fix:

  1. A field outside the six (30.7%). version: 1.0.0 and author: someone at the top level. Move them under metadata as text: version: "1.0.0".
  2. A description with no “when” (36.6%). “Generates API docs” tells the agent what, not when. Add “Use when the user asks for API docs or changes a route”, with the words people actually type.
  3. No frontmatter on line 1 (191 more files). Some are notes that only share the name; others start with a title or a blank line. Move --- to line 1.
  4. The name is not the folder (6.9%). name: pdf-tools in skills/pdf/. Rename one of them.
  5. Metadata that nests (5.7%). metadata: { openclaw: { requires: ... } }. The spec wants a flat map of text; keep tool-specific settings in a file the skill reads.
  6. Too long (8.9% over 5,000 tokens). The whole body loads every time. Keep the steps in SKILL.md and move tables, API references and long examples into references/.

Rarer, but each one a hard failure somewhere: 14 skills had “claude” or “anthropic” in the name, 14 had XML tags in the description, 27 wrote allowed-tools as a list.

What we did not find: a real API key. 34 skills tripped generic password rules, every one a placeholder in a code sample (password: changeme); two tripped vendor rules, both fake examples. We changed the validator to flag only vendor formats after reading all 36.

The description decides whether the skill is used

The spec says the name and description “are loaded at startup for all skills”, about 100 tokens each. The body is read only after the agent picks the skill. Anthropic’s authoring guide puts it plainly: Claude uses the description “to choose the right Skill from potentially 100+ available Skills”, and it should be written in the third person.

We tested this in Claude Code with one skill and three descriptions: a vague one (“Helps with changelogs”), one that said what it does, and one that said what and when. Five requests should use the skill and three should not, each run three times: 72 runs. The “what and when” description was picked on 15 of 15 runs that needed it; the other two on 9 of 15 each, missing “bump the version” and “wrap it up so it is ready to ship” most often. None fired on the 27 runs that had nothing to do with changelogs. The prompts, the misses and the cost are in Claude Code skills, tested.

How long should a SKILL.md be?

The spec’s numbers: under 500 lines for SKILL.md and under about 5,000 tokens for the instructions, with detail in files the agent opens “only when required”. Public skills are mostly well inside that: the median was 73 lines, the 90th percentile 392. The long tail is where problems are: 107 skills over 500 lines, some over 2,000, often a whole API reference pasted in.

A practical split:

  • SKILL.md: when to use it, the steps, one example, what not to do. One screen if you can.
  • references/: API tables, style guides, long examples. Linked by relative path, one level deep.
  • scripts/: code the agent runs instead of writing it each time, with clear error messages.
  • assets/: templates and schemas the skill fills in.

Where each agent looks for skills

From each vendor’s own docs, read on 18 November 2026:

AgentIn the repositoryFor one person
Claude Code.claude/skills/<name>/SKILL.md~/.claude/skills/
OpenAI Codex.agents/skills/, from the working folder up~/.agents/skills/
GitHub Copilot.github/skills/, .claude/skills/, .agents/skills/~/.copilot/skills/, ~/.agents/skills/
Cursor.cursor/skills/, .agents/skills/; also .claude/skills/, .codex/skills/~/.cursor/skills/, ~/.agents/skills/

No folder is read by all four. .claude/skills reaches Claude Code, Copilot and Cursor; .agents/skills reaches Codex, Copilot and Cursor. In our sample, most skills sat at a repository’s root (45.8%) or in a skills/ folder of a skills collection (25.2%): published to be copied, not used in place.

A template to copy

---
name: your-skill-name
description: Does X for Y. Use when the user asks to ..., mentions ..., or works on
  files like ... Do not use for ...
metadata:
  owner: your-team
  version: "1.0"
---

# Your skill name

## When to use
One or two sentences, the same triggers as the description.

## Steps
1. ...
2. ...
3. Check the result: the command or test that proves it worked.

## Example
Input: ...
Output: ...

## Do not
- ...

Details: [references/details.md](references/details.md)

Check it before you commit it: paste it into the SKILL.md validator. It runs in your browser and says, for each of the three readers, what fails and how to fix it.

Skills for a team, not one laptop

A skill in one developer’s ~/.claude/skills helps one developer. The harder part is getting the same skill to every agent that touches a team’s work, in the right project, and keeping keys out of it. That is where Agent Ready, our Jira app, keeps skills: a company library and each project’s own, imported from a SKILL.md, a .zip or the .tgz that npm pack downloads (read in the browser, nothing fetched). A project or a role, such as “Mobile security”, brings its skills to every work item it is on, and they reach the agent in the brief or through MCP with get-skill. A skill with a password or key in it is not saved, and Copy as SKILL.md takes it back to a repository. How to run skills for a whole team: agent skills for teams.

Sources

Frequently asked questions

How do you structure a SKILL.md file?

Put the skill in a folder named after it. SKILL.md starts on its first line with ---, then YAML frontmatter with at least name (lowercase letters, digits and hyphens, the same as the folder) and description (what the skill does and when to use it), then a closing ---. Under it, Markdown instructions: the steps, an example of input and output, and the edge cases. Longer material goes into references/, scripts into scripts/, templates into assets/.

What does a SKILL.md file look like?

Three lines of frontmatter and a short Markdown body is enough: "---", "name: changelog-entries", "description: Writes CHANGELOG.md entries in Keep a Changelog format. Use when the user finishes a change, asks for release notes or bumps the version.", "---", then numbered steps. The template on this page is a complete one to copy.

How long should a SKILL.md file be?

The Agent Skills specification asks for under 500 lines and under about 5,000 tokens of instructions, because the whole file is loaded every time the skill runs. In our sample of public skills the median was 73 lines; 6.7% went over 500 lines and 8.9% over 5,000 tokens. Move reference material into separate files the skill links to.

Why does claude.ai refuse a skill that works in Claude Code?

Claude Code accepts fields of its own, such as argument-hint, disable-model-invocation and model. A claude.ai upload and the Skills API accept only the six fields of the Agent Skills spec and stop with "Unexpected key(s) in SKILL.md frontmatter". In our sample, 30.7% of skills carried a field outside the spec, most often version.

Where do I put SKILL.md so every agent finds it?

No single folder covers all four big agents. .claude/skills is read by Claude Code, GitHub Copilot and Cursor; .agents/skills by Codex, GitHub Copilot and Cursor. Copilot also reads .github/skills, Cursor also .cursor/skills. A team that uses Claude Code and Codex keeps the skill in one place and links or copies it into the other.

Are skills from GitHub safe to install?

Only after you read them. Anthropic says to use skills "only from trusted sources", because a skill can tell the agent to run code or call tools. Read the SKILL.md and every script it ships, and check what allowed-tools grants. We found no real API key in 1,792 public skills, but two had fake ones that a scanner flags.

Keep reading