Agent Instruction Files 2026: CLAUDE.md, AGENTS.md, SKILL.md & the Fight for the Agent's Context
Every serious AI coding agent now reads at least one markdown file before it touches your codebase. Some read two or three. A few come with their own proprietary formats layered on top. In 2026, the humble .md file has quietly become one of the most contested pieces of real estate in developer tooling — a low-key standards war fought not in browser engines, but in project root directories.
We mapped the landscape: who defines which file, what each one actually does, where it lives, and which formats are consolidating into something resembling an open standard.
The Landscape at a Glance
| File | Key Information | Description |
|---|---|---|
AGENTS.md |
- Vendor: Open standard (agents.md) - Introduced: 2025 - Type: Instruction file - Status: De facto standard |
The cross-tool instruction file. Read by Codex, Cursor, Copilot, Gemini CLI, Windsurf, Cline, Aider, and others. Claude Code reads it as a fallback. Supports nesting and imports. The closest thing this space has to a universal format. |
CLAUDE.md |
- Vendor: Anthropic - Introduced: 2024 - Type: Instruction file - Status: Vendor-native |
Claude Code's native instruction file. Supports imports, project + user + subdirectory scoping, and a CLAUDE.local.md variant for personal overrides. Takes precedence over AGENTS.md when both exist. |
AGENTS.override.md |
- Vendor: OpenAI - Introduced: 2025 - Type: Instruction file - Status: Vendor-native |
Codex CLI's local-only override of AGENTS.md. Designed to be gitignored — machine-specific preferences that should never reach the repo. |
GEMINI.md |
- Vendor: Google - Introduced: 2025 - Type: Instruction file - Status: Vendor-native |
Gemini CLI's instruction file, with @path import support. Project, user, and system-level scopes. |
JULES.md |
- Vendor: Google (Jules) - Introduced: 2025 - Type: Instruction file - Status: Vendor-native |
Instructions for Google's asynchronous coding agent, Jules. Same convention as GEMINI.md, aimed at long-running delegated tasks. |
.cursor/rules/*.mdc |
- Vendor: Cursor - Introduced: 2024–2025 - Type: Rule files - Status: Proprietary (legacy: .cursorrules) |
Cursor's current rule system: markdown with YAML frontmatter, activatable by glob (globs:), alwaysApply, or manually. Replaced the single-file .cursorrules. |
.github/copilot-instructions.md |
- Vendor: GitHub (Microsoft) - Introduced: 2025 - Type: Instruction file - Status: Vendor-native |
Project-wide custom instructions for GitHub Copilot in agent mode. GitHub's bet on convention-over-configuration: it's just a file in .github/. |
.github/instructions/*.instructions.md |
- Vendor: GitHub (Microsoft) - Introduced: 2025 - Type: Scoped rules - Status: Vendor-native |
Copilot's glob-scoped instruction files, activated per path pattern via applyTo: frontmatter. Cursor-style granularity inside the GitHub ecosystem. |
.windsurf/rules/*.md |
- Vendor: Windsurf - Introduced: 2025 - Type: Rule files - Status: Proprietary (legacy: .windsurfrules) |
Windsurf's modular rule system. The legacy .windsurfrules single file is capped around 6,000 characters; the directory format removes that limit and adds activation modes. |
.clinerules / .clinerules/* |
- Vendor: Cline - Introduced: 2024 - Type: Instruction file - Status: Vendor-native |
Rules for the Cline VS Code extension. Accepts either a single file or a directory of markdown files. |
CONVENTIONS.md |
- Vendor: Aider - Introduced: 2024 - Type: Instruction file - Status: Vendor-native |
Aider's convention file, paired with .aider.conf.yml for tool configuration. |
.junie/guidelines.md |
- Vendor: JetBrains - Introduced: 2025 - Type: Instruction file - Status: Vendor-native |
Project guidelines for JetBrains' Junie agent, living in a dedicated .junie/ directory. |
Skills — a Different Animal Entirely
If instruction files tell an agent how to behave in this project, skill files tell it how to perform a specific task. The format that has won here is almost eerily uniform:
| File | Key Information | Description |
|---|---|---|
SKILL.md |
- Vendor: Anthropic (Agent Skills) - Introduced: 2025 - Type: Skill bundle - Status: De facto standard |
A folder-based skill package: SKILL.md with name/description frontmatter plus optional scripts, references, and assets. Loaded on demand via progressive disclosure rather than injected into every prompt. |
SKILL.md |
- Vendor: Kimi - Introduced: 2025 - Type: Skill bundle - Status: Adopted convention |
Kimi's assistant environment uses the identical SKILL.md folder convention, evidence the format is spreading beyond its originator. |
skills/*/SKILL.md |
- Vendor: OpenAI (Codex) - Introduced: 2025–2026 - Type: Skill bundle - Status: Adopted convention |
Codex's skills live in ~/.codex/skills/ or .agents/skills/ — the same packaging pattern, different directory. |
The distinction matters in practice. Instruction files are always in context, so they compete for token budget and demand discipline. Skill files sit in a registry; the agent sees only their name and description until it decides one is relevant. One shapes behavior continuously, the other extends capability selectively.
Adjacent Standards Worth Knowing
| File | Vendor | Purpose | Place |
|---|---|---|---|
llms.txt |
Open standard | Makes documentation sites machine-readable for LLMs | Website root |
.aiignore / .cursorignore / .codeiumignore / .claudeignore |
Various | Excludes files from AI context (env files, credentials, generated code) | Project root |
These aren't instruction channels, but they gate them: an ignore file decides what an agent is even allowed to see, which makes it a quiet but load-bearing part of the stack.
The Consolidation Story
Three patterns stand out in 2026:
1. AGENTS.md is absorbing the market. Cursor, Copilot, Gemini CLI, Windsurf, and Cline all read it natively. Claude Code reads it as a fallback when CLAUDE.md is absent. The practical advice has converged: maintain AGENTS.md as your single source of truth, then have vendor files reference it with a one-liner import.
2. Single files are dying. Nearly every vendor has moved — or is moving — from one root-level file to a directory of modular, activatable rules (.cursor/rules/, .windsurf/rules/, .claude/skills/, .agents/skills/). The root file survives mainly as an entry point.
3. "Instructions vs. skills" is the new "config vs. plugins." The taxonomy has crystallized: instructions (CLAUDE.md, AGENTS.md) shape behavior; skills (SKILL.md bundles) package capability; ignore files enforce boundaries. Teams that organize their agent context along these three lines waste the fewest tokens and get the most consistent agent behavior.
Key Takeaways
- If you maintain one file, make it
AGENTS.md— widest cross-tool support, natively read by Codex, Cursor, Copilot, Gemini CLI, Windsurf, and Cline. - If you work in Claude Code, keep
CLAUDE.md— it takes precedence overAGENTS.md, so a bare reference file pointing toAGENTS.mdis the cleanest setup. - SKILL.md isn't a missing instruction file — it's a different layer entirely, and it has quietly become the most standardized format in the whole space.
- Don't sleep on ignore files. The best instructions in the world won't help if your agent is drowning in
node_modulesand.env.