Agent Skills: What Has to Be Inside a SKILL.md

📘 Tutorials 2026-11-22 8 min read

A skill is installed, the model never opens it, and the body keeps getting longer in the hope that length fixes routing.

📜 Table of Contents

A skill that never fires looks like a content problem. It is a routing problem. The model does not browse your folder. At startup it sees one line per skill, the name and the description, and that line is the only reason it will ever open the rest.

So the useful question is not how to write a good prompt inside a file. It is: what does the runtime read, what does it defer, and what has to sit in the deferred part for a procedure to survive being read by something that had no part in writing it.

Below is the spec as published at agentskills.io on 22 November 2026, plus measurements from the 19 reference skills in the anthropics/skills repository (198,366 stars, last push 16 November 2026, pulled from the GitHub API today). Every count came out of that repository, not out of a vendor blog.

The folder is the interface

A skill is a directory. One file is required, three subdirectories are conventional:

release-notes/
├── SKILL.md          # required: frontmatter + instructions
├── scripts/          # optional: runnable code the agent calls
├── references/       # optional: docs loaded only when needed
└── assets/           # optional: templates, fixtures

Nothing else is mandatory. No manifest, no build step, no server. If you can ship a folder of Markdown you can ship a skill, which is most of the reason the format spread faster than tool-calling schemas did.

Frontmatter: six fields, two of them load-bearing

fieldrequiredconstraintwhat it decides
nameyes1-64 chars, lowercase a-z, 0-9 and hyphens; no leading or trailing hyphen; no double hyphen; must equal the folder nameidentity, and whether validation passes at all
descriptionyes1-1024 charswhether the skill is ever selected. This is the only text the model sees before activation
licensenoshort name or bundled filenothing at runtime; matters for reuse
compatibilitynomax 500 charsdeclares required binaries, OS, network
metadatanostring to string mapauthor, version, whatever your tooling wants
allowed-toolsnospace-separated, experimentalpre-approved commands such as Bash(git:*) Bash(jq:*) Read

The naming rules are stricter than they look, and they are the first thing that breaks. PDF-Processing fails on uppercase. -pdf fails on the leading hyphen. pdf--processing fails on the double hyphen. pdf-processing inside a folder called pdf_processing fails because the name must match its parent directory. Four ways to get a valid idea rejected before it runs once.

Progressive disclosure: three loads, one budget

The spec defines exactly three moments when text enters the context:

stagewhat loadswhenpublished budget
metadataname and description of every installed skillalways, at session startabout 100 tokens per skill
instructionsthe whole SKILL.md bodywhen the skill is activatedunder 5,000 tokens recommended
resourcesscripts/, references/, assets/only when the procedure asks for a fileas needed

I measured the first row instead of trusting the tilde. Across the 19 reference skills the description field totals 1,290 tokens, an average of 68 each. Twenty skills idle cost roughly 1,360 tokens, which is affordable in a way that twenty tool schemas are not.

The third row is where the leverage sits. A skill can carry a 26,000-token reference manual and still cost about 100 tokens until somebody asks for it. That claim holds only as long as the body points at the file instead of pasting it in.

The part people get wrong: the description is a routing key

Two descriptions for the same skill:

description: Helps with release notes.
description: Writes release notes from a git commit range. Use when the user asks for a
changelog, release notes, what changed since v1.4, or a summary of commits between
two tags. Reads git log output only; never invents entries.

The second works because it contains the words a person would actually type, and because it states a boundary. The spec asks for both: what the skill does, and when to use it, with the keywords that identify the task. That is not copywriting advice. It is the retrieval key.

The boundary sentence carries more weight than it looks. Reads git log output only, never invents entries, is an instruction with teeth, and in contexts where the body gets truncated or compressed it is often the only instruction that survives.

A SKILL.md that passes review

The example turns a recurring chore, writing release notes from a commit range, into a skill. Watch the shape: short main file, one script, one reference, one template.

---
name: release-notes
description: Writes release notes from a git commit range. Use when the user asks for a
  changelog, release notes, what changed since vX, or a summary between two tags.
  Reads git output only and never invents entries.
compatibility: Requires git, plus Python 3.10 for scripts/collect.py
allowed-tools: Bash(git:*) Read
---

# Release notes

## Steps
1. Run scripts/collect.py FROM_TAG TO_TAG to dump commits as JSON.
2. Drop merge commits, and commits touching only tests or docs.
3. Group the rest into Added / Changed / Fixed using references/CLASSIFY.md.
4. Render with assets/RELEASE_TEMPLATE.md.
5. If a commit message is unclear, list it under Unclassified instead of guessing.

## Rules
- One line per user-visible change. No commit hashes in the output.
- Never describe a change the diff does not support.
- If the range is empty, say so and stop.

