AGENTS.md is always-on project context: coding agents read it before they start work, so everything in it is in context every session. Skills are on-demand: the agent sees only each skill's name and description, and loads the full SKILL.md when a task matches or you call it by name.
The rule that follows is simple. Put facts every task needs in AGENTS.md, and put procedures and reference material that only some tasks need in skills. This guide compares the two, looks at what Vercel's widely shared eval found, and shows how to use both without repeating yourself. Product details were checked against official docs on 28 October 2026.
What is the difference between AGENTS.md and skills?
They load differently, and that one difference drives everything else.
| AGENTS.md | Skills | |
|---|---|---|
| What it is | One Markdown file of project instructions | A folder with SKILL.md plus optional scripts, references and assets |
| When it loads | Before any work, every session | Name and description up front; full body when used |
| Who decides | Nobody: it is always there | The agent matches the description, or you invoke it |
| Context cost | Full file, every session | A short listing entry every turn; body only when used |
| Format | Plain Markdown, no required fields | YAML frontmatter with name and description, then Markdown |
| Bundles scripts | No | Yes, inside the skill folder |
| Best for | Build and test commands, conventions, project layout | Multi-step workflows, reference docs, tasks with side effects |
| Standard | agents.md | Agent Skills |
The AGENTS.md site describes it as "a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project." OpenAI's Codex docs say "Codex reads AGENTS.md files before doing any work."
Skills work the other way. OpenAI's skills docs explain: "ChatGPT and Codex start with each skill's name and description, then load the full SKILL.md instructions when they decide to use that skill." Claude Code's skills docs put the trade-off plainly: "Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it."
For the background on each format, see the AGENTS.md guide and the Agent Skills guide.
What did Vercel's eval find, and what are its limits?
Vercel's post AGENTS.md outperforms skills in our agent evals (27 January 2026, by Jude Gao) tested how to teach coding agents Next.js 16 APIs that aren't in model training data, such as 'use cache', connection() and forbidden().
Its final pass rates on a hardened eval suite:
| Configuration | Pass rate |
|---|---|
| Baseline, no docs | 53% |
| Skill, default behavior | 53% |
| Skill with explicit instructions in AGENTS.md | 79% |
| AGENTS.md docs index | 100% |
The key finding was about triggering: "In 56% of eval cases, the skill was never invoked." Adding an instruction to AGENTS.md to use the skill raised the trigger rate to over 95%, but the wording mattered. "You MUST invoke the skill" made the agent anchor on the docs and miss project context, while "Explore project first, then invoke skill" did better.
The winning setup was not full documentation pasted into AGENTS.md. It was a compressed index, cut from about 40KB to 8KB, that tells the agent where version-matched doc files live so it can read them as needed.
Read the result with its scope in mind:
- One kind of knowledge. It measured general framework knowledge that applies to almost every task, which is exactly what always-on context is for.
- One framework, one vendor's suite. The tests covered Next.js APIs, built and run by Vercel.
- Vercel's own caveat. The post says "Skills aren't useless" and that skills "work better for vertical, action-specific workflows that users explicitly trigger," such as upgrading Next.js or migrating to the App Router. It calls the two approaches complementary.
The lesson to take: if an agent must know something on every task, don't make it depend on a decision to load a skill.
What belongs in AGENTS.md?
Facts the agent needs no matter what it is doing. The AGENTS.md site lists popular sections: project overview, build and test commands, code style guidelines, testing instructions and security considerations.
Keep it short, because every line costs context on every turn:
- Claude Code's memory docs recommend keeping it to "facts Claude should hold in every session" and targeting "under 200 lines per CLAUDE.md file," noting that longer files "consume more context and reduce adherence."
- Codex stops adding instruction files once the combined size reaches
project_doc_max_bytes, 32 KiB by default. - In a monorepo, use nested AGENTS.md files. Codex concatenates them from the root down, so the file closest to your working directory appears last and overrides earlier guidance.
When should something be a skill instead?
Move content into a skill when it is a procedure rather than a fact, or when only some tasks need it. Claude Code's docs suggest creating a skill "when a section of CLAUDE.md has grown into a procedure rather than a fact."
Good candidates:
- Multi-step workflows such as a release checklist, a database migration or a PR review routine.
- Long reference material such as API docs or a style guide that matters only for certain files.
- Tasks with side effects. In Claude Code,
disable-model-invocation: truemeans only you can trigger the skill, so the agent won't decide to deploy because the code looks ready. - Workflows with scripts. A skill folder can bundle scripts and templates; AGENTS.md cannot.
Skills are not free either. In Claude Code the skill listing is budgeted at 1% of the model's context window, and Codex limits its initial list to 2% by default. With many skills installed, descriptions get shortened, which makes triggering less reliable. If a skill isn't firing, see Claude skill not triggering.
How do you use both without repeating yourself?
Give each fact one home, and let AGENTS.md point to skills rather than copy them.
- Keep AGENTS.md as the index. State the facts every task needs, then name the skills that exist and when to use them, in one line each. Vercel's data shows this kind of instruction raises trigger rates.
- Word pointers as "explore, then use." In Vercel's eval, "Explore project first, then invoke skill" beat "You MUST invoke the skill," so write something like "After reading the relevant code, use the release-notes skill for changelog work."
- Never duplicate rules. If a rule lives in both files, they drift apart. Keep a short rule in AGENTS.md and the full procedure in the skill.
- Front-load skill descriptions. Codex advises you to "front-load the key use case and trigger words so a host can still match the skill if descriptions are shortened."
- Use hooks for hard rules. Claude Code treats both CLAUDE.md and skills as context, not enforcement. For a rule that must hold every time, its docs recommend a hook.
Kipt keeps your prompts and SKILL.md folders as Markdown in a private GitHub repo you own, and every skill in it installs into Claude Code or Codex with one npx skills add command. That leaves AGENTS.md in each project for the facts that project always needs.
Where do CLAUDE.md and Cursor rules fit?
CLAUDE.md is Claude Code's always-on file, the same role as AGENTS.md. Claude Code v2.1.277 or later reads AGENTS.md directly, but by default only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. To use both, set Project instructions to claude-md-and-agents-md, or put an @AGENTS.md import at the top of a CLAUDE.md. Claude Code also has .claude/rules/ files, which can be scoped to file paths so they load only when Claude works on matching files. The full comparison is in CLAUDE.md vs AGENTS.md.
Cursor is listed on the AGENTS.md site as one of the agents that read the format, alongside Codex, GitHub Copilot's coding agent, Gemini CLI and others. Cursor also has its own rules system; AGENTS.md vs Cursor rules compares the two.
The same split applies in every tool: a short always-on file for facts, and skills for everything an agent needs only some of the time. For where plain saved prompts fit in, read skills vs prompts.