SKILL.md vs CLAUDE.md vs AGENTS.md: What Goes Where

Every agentic coding setup eventually accumulates three kinds of markdown: CLAUDE.md, AGENTS.md, and SKILL.md. They look similar — plain-markdown instructions for an AI agent — but they load differently, cost tokens differently, and solve different problems. Getting the SKILL.md vs CLAUDE.md split wrong is the most common reason Claude Code context files balloon past the point where the agent actually follows them.

Here's the short answer: CLAUDE.md and AGENTS.md are always-on project context, read at the start of every session and carried through every turn. SKILL.md is an on-demand capability, discovered by its description and loaded only when a task needs it. If an instruction applies to every task in the repo, it belongs in CLAUDE.md or AGENTS.md. If it applies to one kind of task, it belongs in a skill.

SKILL.md vs CLAUDE.md: the one-line rule

Always-on facts go in CLAUDE.md/AGENTS.md. On-demand procedures go in SKILL.md.

Ask one question about any instruction you're about to write down: does the agent need this on every single task?

• "We use pnpm, not npm" — every task. Context file.
• "API routes return { data, error }" — every task that touches an API route, which in most repos is close to every task. Context file.
• "Here's our 40-step release checklist" — one task type, maybe once a week. Skill.
• "How to generate a database migration, with our naming conventions and the three gotchas" — one task type. Skill.

The reason this matters is mechanical, not stylistic. Always-on files are injected into the context window whole, at session start, whether or not they're relevant. A 200-line release runbook inside CLAUDE.md is 200 lines of noise on every "fix this typo" request — noise you pay for in tokens and, worse, in diluted attention. The same runbook as a SKILL.md costs roughly one sentence (its description) until the day you actually cut a release.

CLAUDE.md and AGENTS.md: always-on project context

These two files do the same job for different audiences.

CLAUDE.md

CLAUDE.md is Claude Code's project memory. Claude Code reads it when a session starts — the global ~/.claude/CLAUDE.md first, then the project-level file — and treats its contents as standing instructions for everything that follows. It's the right home for the facts an agent would otherwise have to rediscover every session:

# Project: acme-api

## Stack
- TypeScript 5.7 strict, Node 22, Fastify
- Drizzle ORM + PostgreSQL
- Vitest for tests

## Commands
- Test: pnpm test
- Type check: pnpm check
- Never run: pnpm db:push (use generated migrations)

## Conventions
- snake_case columns, camelCase everywhere else
- All handlers return { data, error }

Short, factual, universally applicable. Our complete CLAUDE.md guide covers structure and anti-patterns in depth, but the summary is: if a line wouldn't change how the agent behaves on a random task, it shouldn't be there.

AGENTS.md

AGENTS.md is the tool-agnostic version of the same idea — an open convention adopted by Codex CLI, Cursor, Gemini CLI, Zed, and a growing list of others. One file at the repo root, same job: always-on project instructions, but readable by whichever agent your teammates happen to run.

If your team is all-in on Claude Code, CLAUDE.md alone is fine. If the team is mixed — some on Cursor, some on Codex CLI, some on Claude Code — AGENTS.md becomes the canonical file and CLAUDE.md can simply defer to it. The two formats are close enough that many repos keep one as a pointer to the other; the AGENTS.md complete guide and our AGENTS.md vs CLAUDE.md comparison walk through the interop patterns.

The key point for this comparison: AGENTS.md sits on the same side of the line as CLAUDE.md. Both are always-on. Neither is the place for long procedures.

SKILL.md: on-demand capability

A skill is a folder with a SKILL.md at its root. The frontmatter carries a name and a description; the body carries the actual instructions; sibling files carry anything the procedure needs — reference docs, scripts, templates:

---
name: db-migration
description: Generate and review a Drizzle migration. Use when
  the task adds, removes, or alters database columns or tables.
---

## Steps

1. Edit the schema in src/schema/, never the SQL directly.
2. Run `pnpm db:generate` and read the generated SQL.
3. Check the three gotchas in ./gotchas.md before committing.

What makes skills different from context files is progressive disclosure. At session start, the agent sees only each skill's name and description — a line or two per skill. The full body, and any referenced files, load only when the current task matches the description. You can have thirty skills installed and pay a few hundred tokens of overhead, not thirty runbooks' worth.

That loading model changes what you can afford to write. A skill can be long, opinionated, and include worked examples, because it only costs context when it's earning its keep. It can also ship more than markdown: skills on localskills.sh are packages — a root SKILL.md plus optional docs, scripts, and templates, up to 100 MB and 500 files per version. The SKILL.md format reference covers the frontmatter fields and how to write descriptions that actually trigger.

