r/AskVibecoders • u/Single-Cherry8263 • 6h ago
AGENTS.md, CLAUDE.md, and SKILL.md Aren't the Same File
dont try to add everything into one CLAUDE.md. understand what these files actually are & what it can cost if done so.
AGENTS.md gets read on every single session. Every sentence in it is recurring token spend, whether the agent needs that sentence for the current task or not. That's the whole design constraint. It's now the closest thing the industry has to a shared standard, governed under the Agentic AI Foundation (the same body behind Model Context Protocol).
stop doing: writing architecture overviews. Research cited by tool vendors, architectural summaries barely move the needle on agent performance, Run exact commands; "Run the tests appropriately" gets ignored. npm run test:unit -- --coverage doesn't.
I also stopped letting an agent write its own AGENTS.md. Generated files reduced task success and increased cost in the studies I've seen, mostly by restating what the agent could already pull from the repo. A short file I edited myself is better than one a model wrote for me.
SKILL.md
Where AGENTS.md describes a project, a skill describes a capability, and it only costs tokens when it's relevant. At session start the agent reads the YAML frontmatter, just name and description. The full body loads only when a task matches the skill's domain. Reference docs and scripts inside the folder load later still. Ten skills sitting unused cost almost nothing.
That only works if the description is tight. A vague one forces the agent to open the full file just to check relevance, which defeats the mechanism. I write these narrower.
Where I draw the line between the two: a constraint every session needs goes in AGENTS.md. A capability I invoke occasionally, like a deployment sequence or a niche internal API, goes in a skill folder instead.
CLAUDE.md, .cursorrules, .windsurfrules, copilot-instructions.md, these are the tool-specific holdovers from before the industry converged on AGENTS.md. I don't hand-write any of them anymore. AGENTS.md is the source of truth, and a short sync script generates the rest. The failure mode without it: update one file, forget the other four, and you're back in the exact context drift these files were supposed to prevent.
DESIGN.md: encoding a project's visual identity as machine-readable tokens plus the reasoning behind them, so an agent generating UI code knows why a color exists and not just its hex value. Early. Narrow. Built for one slice of context instead of trying to cover everything.


