Guides · 2026-10-15
SKILL.md vs AGENTS.md vs CLAUDE.md: What Goes Where
AGENTS.md / CLAUDE.md
Project memory files, loaded at the start of every session. Put facts here: how to run tests, folder layout, key conventions. Keep them short — every line costs context in every session.
SKILL.md
Loaded only when relevant. Put procedures here: step-by-step workflows, checklists, long reference material.
How to decide
- Needed in almost every task? → AGENTS.md / CLAUDE.md
- Needed for one kind of task? → a skill
- A section of CLAUDE.md that has grown into a procedure → move it into a skill (Claude Code's docs recommend exactly this).
Example
- CLAUDE.md: "Use pnpm. Tests: pnpm test."
- Skill
release-notes: the 6-step process for writing your changelog.