What AGENTS.md, SKILL.md, and CLAUDE.md do differently, and how to use them without wasting tokens https://t.co/knGdUUhdKs

Context Engineering & Understanding AGENTS.md & SKILLS.md & CLAUDE.md

The .md Files Quietly Running the LLM World

If you have spent any time building with AI coding agents in 2026, you have probably noticed a strange pattern. Every tool wants its own Markdown file sitting at the root of your repository. CLAUDE.md, AGENTS.md, SKILL.md, .cursorrules, .windsurfrules, copilot-instructions.md. It looks like clutter, but each of these files solves a real problem, and understanding the differences will save you from duplicating context five different ways.

These files exist because LLM agents do not know your codebase the way a human teammate does. A new engineer reads your README, asks a few questions, and picks up conventions by osmosis. An agent has none of that. It needs explicit, written-down context every time it starts a session, and Markdown became the natural format because it is plain text, diffable, and readable by both humans and models.

AGENTS.md: the universal context file

AGENTS.md has emerged as the closest thing the industry has to a shared standard. It now sits under the Agentic AI Foundation, the same governance model that oversees MCP, and is read by more than thirty different agent tools across over sixty thousand repositories. The idea is simple: one canonical file per repo, containing build commands, test commands, code style, and constraints the agent must follow.

What makes AGENTS.md interesting is the research behind how to write it well. Studies cited by tool vendors this year found that architectural overviews barely help agents, while exact commands, version constraints, and explicit “done” criteria measurably reduce errors. Vague instructions like “where possible” or “ensure comprehensive coverage” get ignored, because agents need operational policy, not prose written for humans.

There is also a cautionary finding worth remembering. Letting an LLM generate your AGENTS.md file for you tends to backfire. Research from earlier this year showed generated files reduced task success rates and increased cost, mostly because they repeated information the agent could already infer from the repo itself. A short, human-edited file beats a long, AI-written one.

SKILL.md: capability, not project context

Where AGENTS.md describes a project, SKILL.md describes a capability. A skill is a folder containing a SKILL.md file plus optional scripts, references, and assets, and it is meant to be portable across Claude Code, Codex, Copilot, and other compatible agents.

The clever part is progressive disclosure. At the start of a session, the agent only reads the skill’s name and description from the YAML frontmatter. It loads the full body only when a task actually matches that skill’s domain, and any supplementary scripts or reference docs load later still. This keeps the agent’s context window lean instead of front-loading every possible instruction it might never need.

For anyone maintaining a library of reusable prompts or workflows, this is the more natural home than cramming everything into one giant AGENTS.md. It also explains why marketplaces like skills.sh have taken off, since a skill is just a folder with Markdown in it, which makes it trivially easy to publish and install.

CLAUDE.md and the tool-specific files

CLAUDE.md, .cursorrules, .windsurfrules, and copilot-instructions.md are the tool-specific cousins of AGENTS.md. Each editor or agent originally invented its own convention before the industry converged on a shared standard, and most of them are still honored today for backward compatibility.

The practical pattern that has emerged, and one worth adopting if you maintain multiple tools across a team, is to treat AGENTS.md as the single source of truth and generate the tool-specific files from it. That avoids the classic failure mode of updating one file and forgetting the other four, which quietly reintroduces the exact context drift these files were meant to prevent.

DESIGN.md & Newer entrants worth watching

A few more specialized formats are starting to appear alongside these. DESIGN.md, for instance, is used to encode a project’s visual identity system, combining machine-readable design tokens with human-readable rationale, so an agent generating UI code understands not just the color values but why they were chosen. It is early, but it signals where this pattern is heading: narrow, purpose-built Markdown files for specific slices of context, rather than one file trying to do everything.

Context Engineering: The Real Reason These Files Exist

None of this is really about Markdown. It is about the fact that agent reliability depends heavily on the quality of the context it is given, and Markdown happened to be the lowest-friction format everyone could agree on. The files differ in scope. AGENTS.md covers the project, SKILL.md covers a capability, and the tool-specific files exist mostly for compatibility.

Underneath the novelty, what you are actually doing when you write one of these files is context engineering. That is the practice of deciding what an LLM sees, when it sees it, and in what form, so it can act well without wasting tokens on things it did not need. Treat every file below as a lever for that, not just a formality your tooling expects.

How to Use AGENTS.md and SKILL.md Files ?

Start with AGENTS.md, and resist the urge to make it comprehensive. Every sentence in this file gets read on every session, so it is pure recurring token cost. Write exact commands instead of prose descriptions, state constraints instead of architecture explanations, and delete anything the agent could infer from the repo itself, since research shows those sections do not improve outcomes and only inflate the bill.

A few concrete moves make a measurable difference here.

• Replace “run the tests appropriately” with the literal command and flags, so the agent does not burn a turn discovering it

• Cut any “Architecture Overview” section and keep only non-standard patterns and files the agent should never touch

• Add explicit “done” criteria for common tasks, since ambiguity is what causes agents to over-explore and re-read files

• Never let an agent generate this file unsupervised; edit it yourself or trim aggressively afterward

Move to SKILL.md once your AGENTS.md starts accumulating capability-specific instructions that only apply to certain tasks, like deployment steps or a niche internal API. This is where progressive disclosure does the real work for your token budget.

The agent only pays the cost of the frontmatter description at session start, and loads the full skill body only when a task actually matches it, so ten skills sitting unused cost you almost nothing.

To get that benefit in practice, keep skill descriptions tight and specific enough that the agent can match them correctly without opening the file, since a vague description forces it to load the body just to check relevance, which defeats the purpose.

Reserve SKILL.md for capabilities you invoke occasionally rather than constraints you need every session, since those belong in AGENTS.md instead.

For the tool-specific files, CLAUDE.md, .cursorrules, .windsurfrules, and copilot-instructions.md, stop writing them by hand entirely. Maintain AGENTS.md as the single source of truth and generate the others from it with a short sync script.

This is not primarily a token optimization, it is a correctness one, since divergent files are what quietly reintroduce the exact ambiguity these files exist to remove.

Finally, treat all of these files the way you treat code. Review them in the same pull request as the change they describe, delete stale sections the moment they stop being true, and periodically audit for content that has migrated into the codebase itself and no longer needs to be restated. A lean, accurate file that gets read correctly every time will outperform a thorough one that gets skimmed, ignored, or contradicted by the code around it.

The teams getting real value out of these files in 2026 are not the ones with the most detailed AGENTS.md. They are the ones treating context engineering as an ongoing discipline, where every file earns its place in the token budget or gets cut.