SKILL.md vs CLAUDE.md vs System Prompt vs MCP Server

SKILL.md holds instructions an agent loads on demand. CLAUDE.md and AGENTS.md are project context loaded at session start. A system prompt travels with every request. An MCP server exposes tools the model calls. Choose by how often the context must be present, and whether the agent must act on something outside the conversation.

A skill is a directory whose SKILL.md file carries YAML frontmatter with a name and a description, followed by Markdown instructions, with optional scripts/, references/, and assets/ directories beside it (Agent Skills specification, read 19 September 2026).

A project context file is plain Markdown that the client concatenates into the prompt before any work starts. CLAUDE.md is Claude Code's name for it, and AGENTS.md is the cross-tool name with no required fields (agents.md, read 19 September 2026).

A system prompt is the top-level system parameter on an API request, or the account-wide Instructions for Claude and the per-project instructions on claude.ai (Messages API and Claude personalization, both read 19 September 2026).

An MCP server is a program that exposes tools, resources, and prompts over JSON-RPC 2.0, and the model decides when to invoke a tool (MCP specification, revision 2026-07-28, read 19 September 2026).

Sources for the table: Agent Skills specification and Anthropic Agent Skills overview; Claude Code memory, Claude Code skills, and Claude Code MCP; Codex skills and Codex AGENTS.md; Cursor skills, Cursor rules, Copilot agent skills, Copilot repository instructions, Gemini CLI skills and Gemini CLI GEMINI.md; agents.md, Messages API, and the MCP specification 2026-07-28. All read 19 September 2026.

The specification names three levels. At startup the agent loads the name and description of every installed skill, at roughly 100 tokens each. On activation it loads the body, recommended under 5,000 tokens and under 500 lines. Bundled files load only when the agent reads them, so a reference file nobody opens costs nothing (Agent Skills specification, read 19 September 2026).

Anthropic's overview states the same levels and token figures, and adds that scripts run through bash so only their output enters context (Agent Skills overview, read 19 September 2026).

A real bundle shows the shape. The Channel Skill Generator writes a skill from a channel's public videos. A run recorded on 18 September 2026 produced a four-file bundle: SKILL.md at 9,623 bytes plus references/hooks.md, references/titles.md, and references/transcript-excerpts.md, confirmed with unzip -l. The second run produced a 9,395-byte SKILL.md and the third 9.4 KB (marketing/content-drafts/EVIDENCE.md, section 6). The renderer caps the body at 480 lines so the evidence that does not fit moves to the reference files (prepublish-be/internal/domain/entity/channel_skill_render.go). Nothing in the reference files occupies context until a writing assistant opens one.

Two client limits sit on top of the specification. Codex caps the whole initial skills list at 2 percent of the model context window, or 8,000 characters when the window is unknown, and shortens descriptions first when the list is long (Codex skills, read 19 September 2026). Claude Code joins description and when_to_use and truncates the pair at 1,536 characters in its skill listing (Claude Code skills, read 19 September 2026).

Progressive disclosure does not end at activation. Claude Code keeps the rendered SKILL.md in the conversation across later turns, and after auto-compaction it re-attaches the most recent invocation of each skill keeping the first 5,000 tokens, inside a combined budget of 25,000 tokens. Older skills can drop out entirely after compaction.

A writing-voice brief

Use a skill. A voice brief is procedural, it is long, and it applies when drafting rather than always. It also has natural sub-documents: hooks, titles, and transcript excerpts the agent reads only when it needs an example. That is the layout a channel skill bundle takes, and the layout the specification recommends for a skill with more evidence than fits in 500 lines.

The limit: the agent has to match the description to the task. A brief whose description says "channel voice" without naming when to use it competes with every other installed skill.

A repository convention

Use AGENTS.md or CLAUDE.md, and accept that it costs context every session. Build commands, directory layout, and naming rules apply to nearly every task, so the agent should not have to decide whether to load them. AGENTS.md states the conflict rule plainly: the closest file to the edited file wins, and an explicit chat instruction overrides both (read 19 September 2026).

