docs(findings): transport of an io.modelcontextprotocol/ frontmatter metadata key over SEP-2640

[tobi-oye]

Adds an experimental finding for #126 item 4, reserving the io.modelcontextprotocol/ namespace inside the Agent Skills frontmatter metadata map. One commit on current main.

Why

The group agreed on 2026-06-16 (§2) to propose the reservation upstream in the Agent Skills spec. SEP-2640 already reserves the prefix on the MCP side and defines no keys under it, but nothing had exercised the path, and a wording suggestion reads better with evidence behind it. This is that evidence, run before the upstream proposal rather than after.

What was run

A demo server serves a skill whose frontmatter is exactly:

---
name: namespace-detection-demo
description: Demonstrates transport of MCP-reserved Agent Skills metadata.
metadata:
  io.modelcontextprotocol/test-marker: "detected-by-vscode"
---

VS Code started that server over stdio, called skills/list, and recognized the key four milliseconds later:

17:48:45.530  [editor -> server] {"jsonrpc":"2.0","id":3,"method":"skills/list","params":{}}
17:48:45.534  [info] [mcp-skills-experiment] io.modelcontextprotocol/test-marker detected on skill
              "namespace-detection-demo" from "skills-demo-local" (value "detected-by-vscode")
17:48:45.534  [info] [mcp-skills] "skills-demo-local" served 4 skill(s): tabletop-dice,
              mcp-glossary, namespace-detection-demo, release-notes-writer

Four cases, each recording discovery, the host's log output, and whether the fetched SKILL.md still passes the frontmatter identity check that gates loading:

Case	Discovery	Host log	Load
io.modelcontextprotocol/test-marker present	ok	one info line, detection	passes
only com.example/test-marker	ok	nothing	passes
io.modelcontextprotocol/unknown-test-key	ok	one trace line, ignored	passes
no metadata	ok	nothing	passes

The first ran in the running editor against a live server; the other three are unit tests against the same discovery entry point. No parser changes were needed anywhere. Server: 28 tests pass plus the stdio conformance suite. Host: 39 pass. No model is on the evidence path — wire logs, protocol responses and deterministic host logs only.

Tested commits: server bb21190 (on olaservo/skills-over-mcp-demo abf2262), host 2984fa2, SEP-2640 at a3e147c on the canonical sep/skills-extension branch.

What it does not claim

Stated explicitly in the entry: this shows transport, preservation and host recognition are technically possible. It does not show the namespace should be reserved — that is a governance and interoperability decision for the Agent Skills project. io.modelcontextprotocol/test-marker is a throwaway fixture, not a proposed production property. This is SKILL.md frontmatter metadata, not MCP _meta; the io.modelcontextprotocol.skills/ convention from #60 is a separate mechanism and is unaffected.

Two things worth the group's attention

Ignoring is not the same as not comparing. Because a host compares fetched frontmatter field-by-field against the published entry, a reserved key it does not understand still participates in verification: a marker whose value differs between listing and file fails the check and the skill does not load. So "implementations SHOULD ignore keys under this prefix that they do not recognize" needs to mean do not act on them, not do not compare them. Worth a clarifying clause in the SEP if the group agrees.

Reserved metadata inherits the listing cache's lifetime. Two skills/list calls produced two detection lines, but a third contribution of the same skills to the model's context produced none — it came from the host's cache without re-running discovery. Fine for a log line; relevant for any future key meant to influence behaviour.

Limitations are listed in the entry. The main ones: the live session covered discovery and detection but never loaded the skill, so the "still loads" column rests on tests and the server-side verified read; and the live host negotiated 2025-11-25, so the 2026-07-28 listing-cache attributes were exercised server-side only.

A documentation-only proposal to agentskills/agentskills follows from this: agentskills#546.

AI assistance: this finding, the experiment code and this description were drafted with Claude Code and reviewed by me.

🤖 Generated with Claude Code

[tobi-oye]

One wording clarification that may help: “unrecognized” means the host can read the key and value but has no implementation for its semantics.

The host should still preserve the key and include it in frontmatter identity verification:

• Same unknown key/value in the listing and fetched file: verification passes, but the host assigns it no behavior.
• Different or missing value: verification fails.
• Recognized key: verification passes first, then the host may apply its defined behavior.

Suggested SEP wording:

Implementations SHOULD NOT interpret or act on keys under this prefix that they do not recognize. They MUST still preserve those keys and include them in frontmatter identity verification.