SKILL.md vs AGENTS.md vs CLAUDE.md vs MCP: Which One Do You Need?

October 31, 2026 · backskills · 6 min read

Use a SKILL.md when you want to teach an agent a repeatable task it loads only when relevant. Use AGENTS.md or CLAUDE.md for always-on context about one project, and an MCP server when the agent needs to call live tools or reach data outside its sandbox.

They aren't competitors. Most serious setups use two or three of them together.

The one-line definitions

SKILL.md: the required file in an Agent Skills folder. Frontmatter (name, description) plus instructions, optionally bundled with scripts and references. Loaded on demand.
AGENTS.md: a plain Markdown file at a repo root that tells coding agents how to work in that repo: build commands, test commands, conventions. See agents.md.
CLAUDE.md: Claude Code's project memory file, read automatically at session start. Same job as AGENTS.md, scoped to Claude Code. See Anthropic's Claude Code memory docs.
MCP server: a process that speaks the Model Context Protocol and exposes tools, resources, and prompts to any MCP client. Discoverable through the official MCP Registry.

Comparison table

	SKILL.md	AGENTS.md	CLAUDE.md	MCP server
What it is	Folder with instructions + optional scripts	Markdown file in repo	Markdown file in repo / home dir	Running program
When it loads	On demand, when description matches the task	Every session in that repo	Every Claude Code session	When the client connects; tools called as needed
Context cost	~100 tokens idle (name + description), body on activation	Whole file, always	Whole file, always	Tool schemas, always; results per call
Scope	Reusable across projects	One repo	One repo or user	Any client that speaks MCP
Can run code	Yes, bundled scripts run in the agent's environment	No (describes commands)	No (describes commands)	Yes, in its own process
Reaches external systems	Only through tools the agent already has	No	No	Yes, that's the point
Versioning	`metadata.version` + git	git	git	Required `version` in server.json, unique per publish
Distribution	GitHub, skill directories	Lives in the repo	Lives in the repo	Package registries + MCP Registry

The "context cost" row is from the specs. The Agent Skills spec says only name and description (~100 tokens) load at startup, and recommends keeping the body under 5,000 tokens. MCP versioning rules come from the registry versioning docs.

Pick in four questions

Is this about one repo? "Run pnpm test, never edit generated files, use tabs." That's AGENTS.md (or CLAUDE.md if your team is Claude Code only). Done.
Does the agent need to reach a system it can't touch today? A database, a SaaS API with auth, a browser. That's an MCP server.
Is it a procedure you'd repeat across projects? "How we write release notes." "How to fill our compliance form." That's a skill.
Is it a procedure that uses an external system? Both. A skill that says how and when, calling tools from an MCP server that does the doing.

Same job, four ways

Take one task: "Draft release notes from merged PRs."

AGENTS.md version. Fine if it only applies here:

## Release notes
- Group merged PRs by label: feature, fix, chore.
- Skip PRs labeled `internal`.
- Output to CHANGELOG.md under a new `## vX.Y.Z` heading.

SKILL.md version. Reusable, loads only when asked:

---
name: release-notes
description: Drafts release notes from merged pull requests, grouped by label. Use when the user asks for release notes, a changelog entry, or "what shipped" for a version.
metadata:
  version: "1.0.0"
---

1. Run `python scripts/merged_prs.py --since <last-tag>`. It prints JSON.
2. Group by label: feature, fix, chore. Drop `internal`.
3. Write under `## vX.Y.Z` in CHANGELOG.md. Ask before overwriting.

MCP server version. When the PR data lives behind an API the agent can't call. A minimal tool with the official Python SDK's FastMCP helper:

from mcp.server.fastmcp import FastMCP
import httpx, os

mcp = FastMCP("release-data")

@mcp.tool()
def merged_prs(repo: str, since_tag: str) -> list[dict]:
    """List PRs merged into the default branch since a git tag."""
    token = os.environ["GITHUB_TOKEN"]
    q = f"repo:{repo} is:pr is:merged"
    r = httpx.get(
        "https://api.github.com/search/issues",
        params={"q": q, "per_page": 100},
        headers={"Authorization": f"Bearer {token}"},
    )
    r.raise_for_status()
    return [{"title": i["title"], "labels": [l["name"] for l in i["labels"]]}
            for i in r.json()["items"]]

if __name__ == "__main__":
    mcp.run()

(Filtering by since_tag is left out to keep it short.)

Combined. The skill says "call the merged_prs tool, then group and write." The server fetches. Each piece stays small, and you can swap either one.

Common mistakes

Putting everything in AGENTS.md. It loads every session. A 2,000-line AGENTS.md is paid for on every request, whether the task needs it or not. Move task-specific procedures into skills.

Building an MCP server for pure instructions. If there's no external system, a server is overhead: a process to run, auth to manage, a package to publish. A skill with a script is usually enough.

Writing a skill with a vague description. The description is all the agent sees before deciding to load it. "Helps with releases" won't trigger. See How to write a SKILL.md.

Forgetting that all four drift. Skills get edited. MCP servers publish new versions and can change tool names or descriptions. AGENTS.md changes with the repo. If you depend on someone else's skill or server, you need to know when it changes.

Where tracking fits

AGENTS.md and CLAUDE.md live in your repo. You see every change in review.

Third-party skills and MCP servers don't. Someone else edits them, and your agent's behavior shifts without a diff in your codebase. That's the gap backskills covers: it tracks public SKILL.md files on GitHub and servers in the MCP Registry, checks them daily, keeps version history so you can pin, and sends signed webhook alerts within 24 hours of a change. Details in How to track skill changes and pin versions.

FAQ

Is SKILL.md the same as CLAUDE.md? No. CLAUDE.md is always-loaded project memory for Claude Code. SKILL.md is a reusable, on-demand capability following the open Agent Skills spec.

Are agent skills replacing MCP? No. They solve different problems. Skills package instructions and scripts; MCP connects agents to external tools and data. They compose well.

Can a skill call an MCP server? Yes, if the agent running the skill has that server connected. The skill instructions just name the tool to use.

Should I use AGENTS.md or CLAUDE.md? AGENTS.md if your team uses more than one coding agent. CLAUDE.md if you're Claude Code only, or keep both and have one point to the other.

Do skills work outside Claude? The format is an open spec, and other frameworks such as Microsoft Agent Framework load it. Support for optional fields like allowed-tools varies.

Watch any public skill or MCP server for changes, free: backskills.ai. Agents: https://backskills.ai/mcp and llms.txt.