AGENTS.md and SKILL.md solve different problems and were built by different companies, nine months apart, before ending up under the same neutral governance umbrella. AGENTS.md is a single plain-Markdown file, read in full on every turn, for the standing rules a coding agent needs regardless of task. SKILL.md is a folder-based format that loads progressively — a short description first, full instructions only if the task actually matches — for procedures that apply sometimes, not always. Most repos that have outgrown a single instruction file need both, not a replacement of one by the other.
Quick Answer
| AGENTS.md | SKILL.md | |
|---|---|---|
| Format | Single Markdown file, no required frontmatter | Directory with SKILL.md (YAML frontmatter + Markdown), plus optional scripts/, references/, assets/ |
| Loaded | In full, every turn, from session start | Metadata only at startup; full body on activation; bundled files only when referenced |
| Built for | Repository-wide conventions: build commands, architecture, standing constraints | Task-specific procedures: a migration script, a review checklist, a domain workflow |
| Originated by | OpenAI, August 2025 | Anthropic, published as open standard December 2025 |
| Now governed by | Contributed to the Agentic AI Foundation (Linux Foundation) at its founding | Published openly; adopted broadly, with governance still consolidating |
Two Standards, Same Neutral Home, Nine Months Apart
AGENTS.md shipped first. OpenAI released it in August 2025, developed with input from Codex, Amp, Google’s Jules, Cursor, and Factory — a group of competing tool-makers agreeing on one shared instruction-file format instead of five incompatible proprietary ones. It caught on fast: by the end of 2025 it was cited as adopted by more than 60,000 open source projects, and read natively by Amp, Codex, Cursor, Devin, Factory, Gemini CLI, GitHub Copilot, Jules, and VS Code, among others.
On December 9, 2025, the Linux Foundation announced the Agentic AI Foundation (AAIF) — a neutral home for exactly this kind of cross-vendor infrastructure — with three founding project contributions: Anthropic’s Model Context Protocol, Block’s Goose, and OpenAI’s AGENTS.md. Amazon Web Services, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, and OpenAI signed on as platinum members.
Nine days later, on December 18, 2025, Anthropic published Agent Skills — the format behind SKILL.md — as an open specification at agentskills.io, distinct from (and newer than) the Skills feature it had already shipped inside Claude.ai and Claude Code two months earlier, in October 2025. Adoption moved fast here too: Microsoft added support in VS Code and OpenAI added it to Codex CLI within about 48 hours, and independent trackers of the ecosystem list Cursor, GitHub, OpenCode, Amp, Letta, and Goose as early adopters as well. Unlike AGENTS.md, Agent Skills’ long-term governance wasn’t tied to AAIF at launch — coverage from the time describes stewardship as still being worked out, even as the AAIF itself was actively growing as an institutional option.
The short version: two different companies solved two different problems, nine months apart, and the industry converged on treating both as shared infrastructure rather than a proprietary format war. That’s why “vs” is slightly the wrong framing — they’re not really competing for the same job.
What AGENTS.md Actually Is
A single Markdown file, conventionally at the repository root, with no required frontmatter and no formal schema — “use whatever headings make sense for the project” is close to the entire structural guidance in the spec. Common sections: project overview, setup and build commands, testing conventions, and things an agent wouldn’t otherwise know (which directories are off-limits, how PRs should be scoped).
The practical constraint isn’t format, it’s size and loading behavior. OpenAI Codex documents a 32 KiB combined limit across all discovered instruction files (project_doc_max_bytes) — content past that threshold gets silently dropped, not truncated with a warning. And because AGENTS.md is read in full on every turn in every tool that supports it, a bloated file has a real, ongoing token cost whether or not a given task touches the part that’s relevant.
What SKILL.md / Agent Skills Actually Is
A skill is a directory, not a file — SKILL.md is just the required entry point:
skill-name/
├── SKILL.md # required: frontmatter + instructions
├── scripts/ # optional: executable code
├── references/ # optional: docs, loaded on demand
└── assets/ # optional: templates, static resourcesThe frontmatter is a real schema, not a free-for-all:
| Field | Required | Constraint |
|---|---|---|
name | Yes | 1–64 chars, lowercase + hyphens, must match the parent directory name |
description | Yes | 1–1024 chars — what the skill does and when to use it; this is what the agent evaluates before deciding to load the rest |
license | No | License name or reference to a bundled file |
compatibility | No | Up to 500 chars — environment requirements (e.g. “Requires git, docker, jq”) |
metadata | No | Arbitrary string key-value pairs |
allowed-tools | No | Experimental — space-separated list of pre-approved tools |
The spec’s own guidance on size is specific: keep the SKILL.md body under roughly 5,000 tokens and under 500 lines; anything longer belongs in a references/ file the agent loads only if it needs it. That’s the structural difference from AGENTS.md in one sentence — AGENTS.md has no equivalent on-demand tier, so an equally long AGENTS.md file has nowhere cheaper to live.
Progressive Disclosure Is the Whole Point
This is the mechanism that makes SKILL.md a genuinely different tool rather than “AGENTS.md, but in a folder”:
- Metadata (roughly 100 tokens per skill). Every skill’s
nameanddescriptionload at startup, cheap enough that having dozens of skills available costs almost nothing until one is used. - Instructions (the SKILL.md body). Loads only once a skill is activated — either the agent judges it relevant from the description, or (in tools that support it) a trigger keyword matches.
- Resources. Files in
scripts/,references/,assets/load only when the loaded instructions actually reference them.
AGENTS.md has exactly one loading tier: full content, every turn, no matter what. That’s a feature when the content genuinely applies to every task — nobody wants “run tests before committing” to be conditionally loaded. It’s a cost when the content only matters sometimes — a detailed PDF-processing procedure, a rarely-used migration runbook, a niche compliance checklist. Those belong in a skill, where they’re free to have until the moment they’re actually needed.
When to Use Each
| Put it in AGENTS.md if… | Put it in a skill if… |
|---|---|
| It applies to nearly every task in the repo | It’s relevant to a specific, identifiable subset of tasks |
| It’s short — a paragraph, a command, a constraint | It’s long enough that loading it on every turn would be wasteful |
| It doesn’t need executable scripts or reference docs alongside it | It bundles a script, a template, or documentation the agent should read only on demand |
| You want every tool that reads AGENTS.md to see it, with zero setup | You want it portable as a self-contained package — shareable, versionable, droppable into other repos |
A repo that only has three build commands and a couple of “don’t touch this directory” rules probably doesn’t need a single skill — AGENTS.md covers it. A repo where “generate a compliance report,” “run the database migration checklist,” and “audit third-party licenses” are all occasional, multi-step, script-backed procedures is exactly what skills were built for.
Using Both Together
They compose, and most non-trivial repos end up doing exactly that:
# AGENTS.md
## Setup
pnpm install && pnpm dev
## Conventions
- TypeScript strict mode. No `any` without a comment.
- New API routes need a test under tests/api/.
## Available skills
See .agents/skills/ for task-specific procedures
(database migrations, license audits, PR review checklist)..agents/skills/
├── db-migration/
│ └── SKILL.md
└── license-audit/
├── SKILL.md
└── scripts/audit.pyAGENTS.md stays short because it’s paying a token cost every turn. The skills carry everything that’s detailed and situational, and cost nothing until a task actually calls for them. This is also the direction tools built around both formats are pointing users — OpenHands’s own SDK documentation, for instance, now files AGENTS.md under “legacy context” specifically to contrast it with the newer, cheaper skills path for anything that isn’t a standing, universal rule.
Which Tools Read Which
| Tool | Reads AGENTS.md | Reads SKILL.md / Agent Skills |
|---|---|---|
| Claude Code | Yes (as CLAUDE.md; AGENTS.md needs an @AGENTS.md import or symlink) | Yes — Skills originated here |
| OpenAI Codex CLI / ChatGPT | Yes, one of the original co-designers | Yes, added within about 48 hours of the December 2025 open-standard release |
| Cursor | Yes, as an alternative to .cursor/rules | Yes |
| GitHub Copilot | Yes (CLI and coding agent) | Yes (GitHub added support alongside the standard’s release) |
| VS Code | Via Copilot integration | Yes, added by Microsoft within days of launch |
| Google Jules | Yes, root-level only | Not documented as of this writing |
| Amp, Goose, OpenCode, Letta | Yes | Yes |
The overlap is the headline, not the gap — most tools building serious agentic coding support now read both, which is exactly what “shared infrastructure instead of a format war” was supposed to produce.
The Common Mistake: Duplicating Content in Both
The failure mode isn’t picking the wrong one — it’s writing the same instructions into both and letting them drift. If a build command changes, and it’s both in AGENTS.md and copy-pasted into a skill’s SKILL.md, one of them goes stale. Keep AGENTS.md as the single source for anything universal, reference it from a skill if a skill genuinely needs to repeat something (“see AGENTS.md for setup”) rather than restating it, and let skills own only the parts that are genuinely conditional.
FAQ
Q1. Should I use AGENTS.md or SKILL.md for my repo? Most repos need both, not one or the other. AGENTS.md for standing, universal rules (build commands, conventions, constraints); SKILL.md-based skills for task-specific procedures that shouldn’t cost tokens on every turn.
Q2. Who created AGENTS.md and who created SKILL.md? AGENTS.md was released by OpenAI in August 2025, developed with Codex, Amp, Google’s Jules, Cursor, and Factory. SKILL.md is the file format behind Anthropic’s Agent Skills, published as an open standard in December 2025, after the Skills feature itself shipped inside Claude in October 2025.
Q3. Are AGENTS.md and SKILL.md both open standards now? AGENTS.md was contributed to the Agentic AI Foundation (Linux Foundation) at the foundation’s founding on December 9, 2025, alongside MCP and Goose. Agent Skills was published openly nine days later; its long-term governance structure was still being established at launch, even as adoption moved quickly across major tools.
Q4. Does SKILL.md replace AGENTS.md? No. They’re documented as complementary in every serious technical source, including tools like OpenHands that support both — AGENTS.md for content that applies to (nearly) every task, skills for content that only applies sometimes.
Q5. What’s the token-cost difference in practice? AGENTS.md content is injected into every turn regardless of relevance. A skill’s metadata (name + description) is what’s always present — roughly 100 tokens per skill — with the full body only loading once the skill is actually activated. A repo with a dozen rarely-used skills costs far less than the same content pasted into one large AGENTS.md.
Q6. Can a SKILL.md file have subdirectories or file-scoped rules the way some AGENTS.md setups do?
Not through the frontmatter fields defined in the base Agent Skills spec — those cover name, description, license, compatibility, metadata, and the experimental allowed-tools. Some tools add their own extensions on top (OpenHands’s triggers and paths fields, for example) for keyword- or file-triggered activation, but those aren’t part of the portable base spec.
Q7. Does Claude Code read AGENTS.md automatically?
Not by default — Claude Code reads CLAUDE.md. The standard fix is a one-line @AGENTS.md import at the top of CLAUDE.md, or a symlink, so both formats stay in sync without duplicating content.
Related Reading on The Prompt Shelf
- OpenHands and AGENTS.md: From Microagents to the New Skills System (2026)
- AGENTS.md Not Loading? How to Debug It in 2026
- 15 Best Claude Code Skills You Should Install in 2026
- Claude Code Skills vs Slash Commands: The Complete Guide
- AGENTS.md vs CLAUDE.md: Tool Support Compared (2026)
Browse real AGENTS.md and SKILL.md examples from open-source repositories in our gallery.