Agent Skills, SKILL.md, and AGENTS.md: an overview

What "skills" mean for AI coding agents, how SKILL.md and AGENTS.md differ, and when to reach for each.

If you’ve started handing real work to an AI coding agent — Claude Code, Codex, Cursor, and friends — you’ve probably hit the same wall twice:

You keep re-explaining the same project facts (“we use pnpm, run the tests with turbo, never commit to main”).
You keep re-pasting the same multi-step procedure (“here’s exactly how we cut a release / write a changelog entry / generate a migration”).

Two file formats have emerged to fix these two problems, and they are easy to confuse because both are “just Markdown files that tell an agent what to do.” They solve different problems and are meant to be used together.

	AGENTS.md	Agent Skills (`SKILL.md`)
Answers the question	”How does this repo work?"	"How do I perform this task?”
Scope	One project (the repo it lives in)	Reusable across projects / tasks
Shape	A single Markdown file at the repo root	A folder with a `SKILL.md` plus optional scripts/resources
Who reads it	Many tools (Codex, Cursor, Copilot, Gemini, Claude Code, …)	Claude and other tools following the Agent Skills standard
When it loads	Read as ambient context for work in that repo	Loaded on demand, only when the task calls for it
Analogy	A README written for the agent	A plugin / playbook the agent picks up when relevant

The rest of this page gives you the mental model. Two companion deep-dives cover the exact file formats with copy-pasteable examples:

SKILL.md files — the format behind Claude Agent Skills.
AGENTS.md files — the cross-tool repo convention.

What is a “skill”?

A skill is a self-contained, reusable capability you hand to an agent: a set of instructions (and optionally scripts, templates, and reference material) that teaches the model how to do one thing well. Think of the difference between knowing a fact and knowing a procedure. A fact (“this project uses PostgreSQL”) is cheap to keep in context all the time. A procedure (“here is our 40-line checklist for safely writing and testing a database migration”) is expensive to keep around when you’re not migrating anything.

Skills exist to make procedures cheap when idle and available when needed. The agent knows a skill exists (a one-line description sits in context), but the full instructions only load into the conversation when the model — or you — decides the skill is relevant. Anthropic packages this as Agent Skills, where each skill is a folder containing a SKILL.md file. The same idea, “give the model a capability it loads on demand,” is what people mean when they talk about “skills” for agents generally.

The key insight: an agent’s context window is a scarce, shared resource. Every token of instruction you keep loaded is a token the model has to read on every turn. Skills let you write long, detailed procedures without paying for them until the moment they’re used.

Progressive disclosure: the core idea

Skills work because of progressive disclosure — revealing information to the model in layers, only as deep as the current task requires:

Always in context (tiny): the skill’s name + description. This is all the model needs to decide whether a skill is relevant. A few dozen skills cost only a listing of one-liners.
Loaded when invoked (small–medium): the body of SKILL.md — the actual instructions. This enters the conversation the moment the skill is triggered.
Loaded only if the body says so (large): bundled files the SKILL.md points to — a reference.md, an API spec, example outputs — plus scripts the agent can execute without reading into context at all.

Because of layer 3, a skill can bundle a 2,000-line reference document or a Python script and pay almost nothing for it until the task actually needs it. That’s what makes skills scale: you can install dozens without bloating every conversation.

How AGENTS.md is different (and complementary)

AGENTS.md is not a skill and does not use progressive disclosure. It’s a single plain-Markdown file at a repo’s root that tells any coding agent the things it needs to know to work in that specific repository: how to install dependencies, how to run the build and tests, the coding conventions, and the rules for commits and pull requests. It’s “a README, but written for the agent instead of the human.”

The division of labor is clean:

AGENTS.md answers “how does this repo work?” It’s per-project, it lives in the repo, and it’s read by a broad ecosystem of tools. There’s no frontmatter and no required schema — just headings that make sense.
Skills answer “how do I do this task?” They’re reusable playbooks that travel with you (personal skills) or ship as a package/plugin, and they load only when their task comes up.

A concrete example. Say you maintain a TypeScript monorepo:

Your AGENTS.md tells the agent: use pnpm, run pnpm turbo run test --filter <pkg>, prefix PR titles with [<package>], never touch generated files. This is true for anyone working in this repo, always.
A changelog skill in your personal skills folder tells the agent your personal, cross-project procedure for writing a changelog entry — the tone, the format, the “group by user-facing impact” rule. You want this in every repo you touch, so it doesn’t belong in any one repo’s AGENTS.md.

They compose: when the agent works in your monorepo, it reads AGENTS.md for repo facts, and when you ask it to write a changelog, it loads the changelog skill for the procedure.

When to use which

Use this quick test:

Is it a fact or rule specific to one repository? → put it in that repo’s AGENTS.md (or a nested one — see the AGENTS.md deep-dive).
Is it a procedure or capability you’d want in more than one project, or one that’s long enough to bloat your context if always loaded? → make it a skill.
Is it a short, universal fact about you (not a repo)? → that’s what a personal memory file (e.g. CLAUDE.md) is for; skills are for procedures, not one-line preferences.

Rule of thumb: AGENTS.md is where the agent looks; skills are what the agent picks up. One describes the workspace, the other extends the worker.

Where to go next

SKILL.md files — frontmatter fields, directory layout, bundled scripts, invocation control, and full examples.
AGENTS.md files — the open standard, recommended sections, monorepo nesting, and a complete example file.

References

Verified July 2026 against official sources: