SKILL.md vs MCP Manifest vs AGENTS.md
These three files solve different problems that all get lumped together as "AI agent config": SKILL.md packages a reusable instruction set that Claude loads on demand, an MCP server manifest tells a client how to launch a tool-providing server, and AGENTS.md is a general-purpose operating manual any coding agent reads at the start of a session. None of them replace the others.
| SKILL.md | MCP manifest | AGENTS.md | |
|---|---|---|---|
| What it is | A packaged, on-demand instruction set for Claude | Launch config for an MCP server (command, args, env) | A repo-wide operating manual for any coding agent |
| Format | Markdown + YAML frontmatter | JSON | Plain markdown |
| Triggered by | Matching the description field to the request | The client launching the server at startup | Being read once at the start of an agent session |
| Lives where | Inside a skill package/folder | The client's own config file (merged in) | Repo root (and optionally subdirectories) |
| Grants new tools? | No — instructions only | Yes — the server exposes new tools | No — instructions only |
SKILL.md
A SKILL.md packages a specific, reusable capability — "fill this PDF form," "write commits this way" — as instructions Claude loads only when the request matches. It grants no new tools; it's pure instruction-following, scoped narrowly by its description. Build one when you have a repeatable task worth capturing once and triggering by name.
MCP server manifest
An MCP manifest is infrastructure, not instructions — it's the JSON a client reads to start a server process and connect to it. Unlike the other two, it actually changes what an agent can do, by exposing that server's tools. Build one (or just fill it in from a server's docs) when you're connecting a real tool-providing server, not when you want to change how an agent behaves.
AGENTS.md
AGENTS.md is the broadest of the three: a plain-markdown file any coding agent reads at the start of a session, covering setup commands, code style, and testing conventions for the whole repo. It's the closest thing to a universal standard across agents, and the easiest to add value with first.
FAQ
Do I need all three — SKILL.md, an MCP manifest, and AGENTS.md?
No. Most projects need at most one or two: AGENTS.md if you want any coding agent to work well in your repo, SKILL.md only if you're packaging reusable instructions specifically for Claude Skills, and an MCP manifest only if you're actually connecting to (or building) an MCP server.
Can a project use more than one at the same time?
Yes, and it's common — a repo might have an AGENTS.md for how any agent should work in it, while also connecting to several MCP servers listed in its editor's mcpServers config, with no conflict between them.
Which one should I build first?
If you just want any AI coding agent to be less confused in your repo, start with AGENTS.md — it has the broadest support and the lowest setup cost. Add a SKILL.md or MCP manifest only once you have a concrete reusable capability to package.