SKILL.md Format Explained: Frontmatter, Folders and Limits

SKILL.md is a Markdown file with YAML frontmatter that defines an Agent Skill. The frontmatter needs two fields, name and description. Everything after it is free-form instructions for the agent. The file sits at the root of a folder that can also hold scripts/, references/ and assets/.

This post walks through every field in the Agent Skills specification, the extra rules Claude adds, the Claude Code-only fields, the folder layout and the limits that matter. If you are new to skills, read what are agent skills first, then the complete guide to Agent Skills for how they load and run. The spec itself is maintained by the open Agent Skills project.

The minimal SKILL.md

This is a complete, valid skill:

---
name: commit-messages
description: Writes commit messages in Conventional Commits format from staged changes. Use when the user asks for a commit message or wants to commit staged work.
---

# Commit messages

1. Run `git diff --staged` to see the changes.
2. Pick a type: feat, fix, docs, refactor, test or chore.
3. Write a subject under 72 characters in the imperative mood.
4. Add a body only if the why is not obvious from the diff.

The frontmatter sits between two --- lines at the very top. The agent loads the name and description at startup. It reads the body only when it decides the skill is relevant.

Frontmatter fields in the open spec

The spec defines six fields. Only the first two are required.

Field	Required	Rules
name	Yes	1 to 64 characters. Lowercase letters, numbers and hyphens. No leading, trailing or double hyphens. Must match the folder name.
description	Yes	1 to 1,024 characters. Says what the skill does and when to use it.
license	No	A license name or a pointer to a bundled license file.
compatibility	No	Up to 500 characters. Environment needs such as required tools or network access.
metadata	No	A map of string keys to string values, for anything else.
allowed-tools	No	Space-separated list of pre-approved tools. Marked experimental.

name

The name is the skill's ID. It must match the parent directory, so commit-messages/SKILL.md needs name: commit-messages. Claude's docs add two rules on top of the spec: no XML tags, and no reserved words anthropic or claude. Anthropic's best practices suggest gerund names like processing-pdfs and warn against vague names like helper or utils.

description

This is the most important line in the file. The agent compares each request against every installed skill's description to decide which one to load. A good description names the task, the inputs and the trigger words a user would actually type:

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

Anthropic recommends writing it in the third person, because it is injected into the system prompt. "Processes Excel files" works. "I can help you with Excel" does not.

license, compatibility and metadata

These are informational. Use compatibility only when the skill truly needs something specific:

license: Apache-2.0
compatibility: Requires git and Python 3.10+. No network access needed.
metadata:
  author: example-org
  version: "1.2.0"

Quote version numbers in metadata so YAML keeps them as strings.

allowed-tools

This lists tools the agent may use without asking, for example Bash(git:*) Read. The spec marks it experimental and says support varies between agents. Treat it as a convenience, not a security boundary, and keep it narrow.

Claude Code's extra fields

Claude Code supports the spec fields plus its own. A few that come up often:

• disable-model-invocation: true stops Claude from loading the skill on its own. You run it manually as a slash command. Good for anything with side effects, like deploys.
• user-invocable: false hides the skill from the / menu so only Claude can load it. Good for background knowledge.
• argument-hint shows expected arguments in autocomplete. Use $ARGUMENTS in the body to receive them.
• context: fork runs the skill in a forked subagent, with agent choosing the subagent type.
• model and effort change the model or effort level for the current turn.
• paths limits activation to files matching glob patterns.

Claude Code silently ignores fields it does not recognise, so a typo like disable_model_invocation fails quietly. Other tools have their own extras. Codex keeps UI and policy settings in a separate agents/openai.yaml file (Codex docs), and VS Code supports argument-hint, user-invocable, disable-model-invocation and context (VS Code docs). For maximum portability, stick to the spec fields.

The body

The spec places no format rules on the body. Recommended content is step-by-step instructions, input and output examples, and edge cases. A few habits from Anthropic's guidance make a real difference:

• Be concise. Only include what the model does not already know.
• Match strictness to risk. Loose guidance for open tasks like reviews. Exact commands for fragile ones like migrations.
• Use checklists for multi-step work so the agent does not skip validation.
• Use forward slashes in paths, even on Windows.
• Say whether to run or read a script. "Run scripts/validate.py" and "See scripts/validate.py for the algorithm" lead to different behaviour.

A recommended body outline

The spec recommends step-by-step instructions, examples of inputs and outputs, and common edge cases. Claude's skill structure template uses Instructions and Examples headings. A body that covers both looks like this:

# Skill title

## Workflow
1. First step, with the exact command if it is fragile.
2. Second step.
3. Validate, fix errors, repeat until it passes.

## Rules
- Constraints the agent must always follow.

## Examples
Input: a short, realistic request.
Output: what good output looks like.

## Edge cases
- What to do when input is missing or a script fails.

## References
- [references/STYLE.md](references/STYLE.md) for formatting rules.

Anthropic's best practices add one more habit: for multi-step work, give the agent a checklist it can copy and tick off, so it does not skip validation.

Folder layout and bundled files

A skill that has grown beyond one file looks like this:

release-notes/
├── SKILL.md
├── scripts/
│   └── collect_commits.py
├── references/
│   └── STYLE.md
└── assets/
    └── template.md

