Agent Skills Guide: How SKILL.md Works and When to Write One (2026)

An Agent Skill is a folder with a SKILL.md file in it. The frontmatter tells the agent when to use the skill; the markdown body tells it how. Everything else in the folder — reference docs, templates, scripts — is optional, and exists so the main file can stay short.

That description makes skills sound trivial, and mechanically they are. What makes them worth understanding is the loading model underneath, because it inverts the usual tradeoff between "give the agent enough context" and "do not blow up the context window."

Key takeaways:

• Progressive disclosure runs in three levels: names and descriptions at startup, the body on match, supporting files on demand.
• The description is the only part the model sees when deciding. Write it as a routing rule, not a summary.
• Facts belong in your context file. Procedures belong in skills. The dividing line is whether it should be in context on every turn.
• Directory name becomes the command. Frontmatter name is a display label everywhere except plugin skills.
• allowed-tools pre-approves tools for the invoking turn only; the grant clears on your next message.
• context: fork runs a skill in its own subagent so a heavy procedure does not flood the main thread.
• Six frontmatter fields are portable across the open standard. Everything else is tool-specific and will fail packaging if you are targeting the spec.

The Three Levels of Progressive Disclosure

This is the mechanism the rest of the design follows from.

Two consequences follow, and both are load-bearing.

First, the description carries all the routing weight. At the moment of decision, the body does not exist as far as the model is concerned. A skill with a brilliant body and a vague description never fires. A skill with a mediocre body and a precise description fires exactly when it should, and you can improve the body later.

Second, length in the body is cheap and length in the description is not. Once a skill has been selected, a thorough body costs one load. The description, by contrast, is paid on every session for every skill. Claude Code combines description with the optional when_to_use field and truncates the pair at 1,536 characters in the skill listing, so front-load the key use case.

This is context engineering applied at the file level: decide what must always be present, what should be retrievable on demand, and what belongs one level deeper still. The Context Engineering Maturity Model frames the same decision at the system level.

Anatomy of a SKILL.md

---
name: weekly-status
description: Builds the weekly status report from the sprint board and deploy log.
  Use when asked for a status update, weekly report, or sprint summary.
allowed-tools: Read Grep Bash(git log:*)
---

# Weekly Status Report

## Inputs
- Sprint board export at `reports/sprint.csv`
- `git log` for the last 7 days on `main`

## Steps
1. Read `reports/sprint.csv`. Group items by status.
2. Run `git log --since="7 days ago" --oneline main` and group commits by area.
3. Write the report to `reports/status-<ISO date>.md` using the structure in
   `template.md` in this skill directory.
4. Flag any sprint item that is still In Progress and has no commits.

## Rules
- Never invent a completion. If an item has no evidence, list it as unverified.
- Keep the summary under 300 words. Detail goes in the appendix section.

Note what is doing the work. The description names trigger phrases people actually say. The body is a procedure, in imperative steps, not a description of a procedure. The rules section encodes the failure mode this skill exists to prevent.

The Frontmatter Fields Worth Knowing

All fields are optional; only description is genuinely recommended.

The pairing worth internalizing is disable-model-invocation and user-invocable. They are the two halves of one question: who is allowed to start this? A deployment procedure should be disable-model-invocation: true so it only ever runs when a human types the command. A house style guide should be user-invocable: false so the model can pull it in when relevant without cluttering the menu with something nobody types.

Where Skills Live

The command you type comes from the directory name, not the frontmatter. In a personal or project skill, name is only a display label in listings. Plugin skills are the exception: there, name sets the last segment of the namespaced command.

Nested skills are the monorepo answer. A .claude/skills/ directory inside apps/web/ becomes available once the agent reads or edits a file under apps/web/, so a package can ship its own procedures without every session at the repo root carrying them.

Skills vs. Context Files vs. MCP vs. Subagents

These get conflated constantly, and the distinctions are practical rather than pedantic.

The decision rule for the first two: if it should influence every task, it is a fact and belongs in the context file. If it only matters sometimes, it is a procedure and belongs in a skill. The clearest signal that you need a skill is watching a section of CLAUDE.md grow from a statement into a numbered procedure.

For the third, remember that skills and MCP are complements rather than alternatives. A skill can describe a procedure that calls MCP-provided tools; the skill is the know-how and the server is the reach. See the MCP canonical.

Design Rules That Decide Whether a Skill Works

1. Write the description as a routing rule

The single highest-leverage sentence in the whole file.

The second one names the operations, the technology, and the trigger phrases. It will fire when it should and stay quiet when it should not.

2. Make the body a procedure, not prose

Skills that read like documentation produce agents that write documentation. Skills that read like a runbook produce agents that follow a runbook. Use imperative steps, name exact file paths and commands, and state the checks.

3. Encode the failure mode

The most valuable line in most skills is the one that prevents a specific known mistake: "never modify the test to make it pass," "if the item has no evidence, mark it unverified," "stop and ask if the migration would lock a table over 1M rows." You are not writing a tutorial for a competent reader; you are constraining a system that will otherwise take the shortest path to something that looks like success.

4. Push reference material into supporting files

If the skill needs a 200-line style guide or a lookup table, put it in the folder and reference it from the body. Level three of progressive disclosure means it costs nothing until the agent needs it.

5. One skill, one job

A skill that handles "reports and deploys and migrations" has a description that matches everything, which means it fires on unrelated requests and burns context. Split it. Skills are cheap; muddled routing is not.

Portability: What Works Outside One Tool

Agent Skills is an open standard, and adoption in 2026 is broad. OpenAI's Codex CLI supports skills, and Google's Antigravity CLI reads skills from .agents/skills/.

The caveat is field support. Claude Code accepts a long list of frontmatter fields, but the bare spec — used by claude.ai skill uploads and the Skills API — accepts only six:

name, description, license, compatibility, metadata, allowed-tools

Including a field outside that set does not get silently ignored; packaging or upload fails with an explicit error. If you want one folder to work everywhere, restrict frontmatter to those six and keep tool-specific behavior out of the file.

A Reasonable Starting Set

If you are writing your first skills, these three earn their keep in almost any repository:

• A ship check. The exact sequence that proves a change is safe to merge: typecheck, lint, test, build, and whatever project-specific verification exists. Mark it disable-model-invocation: true so it runs when you ask.
• A review checklist. The things your team actually catches in review, written as checks rather than principles. This one should be model-invocable so it fires when someone asks for a review.
• A "how we do X here" reference for the one subsystem everybody gets wrong the first time — the auth flow, the migration process, the caching layer. Long body, precise description, user-invocable: false if nobody would ever type it.

Start there, then add a skill the next time you notice yourself pasting the same instructions twice. That is the real trigger, and it is more reliable than any taxonomy.

Where to Go Next

• The facts-versus-procedures counterpart: AGENTS.md guide
• Prompting the agent that runs these skills: Claude Code prompting guide
• The system-level framing: context engineering best practices
• Turning repeated prompts into durable assets: how to build a prompt library
• Generate a structured starting prompt with the SurePrompts builder