SKILL.md vs AGENTS.md: Which File Does What and When

AGENTS.md is a single file of standing project guidance that a coding agent reads at the start of every session, while SKILL.md is the main file of a skill: a packaged job your agent loads only when a task calls for it. Put rules that apply to almost every task in AGENTS.md. Put long, occasional workflows in a skill.

If you searched for "SKILL.md vs agent.md", the file is spelled AGENTS.md, plural and in capitals. All facts below were checked on 12 November 2026 against the AGENTS.md site, the Agent Skills specification, and the Claude Code and Codex docs linked in each section.

SKILL.md vs AGENTS.md at a glance

	AGENTS.md	SKILL.md
What it is	A plain Markdown file of project instructions, "a README for agents"	The required file inside a skill folder, with YAML frontmatter and instructions
When it loads	At session start, every session	Only its name and description at startup. The body loads when the skill is used
Where it lives	Repository root, plus nested folders for local rules	Its own folder, such as .claude/skills/<name>/ or .agents/skills/<name>/
Required fields	None. Any Markdown works	name and description
Can bundle files	No	Yes: scripts/, references/ and assets/
Best for	Build and test commands, code style, project conventions	Repeatable jobs: a release checklist, a PDF workflow, a review routine
Context cost	All of it, all the time	About 100 tokens per skill until it is used
Who reads it	Codex, Cursor, Gemini CLI, Jules, Zed, VS Code and others listed on agents.md	Claude, Claude Code, Codex and other clients that follow the open spec

What AGENTS.md is