SKILL.md vs CLAUDE.md vs AGENTS.md: the decision table

And with real instructions sorted into their homes:

The skills vs CLAUDE.md call is almost always a frequency call. When you find yourself writing a numbered list longer than five steps inside a context file, that's the signal to cut it out and make it a skill.

How the three load together at runtime

A concrete session, start to finish:

1. Session start. Claude Code reads ~/.claude/CLAUDE.md (personal preferences), then the project CLAUDE.md (or AGENTS.md, for tools that read it). These land in the context window in full.
2. Skill discovery. Installed skills contribute only their frontmatter — name and description. Thirty skills ≈ thirty sentences.
3. Task arrives. "Add a deleted_at column to the orders table." The agent matches this against skill descriptions, finds db-migration, and now reads its full body plus gotchas.md.
4. Execution. The agent works with three layers active: your always-on conventions (snake_case columns — from CLAUDE.md), the loaded procedure (generate, don't hand-write SQL — from the skill), and the task itself.
5. Next task. "Update the README." The migration skill's body is irrelevant and never loads; only its one-line description was ever paid for.

Notice the division of labor: the context file made the conventions ambient, the skill made the procedure available, and neither had to do the other's job. All three are AI agent memory files in the loose sense — persistent instructions that outlive a chat session — but they're tuned for opposite ends of the frequency curve, and the runtime treats them accordingly.

One practical consequence: context files should reference skills, not inline them. A line like "for schema changes, use the db-migration skill" costs almost nothing and routes the agent to the right procedure. Pasting the procedure into CLAUDE.md costs you on every task forever.

Keeping all three organized and versioned

CLAUDE.md and AGENTS.md are easy: they're single files at the repo root, so they version with the repo. Review changes to them in PRs like any other code — they steer every agent session your team runs, which makes them higher-leverage than most source files.

Skills are where organization gets harder, because the useful ones outgrow a single repo. The same "how we write API endpoints" skill applies to a dozen services; copy-pasting .claude/skills/ folders between repos means twelve slowly-diverging copies and no way to roll back a bad edit.

That's the problem a registry solves. On localskills.sh, skills are published as versioned packages with rollback, organized into org folders with access controls, and installed by name:

localskills install acme/backend/db-migration --target claude cursor windsurf

One published skill, and the CLI writes each tool's native format — .claude/skills/ for Claude Code, .cursor/rules (.mdc) for Cursor, .windsurf/rules/ for Windsurf — so a mixed-tool team maintains one source of truth instead of four. Orgs that live in GitHub can mirror their whole skill library to a repo with bidirectional sync: edits merged in the repo come back as new skill versions.

However you host them, the versioning rule mirrors the loading rule: context files version with the project, skills version as the product they are.

FAQ

Can a repo have both CLAUDE.md and AGENTS.md?

Yes, and mixed-tool teams usually should. Keep AGENTS.md as the canonical always-on file and have CLAUDE.md defer to it (or hold only Claude-Code-specific additions). Duplicating full content in both guarantees drift.

Should I move parts of my CLAUDE.md into skills?

If your CLAUDE.md has grown past a screenful, almost certainly. Anything shaped like a procedure — numbered steps, a checklist, a workflow for one task type — moves to a SKILL.md and gets replaced by a one-line pointer. Facts, conventions, and boundaries stay.

Does SKILL.md work outside Claude Code?

The SKILL.md format is native to Claude Code, but the capability it packages isn't Claude-specific. Publishing a skill to localskills.sh and installing with multiple targets writes tool-native rule formats for Cursor, Windsurf, GitHub Copilot, Cline, and others from the same source package.

What's the difference between AGENTS.md and CLAUDE.md?

Audience, mostly: CLAUDE.md is read by Claude Code, AGENTS.md is a cross-tool convention read by Codex CLI, Cursor, Gemini CLI, and others. Content-wise they carry the same kind of always-on instructions — the AGENTS.md vs CLAUDE.md breakdown covers when to keep one, the other, or both.

How many skills is too many?

Skills are cheap at rest — only descriptions load until triggered — so the ceiling is discoverability, not tokens. The real failure mode is vague descriptions that never match tasks. Write descriptions that name the trigger ("use when the task alters database tables"), and a large library stays usable.

---

Ready to move your procedures out of your context files? Create a free localskills.sh account and publish your first skill in a couple of minutes.

npm install -g @localskills/cli
localskills login
localskills publish