SKILL.md vs AGENTS.md vs CLAUDE.md
SKILL.md is a procedure: a named, triggerable capability. AGENTS.md and CLAUDE.md are identity: persistent project context loaded every session. Use AGENTS.md for runtime-agnostic conventions, CLAUDE.md for Claude Code specifics, and SKILL.md for any workflow you want performed the same way every time.
Key takeaways
- One line settles most confusion: procedure versus identity. Skills do; instruction files are.
- Instruction files fail as re-derived context and wrong guesses; missing skills fail as quality variance across operators.
- Cursor rules straddle both layers: always-on rules are identity, glob-scoped rules behave like lightweight skills.
- A healthy repo uses both layers deliberately: AGENTS.md or CLAUDE.md for context, a skills directory for procedures.
- Codex instructions are AGENTS.md by another runtime; the concepts transfer directly.
The one-line answer
Procedure versus identity. A SKILL.md does: it is a named, triggerable procedure for one class of work. AGENTS.md and CLAUDE.md are: persistent identity and context, loaded every session. Once you hold that line, every placement question answers itself.
The comparison
| SKILL.md | AGENTS.md | CLAUDE.md | Cursor rules | |
|---|---|---|---|---|
| Layer | Skill (procedure) | Identity (context) | Identity (context) | Both |
| Loads | When triggered or invoked | Every session | Every session (Claude Code) | Always-on, or per file-glob |
| Scope | One class of work | Whole project, any runtime | Whole project, Claude Code | Whole project or glob |
| Contains | Steps, triggers, verification, boundaries | Commands, conventions, map, constraints | Same, plus gotchas and decisions | Rules with rationale |
| Fails without it | Quality varies by operator | Re-derived or guessed context | Same, for Claude Code | Same, for Cursor |
| Runtime support | Claude-family and growing | Broadly read across runtimes | Claude Code | Cursor |
Where a given instruction belongs
Ask three questions, in order:
- Is it a fact or standing rule? ("Tests run with
make test", "never commit to main.") Instruction file: AGENTS.md if multiple runtimes touch the repo, CLAUDE.md if it is Claude-specific. - Is it a multi-step workflow with verification? ("How we review a PR", "how we ship.") A skill. If it should fire automatically, give it a trigger-shaped description; if it is high-stakes, make it a slash command.
- Does it apply only when certain files are touched? In Cursor, a glob-scoped rule; elsewhere, a skill with the file-shape in its trigger.
The classic misplacements both come from skipping question 2. Procedures stuffed into CLAUDE.md bloat every session's context with steps that apply to one task in fifty. Skills that merely restate conventions ("write clean code, follow the style guide") add trigger overhead to what should be two identity lines.
Running them together
A healthy repository uses both layers deliberately, and they compound:
- The instruction file names the conventions; skills enforce the workflows that protect them.
- A skill can assume everything the identity file establishes, which keeps skills short.
- When both AGENTS.md and CLAUDE.md exist, one is canonical (usually AGENTS.md) and the other is thin. Divergent twins are the worst configuration, because the agent trusts whichever it read.
Codex instructions, for practical purposes, are AGENTS.md by another name; the placement logic transfers unchanged.
The test
Take any line you are about to write for your agent and ask: would this line change what the agent knows or how the agent performs a task? Knowledge goes in the identity file. Performance goes in a skill. Lines that resist the question ("be careful with the database") are usually neither, and want rewriting into one or the other: a constraint ("all DB access goes through the repository layer") or a procedure (a migration skill with verification steps).
Frequently asked questions
What's the difference between SKILL.md and AGENTS.md?
SKILL.md is a triggerable procedure for one class of work; AGENTS.md is persistent project identity and context. Procedure versus identity.
Do I need both CLAUDE.md and AGENTS.md?
Keep one canonical. If multiple runtimes touch the repo, make AGENTS.md canonical and let CLAUDE.md carry only Claude-specific additions or a pointer.
When should something be a skill instead of an instruction-file line?
When it is a multi-step workflow with verification, or applies only to a class of tasks. Instruction files hold facts and standing rules; skills hold procedures.
Summary
- Topic
- SKILL.md vs AGENTS.md vs CLAUDE.md
- Definition
- Skills are triggerable procedures; AGENTS.md/CLAUDE.md are persistent identity and context files
- Best used for
- Deciding where a given instruction belongs
- Related concepts
- instruction file, agent skill, Cursor rules
- Common mistakes
- Procedures stuffed into CLAUDE.md; skills that just restate project conventions; maintaining divergent AGENTS.md and CLAUDE.md
- Recommendation
- Facts and standing rules in the instruction file; workflows with verification in skills; one canonical context file