Guide
Agent Skills vs AGENTS.md
AGENTS.md and agent Skills solve different halves of the same problem: AGENTS.md is a single file every agent reads to orient itself in your repo — how to build, how to test, what the conventions are — while a Skill is an installable bundle the agent loads only when a task matches its description. Put orientation in AGENTS.md and procedures in Skills. If a section of your AGENTS.md has grown into a step-by-step playbook, that section wants to be a Skill.
Updated August 19, 2026 · first published August 19, 2026
At a glance
Side by side
| AGENTS.md | Agent Skills | |
|---|---|---|
| Unit | One markdown file at the repo root | A folder with SKILL.md plus optional scripts and docs |
| When read | Every session, unconditionally | When the task matches the description |
| Job | Orientation: build, test, layout, conventions | Procedure: how to perform a specific kind of task |
| Distribution | Committed with the repo, not installable | Installable, versionable, shareable across repos |
| Can bundle scripts | No | Yes |
| Length that stays sane | Short — it is always in context | Long — cost is only paid on trigger |
AGENTS.md is context; a Skill is capability
AGENTS.md answers questions an agent has before it does anything: which package manager, which test command, where the source lives, what not to touch. It is read every session, so its cost is constant and its length should be disciplined.
A Skill answers "how do we do this particular thing here" — run a release, review a migration, generate the monthly report. It ships with whatever it needs, including executable scripts, and it costs nothing until a task matches.
The failure mode is treating AGENTS.md as a dumping ground. A 900-line AGENTS.md is paid on every request, dilutes the instructions that matter, and cannot be reused in another repo. Splitting the playbook sections out into Skills fixes all three.
A concrete split
For a typical web app, the division that works looks like this:
- AGENTS.md
- Build and test commands, directory map, language and framework versions, house conventions, what requires human review, links to the Skills below.
- A review Skill
- The full checklist, severity definitions, and output format for a code review in this repo.
- A release Skill
- The ordered release procedure, with the scripts it runs bundled alongside it.
- A migration Skill
- Schema-change rules, the locking gotchas for your database, and the backfill pattern you have standardised on.
They are not competitors, and both are portable
AGENTS.md was adopted precisely so a repo could describe itself once to any agent rather than maintaining a file per tool. Skills have the same property at the capability layer: one SKILL.md folder that Claude Code, Codex CLI, Cursor, Gemini CLI, and Antigravity can all read.
Used together they give you a repo any agent can pick up cold — orientation from the file, procedures from the installed Skills — which is exactly the setup that makes agent work reproducible between people and between tools.
FAQ
Common questions
Do I need both AGENTS.md and Skills?
Most repos benefit from both. AGENTS.md is nearly free to add and immediately useful. Skills earn their place once you notice yourself re-explaining the same procedure — that repetition is the signal.
Can AGENTS.md point at my Skills?
Yes, and it should. A short section naming the installed Skills and when to use them helps the agent choose correctly, and helps humans discover what already exists instead of reinventing it.
Is CLAUDE.md the same as AGENTS.md?
Same idea, different filename and reader. CLAUDE.md is read by Claude Code; AGENTS.md is the vendor-neutral convention. The content guidance is identical: orientation, short, and honest about what must not be touched.
Should a Skill repeat what is in AGENTS.md?
No. Duplication means two sources of truth that drift. Let the Skill assume the orientation AGENTS.md provides and describe only the procedure.
Related
Keep reading
- How to create a Skill →
Turn a repeated instruction into an installable SKILL.md.
- Anatomy of a SKILL.md →
Frontmatter, description writing, and the three-tier loading model.
- Skill vs MCP vs plugin →
Which primitive to reach for, and why they are not substitutes.