The Essential Markdown Files for Every Project — Including Agentic Coding

Every software project accumulates documentation debt in the same predictable way. A README gets written on day one, a CONTRIBUTING file gets added when the first external contributor arrives, and then the rest is improvised. For most of software history, that was fine. The audience for these files was human, and humans are forgiving readers who can infer context.

Agentic coding has changed the calculus. AI coding agents — Claude Code, GitHub Copilot, Cursor, OpenAI Codex, and their peers — start every session with no memory of your project. They know how to write TypeScript or Python in general, but they do not know that your team uses pnpm instead of npm, that your API client never throws exceptions, or that the vendor/ directory must never be modified. Without explicit, structured guidance, they make expensive mistakes that a new human teammate would have avoided after a single onboarding conversation.

This guide covers which markdown files every project needs, what belongs in each one, and — critically — how to separate the information that should live in persistent context files from the reusable procedures that belong in skills.

The Four Essential Files

Before addressing agentic coding specifically, it is worth establishing the baseline. Every software project, regardless of size or team, benefits from four markdown files.

The first three files have been standard practice for decades. The fourth is new, and it is the one most teams are getting wrong.

AGENTS.md: The Standard That Emerged

In December 2025, the AGENTS.md format was donated to the Agentic AI Foundation (AAIF), a directed fund under the Linux Foundation — alongside Anthropic donating the Model Context Protocol and Block donating Goose. The format is now used in over 60,000 open-source repositories and is supported by OpenAI Codex, GitHub Copilot, Cursor, Amp, Jules (Google), and Factory.

Claude Code reads CLAUDE.md rather than AGENTS.md. If your repository already uses AGENTS.md for other tools, the recommended pattern is to create a CLAUDE.md that imports it:

This keeps both tools reading the same instructions without duplication.

What the Research Actually Shows

Before writing a single line of your context file, it is worth understanding what an ETH Zurich study published in early 2026 found when it evaluated context files across multiple coding agents and benchmarks.

The findings challenge two common practices.

LLM-generated context files hurt performance. In five out of eight tested settings, files generated automatically by an LLM reduced task success rates. Agents took 2.45 to 3.92 additional steps per task, and inference costs increased by 20 to 23 percent. The root cause is redundancy: LLM-generated files duplicate content that agents can already find independently in the codebase, adding token overhead without adding signal.

Human-curated files help, but only modestly. Developer-written files outperformed LLM-generated ones in all four tested agents, with a gain of roughly four percentage points on the AGENTbench benchmark. The cost increase was up to 19 percent — nearly the same overhead as LLM-generated files, but with a positive rather than negative return.

The practical implication is clear: write your context files by hand, keep them short, and include only what an agent genuinely cannot discover on its own.

What Belongs in AGENTS.md

A GitHub analysis of over 2,500 AGENTS.md files across public repositories identified six core areas that consistently improve agent behaviour. Files that cover all six land in the top tier of effectiveness.

1. Executable commands — first, with full flags

Put commands early. Agents reference them repeatedly throughout a task. Include the exact command, not just the tool name.

2. Tech stack with exact versions

"React project" is useless. "React 19 with TypeScript 5.9, Tailwind 4, and Vite" is actionable. Without version constraints, agents default to whichever API conventions are most represented in their training data — which may be two major versions behind.

3. Non-standard tooling choices

This is where context files deliver the highest return on investment. If your project uses pixi instead of pip, pnpm instead of npm, or a custom API client that never throws exceptions, the agent cannot infer this from the codebase. One real snippet showing your pattern beats three paragraphs describing it.

4. Testing rules

Specify the test runner, the command to run a single file, and any non-obvious conventions. If tests must pass before committing, say so explicitly.

5. Project structure

Keep this minimal — a brief directory map, not a full architectural overview. The ETH Zurich study found that architectural overviews specifically increased inference cost and encouraged broader file traversal without improving task success. Agents can read your file tree; they cannot read your mind about which directories are off-limits.

6. Permission boundaries

The most common helpful constraint across 2,500+ repositories was "never commit secrets." A three-tier system gives the agent an explicit priority hierarchy:

What Does NOT Belong in AGENTS.md

The ETH Zurich study is unambiguous on this point: content that agents can discover independently should not be in the context file. Adding it increases cost without improving outcomes.

