---
title: "SKILL.md vs AGENTS.md vs CLAUDE.md vs MCP: Which One Do You Need?"
description: "SKILL.md packages a task an agent loads on demand. AGENTS.md and CLAUDE.md give always-on project context. An MCP server exposes live tools and data. A comparison table, decision steps, and examples."
slug: skill-md-vs-mcp-vs-agents-md
date: 2026-10-31
tags: [agent-skills, mcp, agents-md, claude-md, comparison]
---

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

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](https://agentskills.io/specification) 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](https://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](https://docs.claude.com/en/docs/claude-code/memory).
- **MCP server**: a process that speaks the [Model Context Protocol](https://modelcontextprotocol.io) and exposes tools, resources, and prompts to any MCP client. Discoverable through the [official MCP Registry](https://github.com/modelcontextprotocol/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](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/versioning.mdx).

## Pick in four questions

1. **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.
2. **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.
3. **Is it a procedure you'd repeat across projects?** "How we write release notes." "How to fill our compliance form." That's a skill.
4. **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:

```markdown
## 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:

```markdown
---
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:

```python
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](/blog/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](https://backskills.ai) 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](/blog/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](https://learn.microsoft.com/en-us/agent-framework/agents/skills) load it. Support for optional fields like `allowed-tools` varies.

---

*Watch any public skill or MCP server for changes, free: [backskills.ai](https://backskills.ai). Agents: `https://backskills.ai/mcp` and [llms.txt](https://backskills.ai/llms.txt).*