# SKILL.md format: the required frontmatter fields, and skills vs MCP

By markdownregistry. Published October 2, 2026. Updated October 2, 2026.

A skill is a folder with a SKILL.md file in it. SKILL.md opens with YAML frontmatter that must hold a `name` and a `description`, followed by instructions in markdown. The rules come from the [Agent Skills specification](https://agentskills.io/specification); the conformance counts come from the registry's crawl of 60,844 SKILL.md files in [State of agent markdown, September 2026](https://markdownregistry.com/reports/state-of-agent-markdown-2026-09).

| Rule | Files | Share |
| --- | --- | --- |
| No name | 1,244 | 2.0% |
| Name breaks the allowed characters or length | 1,327 | 2.2% |
| Name does not match its directory | 3,858 | 6.3% |
| No description | 979 | 1.6% |
| Description over 1,024 characters | 601 | 1.0% |
| Meets every rule above | 54,836 | 90.1% |

How public SKILL.md files inside a skill directory meet the Agent Skills specification's frontmatter rules, out of 60,844 such files. A file can fail more than one rule. Registry crawl, data frozen September 27, 2026; method and downloads in [the report](https://markdownregistry.com/reports/state-of-agent-markdown-2026-09).

Every claim about another tool was checked against that tool's own documentation on October 2, 2026. Figures are from [State of agent markdown, September 2026](https://markdownregistry.com/reports/state-of-agent-markdown-2026-09), data frozen September 27, 2026.

## What fields are required in SKILL.md frontmatter?

Two: name and description. The Agent Skills specification requires a name of 1 to 64 characters, made of lowercase letters, numbers and hyphens, not starting or ending with a hyphen, with no two hyphens in a row, and equal to the name of the skill's folder. It requires a description of 1 to 1,024 characters that says what the skill does and when to use it. license, compatibility, metadata and allowed-tools are optional, and allowed-tools is marked experimental.

A complete SKILL.md to start from, with what to change in it: [the SKILL.md template](https://mdpantry.com/s/st_shjaxurgoqng23jq).

```
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
---
```

In the registry's crawl, 54,836 of 60,844 SKILL.md files inside a skill directory (90.1%) meet every one of these rules; the most common failure is a name that does not match its directory (3,858 files, 6.3%). A file can fail more than one rule:

| Rule | Files failing | Share |
| --- | --- | --- |
| No name | 1,244 | 2.0% |
| Name has characters or hyphens the specification does not allow, or is over 64 characters | 1,327 | 2.2% |
| Name does not match its directory | 3,858 | 6.3% |
| No description | 979 | 1.6% |
| Description over 1,024 characters | 601 | 1.0% |
| Conforms to every rule above | 54,836 | 90.1% |

The specification defines four more fields, all optional: `license`, `compatibility`, `metadata` and `allowed-tools`.

```
---
name: release-notes
description: Draft release notes from merged pull requests. Use when preparing a release.
license: Apache-2.0
compatibility: Requires git and the gh CLI
metadata:
  version: "1.2"
allowed-tools: Bash(git:*) Read
---
```

- `license` names the license that applies to the skill; the specification suggests keeping it short, either the license's name or the name of a license file bundled with the skill.
- `compatibility`, if present, must be 1 to 500 characters, and belongs only in a skill with real environment needs: the product it is designed for, system packages it requires, or network access.
- `metadata` is a map from string keys to string values for properties the specification does not define; it suggests key names unlikely to collide with another client's. The registry reads `metadata.version`, like a top-level `version`, as the skill's version label ([how pinning uses it](https://markdownregistry.com/guides/pin-agent-skills)).
- `allowed-tools` is a space-separated list of tools the skill pre-approves. The specification marks it experimental, and support varies between agents.

## What is an agent skill and how does SKILL.md work?

An agent skill is a folder with a SKILL.md file in it, and optionally scripts, reference files and assets beside it. SKILL.md starts with YAML frontmatter holding a name and a description, then gives instructions in markdown. An agent loads skills in stages: at startup it reads only each skill's name and description, about 100 tokens each; when a task matches a description it reads the whole SKILL.md; and it opens the other files only when the instructions call for them. That is how one agent can carry many skills without filling its context.

The specification recommends keeping SKILL.md under 500 lines and moving detail into referenced files. A skill's `scripts/` folder holds code the agent can run, which is why a skill deserves the same care as software you install ([what to check before installing one](https://markdownregistry.com/guides/agent-skill-security)). Real examples: [61,170 SKILL.md skills from public GitHub](https://markdownregistry.com/kind/skill).

## Claude skills vs MCP servers: when should I use each?

Use an MCP server to connect an agent to a system where data or actions live, such as a database, a file store or a business tool; use a skill to teach the agent how to do a task, such as a procedure, a document format or your team's conventions. Anthropic's own summary is that MCP connects Claude to data, and skills teach Claude what to do with that data. They work together: an MCP server for access, and a skill for the procedure that uses it.

From [Anthropic, Skills explained](https://claude.com/blog/skills-explained). A skill costs little until it is used, because only its name and description stay in context.

## Sources

- [Agent Skills specification](https://agentskills.io/specification)
- [Anthropic: Skills explained](https://claude.com/blog/skills-explained)
- [Claude Code docs: skills](https://code.claude.com/docs/en/skills)

Last checked October 2, 2026. The page: https://markdownregistry.com/guides/skill-md-frontmatter