The Claude Code documentation puts it plainly: treat CLAUDE.md as the place you write down what you would otherwise re-explain. Add to it when Claude makes the same mistake a second time, or when a code review catches something Claude should have known.

Skills: The Other Half of the Equation

Once your AGENTS.md is in good shape, you will encounter a second class of problem: multi-step procedures that are too long for a context file, or reusable capabilities that apply across multiple projects. This is where skills come in.

The distinction, as articulated by Daniel Miessler in his Personal AI Infrastructure project, is straightforward:

The Claude Code documentation is equally direct: "If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead."

The three-tier hierarchy

Skills follow a three-tier structure:

A skill directory contains a SKILL.md file with YAML frontmatter that triggers activation, plus context files, a Workflows/ subdirectory, and optionally a Tools/ subdirectory for CLI automation. The YAML frontmatter is what makes the difference between a skill that loads automatically when relevant and one that must be invoked manually:

What belongs in a skill

A skill is the right container for anything that meets one of these criteria:

• It is a multi-step procedure (a deployment workflow, a research process, a content publishing pipeline)
• It is reusable across projects, not specific to one codebase
• It would push your CLAUDE.md past 200 lines if included there
• It only needs to be in context when a specific type of task is being performed

A security research skill, for example, might contain a Workflows/VerifyModel.md that walks through the exact steps for verifying LLM model specifications via Firecrawl before adding them to a database. That procedure is too long and too specific to live in AGENTS.md, but it is valuable enough to encode precisely so it runs the same way every time.

The Decision Framework

When you are deciding where a piece of information belongs, work through this sequence:

Is this something the agent needs in every session for this project? If yes, it belongs in AGENTS.md or CLAUDE.md — but only if the agent cannot discover it independently from the codebase.

Is this a multi-step procedure or a reusable capability? If yes, it belongs in a skill. Create a SKILL.md with a descriptive trigger phrase and put the procedure in Workflows/.

Is this already documented somewhere the agent can read? If yes, it belongs nowhere. Adding it to a context file increases cost without improving outcomes.

Is this a personal preference that should not be shared with the team? If yes, it belongs in CLAUDE.local.md (gitignored) or ~/.claude/CLAUDE.md (user-level, applies to all projects).

Is this a rule that only applies to specific file types? If yes, it belongs in .claude/rules/ with YAML frontmatter paths scoping, so it only loads when Claude is working with matching files.

Keeping Files Healthy

Context files degrade over time in a predictable pattern. Every time an agent makes a mistake, the instinct is to add another rule. Rules are rarely removed. The file accumulates contradictory patches and one-off fixes, working directly against the goal of concise, high-signal context.

The Claude Code documentation identifies "silent rule dropout in long sessions" as a documented issue — agents ignoring instructions when the context window grows large, a phenomenon sometimes called "lost in the middle." The mitigation is straightforward: keep files short, place critical rules early, and start new sessions for new tasks.

A practical maintenance cadence: review your AGENTS.md after every sprint. Remove any rule that was added reactively but has not been triggered in the past two weeks. If a section is growing past 50 lines, consider whether it belongs in a skill instead.

A Minimal Template

The following template synthesises patterns from the official AGENTS.md specification, the GitHub analysis of 2,500+ repositories, and the Claude Code documentation. It is intentionally minimal — the goal is to cover the six core areas without adding noise.

Keep this file under 200 lines. When it grows past that, move multi-step procedures to skills and path-specific rules to .claude/rules/.

Summary

The shift to agentic coding does not require a fundamentally different approach to documentation — it requires being more deliberate about what you document and where. Human-readable files (README.md, CONTRIBUTING.md, CHANGELOG.md) remain unchanged in purpose. The addition is a machine-readable context file (AGENTS.md or CLAUDE.md) that tells agents only what they cannot discover independently.

The research is clear on what works: short, human-curated files covering commands, stack, non-standard tooling, coding conventions, and permission boundaries. Everything else — architectural overviews, content already in the README, auto-generated summaries — adds token cost without improving outcomes. Multi-step procedures and reusable capabilities belong in skills, not context files, so they load on demand rather than consuming context window on every session.

The best context files are not written once and forgotten. They grow through iteration, one corrected mistake at a time, and shrink through periodic review that removes rules that have outlived their usefulness.