AGENTS.md is an open format for guiding coding agents. The AGENTS.md site describes it as "a README for agents" and says over 60,000 open-source projects use it (the site's own figure, as of November 2026). README.md stays focused on humans. AGENTS.md holds the build steps, tests and conventions an agent needs.

The site says AGENTS.md "is now stewarded by the Agentic AI Foundation under the Linux Foundation" (see aaif.io). Agents read the nearest AGENTS.md in the directory tree, so a monorepo can give each package its own file. When instructions conflict, the agents.md FAQ says the file closest to the edited file wins, and explicit user prompts override everything.

There are no required fields. A typical file, quoted from agents.md:

# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons

How Codex reads AGENTS.md

According to the Codex docs, Codex builds an instruction chain once per run:

1. It reads ~/.codex/AGENTS.override.md, or ~/.codex/AGENTS.md if there is no override.
2. It walks from the project root down to your current folder, taking at most one file per folder.
3. Files closer to where you are appear later, so they win.
4. It stops adding files once the combined size reaches project_doc_max_bytes, which is 32 KiB by default.

That last point matters: a very long AGENTS.md gets cut off.

How Claude Code reads AGENTS.md

Claude Code's own file is CLAUDE.md. According to the Claude Code memory docs, it reads AGENTS.md only when there is no CLAUDE.md in your working folder or above it. If you have both, Claude Code reads the CLAUDE.md and skips AGENTS.md. Your personal ~/.claude/CLAUDE.md does not count for that check.

So if your team uses several agents, keep shared rules in AGENTS.md and avoid a project CLAUDE.md that hides it. Alternatively, point one file at the other.

What SKILL.md is

A skill is a folder, and SKILL.md is the one file it must contain. For how skills are discovered, loaded and shared across tools, see our complete guide to agent skills. The Agent Skills specification, published by the open Agent Skills project, sets the format:

skill-name/
├── SKILL.md          Required: metadata + instructions
├── scripts/          Optional: executable code
├── references/       Optional: documentation
└── assets/           Optional: templates, resources

A minimal SKILL.md

This example follows the spec. Only name and description are required:

---
name: release-checklist
description: Runs the release checklist for this repo. Use when the user asks to cut, tag or publish a release.
---

# Release checklist

1. Run the full test suite and stop if anything fails.
2. Update CHANGELOG.md with the changes since the last tag.
3. Bump the version, then tag and push.

For the changelog format, see [references/CHANGELOG-STYLE.md](references/CHANGELOG-STYLE.md).

The spec's rules for the two required fields:

• name: 1 to 64 characters, lowercase letters, numbers and hyphens, with no leading, trailing or double hyphens.
• description: 1 to 1024 characters. It should say what the skill does and when to use it, because the agent decides to load the skill from this line alone.

For every optional field, size budget and more SKILL.md examples, see our SKILL.md format guide.

SKILL.md meaning: why it loads in stages

"Progressive disclosure" is the core idea. The spec and Anthropic's skills overview describe three levels:

Level	What loads	When	Rough cost
1. Metadata	name and description	At startup, for every skill	About 100 tokens per skill
2. Instructions	The SKILL.md body	When the skill is used	Under 5,000 tokens recommended
3. Resources	Files in scripts/, references/, assets/	Only if the instructions need them	Only what is read

That is why you can install many skills without filling the context window, and also why a skill can be skipped: if its description doesn't match the request, its instructions never load.

Where skills live

• Claude Code: ~/.claude/skills/ for personal skills, .claude/skills/ for a project (Claude docs).
• Codex: .agents/skills in every folder from where you start Codex up to the repository root, plus user and system locations (Codex docs). Codex's starting list of skills is capped at about 2% of the context window by default.

What the evidence says about which works better

In January 2026, Vercel published an eval comparing the two on Next.js 16 APIs that models had not seen in training:

Setup	Pass rate (Vercel's figures)
No docs	53%
Docs as a skill, default behaviour	53%
Docs as a skill, plus an instruction to use it	79%
Compressed 8KB docs index in AGENTS.md	100%

The cause, in Vercel's words, was that in 56% of cases the skill was never invoked. The agent had the documentation and did not load it.

Two cautions. This is one vendor's eval on its own tasks and setup, so run your own before restructuring a large project. And it tested general framework knowledge, which is exactly the always-relevant content AGENTS.md is meant for. It doesn't show that skills are worse for bounded, repeatable jobs.

Which file should you write?

If the guidance is...	Put it in
Needed on almost every task (build, test, lint, style)	AGENTS.md
Short and about this repo only	AGENTS.md
A long workflow used now and then	A skill
Something you want to reuse across many repos	A skill, in your personal skills folder
Backed by a script or reference files	A skill
Knowledge the agent keeps missing when it is in a skill	AGENTS.md, or a pointer to the skill from AGENTS.md

A practical pattern from the Vercel results: keep AGENTS.md short, and add one line telling the agent when to use each important skill. That raised their skill trigger rate to over 95%.

How to use AGENTS.md and skills together

Most repos that use skills also need an AGENTS.md. The AWS Builder article AGENTS.md vs Agent Skills describes a repo with a React frontend and a Python backend that uses both. Its layout looks like this:

my-app/
├── AGENTS.md                         Architecture, install and test commands
├── frontend/
├── backend/
└── .agents/skills/
    ├── code-review/
    │   └── SKILL.md                  The detailed review process
    └── database-migration-review/
        └── SKILL.md                  Schema changes, data integrity, rollback

AGENTS.md stays short and always applies. The two skills load only when someone asks for a review or touches a migration. Following the Vercel finding above, add one line to AGENTS.md naming each skill and when to use it, such as "For schema changes, use the database-migration-review skill."

Common mistakes

The AWS article lists four mistakes, and each one maps to a rule in this post:

Mistake	Why it hurts	Fix
Putting everything in AGENTS.md	Every line costs context in every session, and Codex stops reading at 32 KiB by default	Move long, occasional procedures into skills
Skills with hidden assumptions	The skill fails in a repo with a different layout or missing tools	State prerequisites in the body or the compatibility field
The same procedure in both files	Copies drift apart and give conflicting instructions	Keep each rule in one place and point to it
Assuming every tool reads both	Claude Code skips AGENTS.md when a CLAUDE.md exists, and not every agent loads skills	Check each tool's docs and test that it picks up both files

Does every tool read SKILL.md the same way?

The Agent Skills specification is an open format, and the core is shared: a folder, a SKILL.md with name and description, and optional bundled files. Clients add their own extras. Claude Code supports extra frontmatter fields, and Codex reads .agents/skills folders. A skill that sticks to the spec's required fields travels best between tools.

Before installing someone else's skill, remember that its scripts run on your machine. Read SKILL.md and any scripts first. Our guide on what agent skills are covers the risks, and our skill-writing guide walks through building one.

FAQ

What is the difference between SKILL.md and AGENTS.md?

AGENTS.md is project guidance a coding agent reads at the start of every session. SKILL.md is the main file of a skill, which the agent loads only when a task matches its description. Use AGENTS.md for always-on rules and skills for occasional, repeatable jobs.

Is it agent.md or AGENTS.md?

The format is AGENTS.md, plural and in capitals, as documented on agents.md. Tools look for that exact name, so a file called agent.md will usually be ignored.

What does SKILL.md mean?

SKILL.md is the required file in an agent skill folder. Its YAML frontmatter gives the skill a name and a description, and its body holds the instructions the agent follows once it uses the skill.

Can I use both AGENTS.md and skills together?

Yes, and most projects should. Keep always-on rules such as build, test and style commands in AGENTS.md, put long or occasional workflows in skills, and add a line to AGENTS.md saying when to use each skill.

Who maintains AGENTS.md?

According to agents.md, the format is stewarded by the Agentic AI Foundation under the Linux Foundation. The Agent Skills specification is a separate open format published at agentskills.io.

Does Claude Code read AGENTS.md?

Yes, but only when there is no CLAUDE.md in your working folder or above it. If a project has both, Claude Code reads CLAUDE.md instead.

List your skill

Built a skill others could use? List it free now on AgenticMart, paid selling opens soon. Any listing can get a free automated scan; each listing page shows its scan status. List your skill, or browse the agent skills directory.