MCP SEP-2640 — Progressive skill disclosure — What does it mean?

The news. On September 13, 2026, SEP-2640 — the Model Context Protocol's Skills Extension — was reported at Final status, meaning core maintainers have signed off and reference implementations plus conformance tests exist. It defines three methods — skills/list and skills/get, which every declaring server implements, plus the optional resources/directory/read — and otherwise rides on the existing Resources primitive, so a host that already treats MCP resources as a virtual filesystem can consume a served skill exactly as it consumes a local one. Read the proposal →

Walk up to the reference desk and you do not ask for the shelf — and you do not even ask for a folder. You read the catalogue card first. In the protocol that card is a skills/list entry, and it holds more than a title: the skill's frontmatter copied verbatim, so you get the name and description the author wrote, and a contents slip listing every file in the skill with a seal number and a page count. The spec is direct about what that buys — a host can build its entire skill registry from the listing alone, without fetching each SKILL.md. Only when a skill earns it does the first document come across, and the supporting files wait until something actually reads them. That staircase is progressive disclosure, the same discipline the curriculum teaches for tool definitions.

An agent's context window is the desk it works at, and the desk does not grow — the scarce-resource problem in its plainest form. A skill that would have been useful is worthless if loading it leaves no room to act on it. What the extension adds is the ability to settle that question with arithmetic, before any bytes move: because the manifest is complete and every entry carries a byte size, a host counts the entries and sums the sizes straight from the listing. The spec leans on this hard enough to make it a prohibition rather than advice — files are not retrieved on connection, on listing, or at approval — and states the reason plainly: a listing may be arbitrarily large, so eager retrieval scales with the catalog instead of with use.

So what does a seal number actually prove? Less than it looks like, and the spec says so in as many words. When a host retrieves a file the manifest lists, it must check the bytes against that entry's digest — and a byte length disagreeing with the entry's size fails the same way, before hashing even starts. That catches corruption, a truncated read, and the ordinary case of a skill updated after you fetched the listing. What it does not catch is a dishonest server. The digests are unsigned and come from the same server as the content, so a match proves the two are consistent, not that either is trustworthy — any intermediary that can rewrite the content can rewrite the listing with it. The check is about drift between the slip and the documents, not about trusting the desk.

Content-bound approval binds to every URI and digest in the entry's resources set, not to bytes you have not fetched yet — which is what makes lazy retrieval safe to combine with approval. A file fetched long after you approved the skill is still checked against the set you approved when it is finally read, and if the server publishes a different set, that approval is revoked and has to be asked for again. A skill whose resources is the string "dynamic" sits outside this entirely — it offers no content integrity and cannot be content-bound at all. The marker is deliberately explicit so a host can tell a deliberately unverifiable skill from a malformed one, and hosts may decline to load it.

Approval also does not flow downhill. Activating a nested skill requires fresh, explicit consent, because silently promoting a file of an approved skill into an active skill would let a server ride new instructions in on an old approval. The same reasoning governs the Agent Skills allowed-tools field, which a local skill uses to declare the tools available while it runs: for an MCP-origin skill the host must ignore it unless the user has approved that grant specifically. A remote server populating allowed-tools is requesting elevated access on your machine, not describing a property of its own — which is also how you should read any remote instruction reaching a policy decision.

What 16 MiB of skill actually costs

Hold the spec's two guaranteed-interoperability limits fixed: 512 resource entries per skill, and 16 MiB (16,777,216 bytes) summed over their sizes. Conforming hosts must support skills up to those limits and may support larger ones. Both are checkable from the listing alone — count the entries, add up the size fields — before one file moves. Now convert the ceiling into context. English prose runs at roughly four bytes per token, so a skill at the size limit lands near 4.2 million tokens (illustrative — the exact ratio depends on the tokenizer). A 200,000-token context window holds about 800 KB of text, so a skill at that limit is roughly twenty full context windows. Against that, the frontmatter the listing already handed you is a name and a description — tens of tokens, for a compact entry. The host chooses between skills on the strength of what it is already holding, and never pays the 4.2 million to find out.

The extension is deliberately thin — three methods and a manifest, with the skill format itself delegated to the Agent Skills specification — but it changes what loading a skill means. A local skill is a directory you read; a served skill is a manifest you budget, a set you approve, and files you verify one at a time. Sizes let you refuse before paying, lazy retrieval keeps the refusal cheap, and digests keep the slip and the documents in step. None of that makes a server trustworthy, and the spec is careful not to pretend otherwise — which is the more useful lesson for anyone wiring a remote instruction source into a harness.

Goes deeper in: AI Agents → Tool Use → Skills as a Primitive

Related explainers

• MCP SEP-2663 — async task handles — the same spec process, applied to long-running tool calls instead of instructions
• AWS on MCP tool design — the context cost of tool definitions, which is the problem progressive disclosure solves
• Forked vs isolated subagent context — the other way harnesses keep a growing workload out of one window