Context Files for AI Agents: AGENTS.md, SKILL.md, DESIGN.md

Coding-agent repositories are accumulating a pile of markdown files in their root: AGENTS.md, SKILL.md, .cursorrules, .windsurfrules, copilot-instructions.md. This guide explains which file is responsible for what, and how to avoid duplicating the same context in five different places.

The material is based on a review by Jaydeep Karale, cross-checked against primary sources, but not verified by running the code. Data is current as of September 2026.

Why agents need context files

A new engineer reads the README, asks questions, and picks up conventions as they go. An agent doesn't have that luxury: at the start of every session, it needs explicitly written context. Markdown became the default format because it's plain text that both humans and models read equally well, and changes show up cleanly in a diff.

The target setup looks like this: one canonical AGENTS.md as the single source of truth; tool-specific files generated from it; and rare capabilities split out into SKILL.md files that load on demand.

💡 Context engineering is the practice of deciding exactly what the model sees and in what form, so it acts precisely without burning tokens on irrelevant material.

The file map: who's responsible for what

File	Describes	Read by	When needed
AGENTS.md	The project: commands, code style, boundaries	Major coding agents	Almost always, one per repo
SKILL.md	A specific capability: instructions, scripts, reference material	Claude Code, Codex, Copilot, and others	When a capability isn't needed every session
.cursorrules, .windsurfrules	Project config for Cursor and Windsurf	Cursor, Windsurf	Backward compatibility
copilot-instructions.md	Project config for GitHub Copilot	GitHub Copilot	Backward compatibility, lives in .github/
DESIGN.md	The visual system: tokens and rationale	Agents generating UI	When an agent writes UI code

AGENTS.md: the common standard

AGENTS.md was released in August 2025 and later handed off to the Agentic AI Foundation (AAIF) under the Linux Foundation. According to OpenAI, by the time of the handoff more than 60,000 projects had already adopted the standard, and it's now read by the major agentic tools: Codex, Cursor, GitHub Copilot, Gemini CLI, VS Code, and others. It's meant to be one canonical file per repository: build and test commands, code style, and hard constraints the agent must respect.

Research on this points to some practical conclusions: architecture overviews barely move the needle. What measurably reduces error rates are precise commands, explicit version constraints, and clear definitions of done. Vague phrasing like "where possible" simply gets ignored — agents need exact, working rules.

⚠️ Warning: don't hand off AGENTS.md generation to the model itself without oversight. A 2026 study (arXiv:2602.11988) found that context files raise inference cost by more than 20% on average, and auto-generated ones also reduce task success rates; hand-written files, by contrast, give a modest boost. A short, carefully reviewed file beats a long, auto-generated one.

SKILL.md: a portable capability

Where AGENTS.md describes the project, SKILL.md describes a single capability. A skill is a folder containing a SKILL.md file and, if needed, supporting scripts and reference material. The format is portable across Claude Code, Codex, Copilot, and other compatible agents.

💡 Progressive disclosure: at the start of a session, the agent reads only the skill's name and description from the YAML frontmatter; the full body loads only when a matching task comes up, and scripts or reference material load even later. That way the context window isn't spent on instructions that might never be needed.

For a library of reusable prompts and procedures, this format is far more convenient than one bloated AGENTS.md. It's also why directories like skills.sh have taken off: a skill is just a folder of Markdown, easy to publish and easy to install.

Some practical rules:

• The frontmatter description needs to be precise — the agent decides whether to open the file based on it, and a vague description defeats the whole point of the savings.
• Move occasional-use capabilities (deployment, an internal API) into SKILL.md; rules needed in every session stay in AGENTS.md.
• A dozen unused skills cost almost nothing: the agent only pays tokens for their short descriptions, not their full bodies.

Tool-specific files

Before the common standard existed, every tool invented its own convention, and these files are still maintained for backward compatibility (see the tool mapping in the table above).

A working pattern for teams juggling several tools: keep AGENTS.md as the single source of truth, and generate everything else from it. This closes off a common failure mode — one file gets updated, four get forgotten, and the files drift out of sync again.

A minimal sync script looks like this:

#!/usr/bin/env bash
# sync-agent-context.sh: AGENTS.md as the single source of truth
set -euo pipefail

cp AGENTS.md .cursorrules
cp AGENTS.md .windsurfrules
mkdir -p .github
cp AGENTS.md .github/copilot-instructions.md

DESIGN.md and narrower formats

Alongside the general-purpose files, narrower ones are emerging. DESIGN.md, for instance, encodes a project's visual system: machine-readable design tokens (colors, spacing, typography) plus the rationale behind why those specific choices were made. An agent generating a UI gets both the values and the reasoning behind them. The format is still early, but the direction is clear: separate files for separate slices of context.

A reference AGENTS.md template

Here's a minimal example to build from:

# AGENTS.md

## Commands
<!-- Exact commands with flags -->
- Build: `pnpm build`
- Test: `pnpm test -- --run`
- Lint and typecheck: `pnpm lint && pnpm typecheck`

## Boundaries
<!-- What not to touch without a separate task -->
- Don't modify migrations in `db/migrations/`
- Don't add dependencies without a corresponding line in the PR description

## Definition of done
<!-- A task is complete when all of the following hold -->
- Build, tests, and lint all pass
- Changes are scoped to files relevant to the task
- AGENTS.md is updated if commands or boundaries changed

Maintenance discipline

These files deserve the same treatment as code:

• Review them in the same pull request as the change they describe.
• Delete outdated sections immediately.
• Audit every few months: remove any rule that has since migrated into code, linters, or type checks.
• Remember that every line of AGENTS.md gets read on every single session — it's an ongoing token cost, so don't put anything in it that's already obvious from the repo itself.

⚖️ Trade-off: a short, precise file that actually gets read every time beats a detailed one that gets skimmed or that contradicts the code.

Quick-check checklist

• The repo root has exactly one AGENTS.md, readable in a couple of minutes
• Every command in the file has been tested and can be copy-pasted without edits
• There's no general architecture-overview section
• There's no vague phrasing like "where possible"
• Common tasks have explicit definitions of done
• The file was written or reviewed by a human, not accepted as-is from auto-generation
• Rare procedures are split into SKILL.md files with precise frontmatter descriptions
• Tool-specific files are generated from AGENTS.md via script
• Context files go through review in the same PR as the code
• There are no rules already enforced by code, linters, or type systems

Getting this system right for a specific repo and tool stack is easier in practice than in theory, especially once a team is running several agents and several editors at once. Treat context files the way you'd treat any other piece of infrastructure: version them, review them, and prune them relentlessly — the payoff shows up in fewer wasted tokens and fewer agent mistakes.