The limit: the file grows. Claude Code recommends keeping a CLAUDE.md under 200 lines and moving a procedure into a skill once it stops being a fact. Codex silently stops adding files once the combined size reaches 32 KiB (Claude Code memory and Codex AGENTS.md, read 19 September 2026). Past that point the rule you added is not in the prompt, and nothing tells you.

A live data lookup

Use an MCP server. A transcript or a ticket is not in the repository, and a value copied into a context file goes stale by the next session. An MCP server exposes the lookup as a tool the model calls at the moment it needs the answer. Prepublish publishes one at prepublish.ai/mcp for that reason: the transcript is fetched on the call rather than pasted into the prompt.

The limit: the tool definition itself spends context, and the output can be large. Claude Code warns when a single MCP tool output passes 10,000 tokens and limits output to 25,000 by default (Claude Code MCP, read 19 September 2026).

Sources, each read 19 September 2026: Claude Code skills and memory; Cursor skills and rules; Codex skills and AGENTS.md; Copilot agent skills and repository instructions; Gemini CLI skills and GEMINI.md, last updated 30 April 2026 and 18 June 2026. Gemini CLI's own skills page records that unpaid-tier and Google One users were moved to Antigravity CLI on 18 June 2026.

The matrix has one practical implication. .agents/skills/ is the directory several clients already scan, so a skill placed there reaches Cursor, Codex, Copilot, and Gemini CLI without a copy. SKILL.md frontmatter is narrower than any single client's. Only name, description, license, compatibility, metadata, and allowed-tools survive the specification. Claude Code adds fields such as disable-model-invocation and paths, and other hosts reject them when a skill is packaged or uploaded (Claude Code skills, read 19 September 2026).

A skill tells the agent how to work. An MCP server gives it something to call. They combine without overlapping: a skill can tell the agent to check a schema before writing a query, and the MCP server answers the query.

The loading behavior differs. Skill metadata loads at startup and the body on activation. MCP tool names load at startup, and the definitions follow either immediately or on a search. Claude Code defers MCP tool definitions by default through tool search, so only tool names and server instructions occupy context at session start (Claude Code MCP, read 19 September 2026). Its auto mode loads definitions upfront while they total under 10 percent of the context window and defers all of them once they cross that line. A server configured with alwaysLoad puts its tools in context at session start whether or not tool search is on.

The MCP specification also makes tools a different kind of object from a text file. Tools are model-controlled: the model discovers and invokes them, while resources are application-driven and prompts are user-invoked (MCP specification, revision 2026-07-28, read 19 September 2026). The specification requires hosts to obtain explicit user consent before invoking any tool, and tells implementers to treat tool descriptions as untrusted unless the server is trusted.

Nothing in the Agent Skills format guarantees compliance. A skill body is text in a prompt, and the model can ignore it, apply half of it, or never see it because the description did not match the request. Claude Code says this in its own documentation: memory and instruction files are context rather than enforced configuration, and blocking an action requires a PreToolUse hook (Claude Code memory, read 19 September 2026).

Activation is the first place a skill can fail. Codex shortens descriptions first when the initial list grows, and may omit some skills from the list with a warning, which means a skill on disk is not always a skill the model knows about. Claude Code shows the same pressure from the other side: the combined description and when_to_use text is truncated at 1,536 characters in the listing, so the words at the end of a long description never reach the model.

Trust is the second limit. Anthropic's overview treats a skill like installing software and tells readers to audit every file in a bundle, because a skill can direct the agent to call tools or run code that the description does not mention. The MCP specification takes a similar position on tools, noting that the protocol cannot enforce its own security principles and that hosts should build consent and authorization flows themselves.

The last limit is that context bought at startup is context unavailable later. A 32 KiB AGENTS.md, a 9,623-byte SKILL.md kept in context after activation, and a dozen always-loaded MCP tool definitions all draw from the same window. The mechanisms differ in when they charge, not in whether they charge.