The file every agent reads vs the folders it reads sometimes
AGENTS.md and Agent Skills solve a problem that looks similar from a distance (both put instructions in front of an agent) but they sit at opposite ends of a cost curve. One file loads on every single request, whether it's relevant or not. Skills load only when something matches. Confusing the two leads to two failure modes: a bloated AGENTS.md that taxes every request, or project conventions buried in a skill the agent never happens to load. AGENTS.md isn't the only other mechanism worth distinguishing from a skill. See Agent Skills vs MCP and Agent Skills vs Subagents for the other two comparisons that come up just as often.
What AGENTS.md is for
AGENTS.md. Claude Code reads the equivalent CLAUDE.md. Is a single file at the repo root. It's always loaded: every session, every request, regardless of what the user asked for. That's the entire value proposition: the agent doesn't need to guess whether it's relevant, because it's already there.
That's also the entire cost. Because it's loaded every time, whatever you put in AGENTS.md is context tax on every single request in that repo, whether the request needs it or not. This is why the guidance is blunt: it should stay short. It's the right home for facts that are true of every task in this repo. Build commands, architecture notes, naming conventions, which directories are off-limits.
What skills are for
A skill is the opposite shape: many folders, each loaded conditionally. At session start the agent reads only a skill's name and description. Cheap enough that having a hundred installed skills costs barely anything if none of them match the current request. Only when a request matches a skill's description does the agent load the full SKILL.md body.
Skills also aren't tied to one repository. They encode reusable procedure (how to write a database migration, how your team formats a changelog, how to run a specific kind of audit) independent of which project you're currently in. The same skill folder can sit in ~/.claude/skills/ and apply across every repo you touch, or live inside one project at .claude/skills/ if it's specific to that codebase. See the platforms page for the exact paths per agent.
Always-loaded vs conditionally-loaded
| AGENTS.md / CLAUDE.md | Agent Skills | |
|---|---|---|
| When it loads | Every session, every request | Only when a request matches a skill's description |
| Context cost | Paid on every request, relevant or not | Near-zero at idle; full cost only when triggered |
| Scope | This one repository | Reusable across repos, or scoped to one project |
| What it holds | Facts that are always true here — conventions, commands, architecture | Procedures that matter sometimes — a specific task done a specific way |
| Ideal length | Short — a page, not a manual | As long as the procedure needs, since it only loads on match |
| Number per project | One | As many as you need |
Worked example: a real repo with both
Consider a Next.js project with a database migration convention and a separate, occasional need for writing onboarding emails in the company's voice.
project/
├── AGENTS.md
└── .claude/skills/
├── db-migration/
│ └── SKILL.md
└── onboarding-email/
└── SKILL.md
AGENTS.md, short, always relevant to anyone working in this repo:
# project
Next.js 15 app. Package manager: pnpm.
## Commands
- pnpm dev: local dev server
- pnpm test: run the test suite
- pnpm build: production build, run before any deploy
## Conventions
- API routes live in app/api/, one folder per route.
- Database access goes through lib/db.ts. Never instantiate a client elsewhere.
- Migrations use the db-migration skill. Do not hand-write SQL migrations.
db-migration/SKILL.md, only loads when someone is actually adding a migration, which is most sessions in this repo but not all:
---
name: db-migration
description: Use when the user asks to add, modify, or run a database migration in this project.
---
# Database Migrations
1. Generate a new migration file with the project's migration tool.
2. Write the up step first, then a matching down step. Never ship a migration without one.
3. Run it against the local dev database before committing.
4. Never edit a migration that's already been merged. Write a new one instead.
onboarding-email/SKILL.md, rarely needed, and nothing about it belongs in the always-loaded file:
---
name: onboarding-email
description: Use when drafting a welcome or onboarding email to a new user or customer.
---
# Onboarding Email Voice
Short paragraphs. No exclamation marks. Lead with what the reader should do next, not with the product story.
Notice what AGENTS.md does: it states the migration convention exists and points at the skill, without embedding the actual migration steps. That's the practical split in miniature, the always-loaded file carries the fact that a convention exists; the skill carries the procedure for following it.
Now compare what happens without that line in AGENTS.md at all. An agent asked to "add a column to the users table" has no way to know a db-migration skill exists unless the request itself happens to phrase things the way the skill's description expects. It might just as easily hand-write a raw SQL migration, skip the down step, and never touch the local dev database first, technically a working change, but one that breaks the convention the team actually relies on. The one-line pointer in AGENTS.md is what closes that gap: it doesn't duplicate the procedure, it just makes sure the agent knows the procedure exists before it improvises one.
Multi-repo teams and shared skills
The split gets more interesting once you're working across more than one repository. AGENTS.md is inherently per-repo. It describes this codebase, so it can't be shared wholesale across projects without becoming generic to the point of uselessness. Skills don't have that constraint. A skill installed globally at ~/.claude/skills/ applies everywhere you work, independent of which repo you're in, which is exactly why procedures like "how we write commit messages" or "how we structure a design doc" are better encoded as skills than copy-pasted into every project's AGENTS.md.
The practical pattern for a team with several repos: keep each AGENTS.md short and specific to that one codebase (its commands, its architecture, its local conventions) and push anything that should be consistent across every project the team touches into a shared, globally installed skill. That way a change to "how we do code review" is one skill update, not an edit to every repo's AGENTS.md.
The practical split
Put a fact in AGENTS.md if it's true for essentially every task in the repo: the package manager, the test command, where things live, which patterns are forbidden. Put a procedure in a skill if it only matters for specific kinds of requests: how to do a migration, how to write a certain document, how to run a particular audit.
The failure mode in each direction is different. Cram everything into AGENTS.md (every possible procedure, every edge case) and every request in the repo pays for context it usually doesn't need. That's the bloat the standard guidance warns against. Push a project-wide convention into a skill instead, and the agent might simply never load it, because it only loads on a description match, and a general "make some changes" request may not obviously match "use the db-migration skill."
What goes wrong when you get it backwards
A repo where AGENTS.md has ballooned into a full engineering handbook is the most common failure. Every session pays the tax of loading paragraphs about a testing convention that only mattered for last quarter's project, or a deploy runbook that fires twice a year. The fix isn't deleting the content. It's moving the occasional-use parts into skills and leaving only the always-true parts in AGENTS.md.
The opposite failure is subtler: a core convention, "always use lib/db.ts, never instantiate a database client directly". Gets written as a skill instead of stated in AGENTS.md. Because it's only loaded on a description match, and a generic coding request doesn't obviously match "database client instantiation," the agent skips it entirely on requests where it actually applies. Anything that should apply to every task belongs in the always-loaded file, full stop.
Which should you use, decision criteria
Ask: is this true of nearly every task in this repo, or only some of them?
- Nearly every task → AGENTS.md. Keep it short, commands, conventions, architecture, pointers to relevant skills.
- Only some tasks → a skill. Give it a description that names the concrete situations where it applies.
- True everywhere, but detailed and rarely all needed at once → a short pointer in AGENTS.md, with the detail pushed into a skill's
references/folder that loads on demand.
Troubleshooting: when a convention or skill gets missed
The agent ignores a convention that's in AGENTS.md. Check that AGENTS.md is actually at the repo root and being picked up. Some agents also read a CLAUDE.md variant, so confirm which file your specific agent expects.
A skill never activates even though it's clearly relevant. The description is almost always the problem. See the guide to how agents discover and activate skills for what a triggering description looks like.
AGENTS.md keeps growing. Treat that growth as a signal, not a fact of life. Anything in there that only applies to some tasks is a candidate to move into a skill.
A convention is duplicated in both places and has drifted. Pick one home for it. If it's universal, it belongs in AGENTS.md and the skill should just reference it. If it's task-specific, delete it from AGENTS.md and let the skill own it.
Two skills seem to overlap with each other, or with something in AGENTS.md. Overlap usually means one of them is scoped too broadly. Narrow the descriptions so each skill's triggering situation is distinct, and make sure AGENTS.md only ever states facts, not procedures a skill already owns. See how agents discover and activate skills for how description matching actually works, since that's what determines whether a skill fires at all.
Why both, and not one or the other
It's tempting to treat this as a decision to make once and move on. "we're an AGENTS.md shop" or "we do everything as skills." Neither holds up. AGENTS.md can't scale to cover every procedure without becoming the exact bloat problem it's meant to avoid. Skills can't guarantee a convention is seen on every request, because they're conditional by design. The two are complementary by construction, and most serious setups use both: a short, stable AGENTS.md for what's always true, and a growing library of skills for everything that's true sometimes. For the mechanics of exactly when a skill's description gets matched against a request, see how agents discover and activate skills. Browse what other teams have already written at getclaudeskills.com/skills, filtered by category if you know what you're after.
