How to write an agent skill: the SKILL.md format, field by field

To write an agent skill, you make a folder, put a SKILL.md file in it, and give that file two required YAML fields: name and description. Everything else in the format is optional. The genuinely hard part of how to write an agent skill is the description, because it is the only text an agent reads before it decides whether to load anything else you wrote.

This post walks the Agent Skills specification field by field as we read it on October 23, 2026, with the limits each field actually enforces, the body-size budget the spec recommends, where four different clients look for the folder, and a testing loop that tells you whether your description fires on the right prompts. In our view most skills that fail do not fail on syntax - they fail because they never activate, or because they activate on everything.

What an agent skill is: one folder, one SKILL.md file

An agent skill is a directory containing, at minimum, a SKILL.md file with YAML frontmatter followed by Markdown instructions. The specification adds three optional conventional subdirectories: scripts/ for executable code, references/ for documentation the agent reads on demand, and assets/ for templates and data files. Any other files and directories are allowed.

The point of the format is what the spec calls progressive disclosure, and it is worth understanding before you write a line. Agents load skills in three stages: at startup they read only each skill's name and description; when a task matches a description they read the whole SKILL.md body into context; then they execute, loading bundled scripts or reference files only as needed. The overview page puts the consequence plainly - "Full instructions load only when a task calls for them, so agents can keep many skills on hand with only a small context footprint."

The format was developed by Anthropic and released as an open standard; the specification and documentation repository licenses its code under Apache 2.0 and its documentation under CC-BY-4.0, and showed roughly 26,400 GitHub stars when we checked on October 23, 2026.

What fields does SKILL.md require, and what does each one constrain

Two fields are required and four are optional. These are the constraints the specification states, as of October 23, 2026:

Three of those rules trip people up. The name must match the folder name, so renaming the directory without editing the file breaks the skill. The description has a hard ceiling of 1,024 characters, and the spec's own guidance on optimizing descriptions warns that descriptions "tend to grow during optimization" - check the count after each revision. And allowed-tools is explicitly experimental, so we would not build a security boundary on it; treat it as a convenience that may or may not be honored by the client your teammate uses.

The spec also says most skills do not need the compatibility field at all. Add it only when your skill really will fail without something specific - its examples are "Requires git, docker, jq, and access to the internet" and "Requires Python 3.14+ and uv".

How to write an agent skill that the agent will actually load

The description carries the entire burden of triggering, because it is all the agent has at discovery time. The specification's guidance is specific about how to phrase it, and four points matter most:

• Use imperative phrasing. Write "Use this skill when…" rather than "This skill does…" - the agent is deciding whether to act.
• Describe user intent, not internals. The agent matches against what the user asked for, not how your code works.
• Be pushy about scope. The guidance says to list contexts explicitly, "including cases where the user doesn't name the domain directly".
• Stay short. A few sentences to a short paragraph, inside the 1,024-character limit.

The spec's own before-and-after is the clearest illustration we found. Before: "Process CSV files." After: a description naming summary statistics, derived columns, charts and cleaning, applying to CSV, TSV and Excel files, "even if they don't explicitly mention 'CSV' or 'analysis.'"

One nuance the docs raise is easy to miss, and it will save you an afternoon of debugging: agents "typically only consult skills for tasks that require knowledge or capabilities beyond what they can handle alone". A one-step request like "read this PDF" may not trigger a PDF skill at all, because the agent can just do it. If your skill wraps something the model already does well, a better description will not rescue it.

Keep SKILL.md under 500 lines and push the rest into references

The specification gives a three-tier budget: roughly 100 tokens of metadata loaded at startup, under 5,000 tokens recommended for the SKILL.md body once activated, and resources loaded only when required. It also says to keep SKILL.md under 500 lines and move detailed reference material into separate files.

The best-practices guide is blunt about why: once a skill activates, its full body "loads into the agent's context window alongside conversation history, system context, and other active skills", so every token competes for attention. Its test for each paragraph is the one we would keep taped to the monitor - "Would the agent get this wrong without this instruction?" If not, cut it.

Two pieces of that guidance do more work than the rest:

1. Tell the agent when to load each file, not just that files exist. The guide contrasts "Read references/api-errors.md if the API returns a non-200 status code" with a generic "see references/ for details" - the first is a trigger, the second is decoration. Keep references one level deep from SKILL.md.
2. Write a gotchas section. The guide calls environment-specific facts that defy reasonable assumptions "the highest-value content in many skills" - a table that uses soft deletes, an ID field with three different names across three services, a /health endpoint that returns 200 while the database is down. Keep gotchas in SKILL.md itself, because the agent may not recognize the trigger to go load them.