## Example
Input: v1.3.0..v1.4.0, 47 commits.
Output: 12 entries across three headings, 4 commits listed as unclassified.

Three things there are doing real work. The steps are numbered so the agent does not improvise an order. The classification rules sit one level down in a file referenced by relative path, which is what the spec means by keeping references one level deep from SKILL.md. And there is an explicit fallback for unclear input, because the failure that hurts is a plausible fabrication, not an empty answer.

What the 500-line rule is for

The spec recommends keeping the main file under 500 lines and the body under 5,000 tokens. The reference repository shows what happens without that discipline. Of the 19 skills, three exceed the token guidance: claude-api at 26,384 tokens across 609 lines, skill-creator at 7,172, and pptx at 6,993. The other sixteen average 1,756 tokens.

Those outliers are not mistakes. claude-api is a working API reference, and its authors accept the cost because reading it is the task. The lesson is narrower: a 600-line body is a deliberate trade, and you should know which side of it you are on. If your body is long because you pasted documentation into it, move the documentation to references/ and keep the procedure in the body.

Validate before you install

skills-ref validate ./release-notes

The reference validator checks frontmatter against the naming and length rules. Run it before copying the folder anywhere, because a skill that fails validation fails silently in most clients: it does not appear in the list at all, and you spend the afternoon debugging the model when the problem is a YAML field.

When a skill is the wrong shape

Skills are one of four ways to give an agent capability, and they solve different problems. The Model Context Protocol specification dated 2026-07-28 draws the lines plainly:

shapewho triggers itcost when idlegood for
MCP toolthe model decides, calling tools/call against a typed inputSchemathe full schema, every sessionone action with typed arguments and a checkable result
MCP resourcethe application decides, read via resources/reada discovery listingdata the app fetches and hands over as context
MCP promptthe user picks it, arguments arrive as stringsa listingreusable templates a human chooses on purpose
skillthe model decides from the description, then reads filesabout 100 tokens of metadatamulti-step procedure, house style, scripts, reference material

If what you want is call this endpoint and get JSON back, a tool is correct and a skill would be a wrapper around a tool you did not write. If what you want is follow these nine steps in this order, in our format, using this script, a skill is correct and a tool would have to encode all nine steps in a schema nobody can read.

The two compose. Install an MCP server for the typed actions, then write a skill that says which action comes first. The skill costs about 100 tokens idle. The server schemas cost whatever they cost, and that bill arrives whether or not anything is used.

FAQ

Does the file have to be named SKILL.md, uppercase? Yes. The spec names that file explicitly and discovery walks directories looking for it. A lowercase skill.md is invisible to clients that follow the spec.

Can one skill call another? Not by reference. There is no import mechanism in the spec. The practical workaround is a shared references/ file that both bodies point at, which keeps duplicated text in one place.

How many skills can I install? Metadata averages 68 tokens per skill in the reference set, so a hundred skills is roughly 7,000 tokens of idle overhead. That is tolerable. The real ceiling is description collisions: two skills that both claim summarize documents will split the traffic unpredictably.

Do I need scripts at all? No. A pure Markdown skill is legal and often enough. Scripts earn their place when a step is deterministic and would otherwise be re-derived from prose every time, which is where drift and invented flags come from.

Is this Anthropic-only? The format is published as an open specification at agentskills.io with a validator library, and the repository also ships a plugin manifest for Claude Code. Treat SKILL.md as a portable text format rather than a vendor feature.

What to do next

Take the one procedure you have explained to an agent more than twice this month. Write the description first, in the words you would actually search for. Then four numbered steps. Then move everything else into references/. Run the validator, install it, and watch whether it fires without being named. If it does not fire, the description is wrong, and no amount of body text fixes routing.

Related: what 37 MCP tool schemas cost in tokens, self-hosted agent memory, per-key budget caps in LiteLLM.

Related Articles
2026-08-13
Cursor Rules Examples 2026: 12 Real .cursorrules for Python, React and Data Work
2026-08-11
LLM Security 2026: The OWASP Top 10 for LLM Apps, Explained With Fixes
2026-11-02
This Week's GitHub Stars Ranking: Codex Leads with 1865 Stars Gained
2026-08-01
LLM Finetuning Toolkit 2026: Unsloth vs Axolotl vs TRL Compared
2026-08-07
AI Photo Restoration: Bring Old Family Photos Back to Life - Open Source
2026-08-01
Local LLM Setup in 2026: What Reddit Actually Recommends (from r/LocalLLaMA)

Written by our editorial team; tools listed here are tested or verified against public sources. Links point to official sites or GitHub repos for reference only — no paid placements.

💬 Comments (0)

No comments yet. Be the first!

Login to comment