• scripts/ holds code the agent can execute. The spec says scripts should be self-contained or document their dependencies, print helpful errors and handle edge cases. When the agent runs a script, only its output enters context, not its source.
• references/ holds extra documentation loaded on demand. Smaller, focused files mean less context used.
• assets/ holds templates, schemas, lookup tables and images.

Link to these files with relative paths from the skill root:

For tone and formatting rules, read [references/STYLE.md](references/STYLE.md).

To gather commits, run:
python scripts/collect_commits.py v1.4.0 HEAD

Keep links one level deep. Anthropic notes that when a reference points to another reference, Claude may only preview the nested file and miss details. For reference files over 100 lines, add a short table of contents at the top.

Because scripts run with the agent's permissions, they are also the part of a skill most worth reviewing. Our AI agent security guide explains what to look for.

Size limits and budgets

What	Limit or guidance	Source
Metadata cost	About 100 tokens per skill	Spec and Claude docs
SKILL.md body	Under 500 lines, under 5,000 tokens recommended	Spec
Bundled files	No context cost until read	Claude docs
Claude Code listing	description plus when_to_use truncated at 1,536 characters	Claude Code docs
Claude API upload	Under 30 MB uncompressed, up to 20 skills per request	Skills API guide

The Skills API guide also notes that a new version of a custom skill is a full snapshot. Upload every file each time.

A real example from Anthropic

Anthropic's skills repository is the best place to read production skills. The document skills (docx, pdf, pptx, xlsx) show the pattern at scale: a short SKILL.md that routes to deeper reference files and ships scripts for the fragile steps. The repo also has a template/ folder to copy from.

Common SKILL.md errors

Most broken skills fail on a handful of mistakes:

Error	What happens	Fix
name does not match the folder	Fails spec validation	Rename the folder or the field so they match
Uppercase, spaces or -- in name	Fails spec validation	Use lowercase letters, numbers and single hyphens
description contains : or # without quotes	Invalid YAML, or a description cut off at the #	Wrap the description in double quotes
Text before the opening ---	Claude Code treats the whole file as body, with no frontmatter	Put --- on line 1
Misspelled field, such as disable_model_invocation	Claude Code ignores it without an error	Copy field names exactly, hyphens included
< and > in the description	Claude Code shows them as &lt; and &gt;	Use square brackets, such as [branch]
Reference files that link to other reference files	Claude may only preview the nested file	Link every reference directly from SKILL.md

The colon rule comes from the YAML 1.2 spec: an unquoted value must never contain a colon followed by a space, or a space followed by #. Descriptions often break it with phrases like "Use when: the user asks". The Claude Code rows come from the Claude Code skills docs, and the nesting row from Anthropic's best practices.

Skill not loading? Troubleshooting

If your agent ignores a skill, check these in order. The steps follow Claude Code's troubleshooting section; other agents behave similarly but check their own docs.

1. Is it in the right place? Claude Code reads ~/.claude/skills/<name>/SKILL.md and .claude/skills/<name>/SKILL.md. Codex, VS Code and Gemini CLI read .agents/skills/.
2. Can the agent see it? In Claude Code, run /skills or ask "What skills are available?".
3. Does the frontmatter parse? If the YAML is malformed, Claude Code still loads the body but with empty metadata, so it can never match your description. Run Claude Code with --debug to see the parse error, or run skills-ref validate (below).
4. Does the description match the request? Add the words users actually type, then try the prompt again in a fresh session.
5. Are there too many skills? When the skill listing exceeds its budget, Claude Code drops some descriptions. /doctor shows the listing's context cost.

For a step-by-step testing method, including a should-trigger and should-not-trigger query set, see our guide on how to write and test an agent skill.

Validating your file

The spec project ships a reference validator, skills-ref:

skills-ref validate ./release-notes

It checks frontmatter and naming rules. It does not check whether your instructions are good or your scripts are safe. When you publish a skill repo, AgenticMart detects it by the SKILL.md file or a skills/ folder and any listing can get a free automated scan; each listing page shows its scan status, and how the free scan works explains what is checked. A scan is a malware and risk check, not a safety guarantee. Published skills appear in the agent skills directory. To build one from scratch, follow our tutorial on how to write an Agent Skill.

FAQ

Which SKILL.md fields are required?

Only name and description. The spec also defines optional license, compatibility, metadata and allowed-tools, and individual tools such as Claude Code add their own optional fields.

Does the name have to match the folder name?

Yes, under the open spec the name must match the parent directory. In Claude Code the name is optional and defaults to the directory name, but keeping them identical avoids surprises across tools.

How long can a SKILL.md file be?

There is no hard cap on the body, but the spec recommends under 500 lines and under 5,000 tokens. Move longer material into references/ files, which cost nothing until the agent reads them.

Can a skill include code in any language?

Yes. Supported languages depend on the agent and its environment, with Python, Bash and JavaScript the common choices. On the Claude API, scripts can only use pre-installed packages because there is no network access.

Why does my SKILL.md frontmatter not work?

The usual causes are text before the opening ---, an unquoted description that contains a colon followed by a space, and misspelled field names. Quote the description, put --- on the first line, and run skills-ref validate to check the result.

Is version a required SKILL.md field?

No. The open spec has no version field. If you want to record one, put it under metadata as a quoted string, such as version: "1.2.0". Registries that require a version are setting their own rules, not the spec's.