On scripts: the guidance is to bundle a tested script when you notice the agent "independently reinventing the same logic each run". Parsing, format conversion and chart building are deterministic; prose that asks the model to re-derive them every session is both slower and less reliable. Scripts should be self-contained or document their dependencies, and the supported languages depend on the client - Python, Bash and JavaScript are the common ones. If those scripts will touch anything you care about, the isolation boundary matters more than the skill does; we covered how those boundaries differ in our guide to comparing AI agent sandboxes.

From empty folder to working skill, in five steps

The specification's quickstart builds a dice-rolling skill in under 20 lines. Generalized, the loop is:

1. Do the task by hand first. The best-practices guide recommends completing a real task in conversation with an agent, then extracting the reusable pattern - keeping the steps that worked, the corrections you made, the input and output formats, and the project-specific context the agent did not already know.
2. Create the folder and the file. The directory name and the name field must match.
3. Write the description for the router, the body for the worker. Description: when to use this. Body: step-by-step instructions, example inputs and outputs, edge cases.
4. Validate the frontmatter. The repository ships a reference library, skills-ref, with a validate command that checks the frontmatter and the naming conventions.
5. Run it against real tasks and revise. The guide says even a single pass of execute-then-revise noticeably improves quality, and to read execution traces rather than only final outputs.

Where the folder goes depends on the client, and this is the detail that most often makes a working skill look broken. VS Code looks in .agents/skills/ by default, per the quickstart. Claude Code loads personal skills from ~/.claude/skills/skill-name/SKILL.md and project skills from .claude/skills/skill-name/SKILL.md, with enterprise, nested, plugin and claude.ai-synced locations alongside them; its own docs say enterprise overrides personal and personal overrides project when two skills share a name. If your skill is not appearing, check the path before you rewrite the description.

Do agent skills replace MCP servers?

No, and treating them as competitors is the most common misreading we see. MCP describes itself as "an open-source standard for connecting AI applications to external systems" - data sources, tools and workflows - and uses a USB-C port as its analogy. Agent Skills package procedural knowledge: what to do, in what order, with what conventions.

The practical division: MCP gets the agent access to your database, your issue tracker or your design files. A skill tells it that your users table uses soft deletes, that migrations run through one exact command, and that the report goes out in a particular template. One is a connection, the other is a procedure, and a serious setup usually wants both. Upfynd lists 208 products in AI agents and 121 in AI coding tools as of October 2026; when you shortlist one, we'd check its docs for both - which skill directories it reads, and whether it can connect to an MCP server.

How to test an agent skill before you share it

Triggering is testable, and the spec documents a method rather than leaving you to vibes. Build about 20 realistic prompts, 8-10 labeled should-trigger and 8-10 should-not-trigger, then run each one several times - model behavior is nondeterministic, so the guidance is three runs each and a trigger rate, with 0.5 as a reasonable pass threshold.

Two refinements are what make this more than a smoke test:

• Make the negatives near-misses. The guidance calls "Write a fibonacci function" a weak negative that "tests nothing", and offers "I need to update the formulas in my Excel budget spreadsheet" as a strong one for a CSV skill: same vocabulary, different job.
• Split train and validation. Roughly 60% of queries guide your edits and 40% are held back to check that the edits generalize. The guidance warns against adding keywords lifted from failed queries, because that is overfitting, and notes the best description "may not be the last one you produced".

Five iterations is usually enough, the docs say; if nothing improves, suspect the queries rather than the description.

One portability caveat to hold on to. Individual clients add frontmatter and body features the open spec does not define - Claude Code's documentation describes argument placeholders and a disable-model-invocation flag that makes a skill run only when typed as a command. Those are useful, and they are not in the specification, so a skill that relies on them is a Claude Code skill rather than a portable one. If you intend to share it, keep the client-specific parts out of the critical path and say so in the compatibility field.

Start with the skill you already explained twice

In our view the strongest signal that a skill is worth writing is a correction you have made to an agent more than once. Write that down as a gotcha, wrap the procedure around it, keep the file short, and test the description against prompts you did not write while optimizing it. If the result is a tool other people should find, list it on Upfynd - listing is free, and a person checks every submission before it goes live.