--- title: Agent Skills vs AGENTS.md slug: skills-vs-agents-md type: guide targetQuery: skills vs AGENTS.md canonical: https://top-agent-skills.com/guides/skills-vs-agents-md published: 2026-08-19 updated: 2026-08-19 --- # 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. ## AGENTS.md vs agent Skills | | 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. ## 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 - [How to create a Skill](https://top-agent-skills.com/guides/how-to-create-a-skill) — Turn a repeated instruction into an installable SKILL.md. - [Anatomy of a SKILL.md](https://top-agent-skills.com/guides/anatomy-of-a-skill-md) — Frontmatter, description writing, and the three-tier loading model. - [Skill vs MCP vs plugin](https://top-agent-skills.com/guides/skill-vs-mcp-vs-plugin) — Which primitive to reach for, and why they are not substitutes. --- _Top Agent Skills. Machine-readable twin of https://top-agent-skills.com/guides/skills-vs-agents-md._ _Catalog as one JSON file (CC BY 4.0): https://top-agent-skills.com/skills.json_