docs(findings): transport of an io.modelcontextprotocol/ frontmatter metadata key over SEP-2640 - #136
Open
tobi-oye wants to merge 2 commits into
Conversation
The issue modelcontextprotocol#66 entry was written against the pre-v1 draft, before skills/list existed. This adds a follow-up entry covering a run of the same VS Code fork against the v1 extension surface, using the findings template added in modelcontextprotocol#112. Traces one query end to end — "what does 5d10dh1 mean?" — chosen because the demo server's roll_dice tool executes dice notation but cannot explain it, so a correct answer can only come from skill content. One skills/list at connect, then two resources/read hops (SKILL.md, then the references/ file its body points at), both verified against the manifest carried in the listing entry. Records three host defects surfaced only by running: a directory URI with no read path, an uncached supporting file fetched six times, and a listing cached across four connections for 27 hours. Notes two design questions for the SEP: nothing bounds listing retention on pre-2026-07-28 connections, and a server-side tool covering the same task as a skill wins against it by default. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Issue modelcontextprotocol#126 item 4 proposes reserving the `io.modelcontextprotocol/` prefix inside the Agent Skills frontmatter `metadata` map. SEP-2640 already reserves it on the MCP side and defines no keys under it, but nothing had exercised the path end to end, and the wording suggestion the group agreed to open upstream reads better with evidence behind it. This records a run of that path. A demo server serves a skill whose frontmatter carries one key under the prefix; a VS Code fork reads `frontmatter.metadata` off the listing and reports the key it recognizes. Four cases: the marker present, a vendor-namespaced key only, an unrecognized key under the reserved prefix, and no `metadata` at all. Each records discovery, the host's log output, and whether the fetched SKILL.md still passes the frontmatter identity check that gates loading. Evidence is protocol responses, assertions and deterministic logs; no model is on the path. The entry states plainly what this does not settle. It shows transport, preservation and host recognition are possible; it does not show the namespace should be reserved, which is a governance call. The key `io.modelcontextprotocol/test-marker` is a fixture, not a proposed property. And this is frontmatter `metadata`, not MCP `_meta` — the io.modelcontextprotocol.skills/ convention from modelcontextprotocol#60 is unaffected. Two limitations worth the reader's attention: detection was observed in the unit-test harness driving the real discovery entry point, not in the running application, and no single process spanned both ends — the host-side evidence starts from the server's captured JSON. One thing the run surfaced: because a host compares fetched frontmatter field-by-field against the entry, a reserved key it does not understand still participates in verification. "Ignore unknown keys" has to mean do not act on them, not do not compare them. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds an experimental finding for #126 item 4, reserving the
io.modelcontextprotocol/namespace inside the Agent Skills frontmattermetadatamap.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:
A VS Code fork reads
frontmatter.metadataoff theskills/listentry and reports the key it recognizes. Four cases, each recording discovery, the host's log output, and whether the fetchedSKILL.mdstill passes the frontmatter identity check that gates loading:io.modelcontextprotocol/test-markerpresentinfoline, detectioncom.example/test-markerio.modelcontextprotocol/unknown-test-keytraceline, ignoredmetadataNo parser changes were needed anywhere. Server: 28 tests pass plus the stdio conformance suite. Host: 39 pass. No model is on the evidence path — protocol responses, assertions and deterministic logs only.
Tested commits: server
bb21190(on olaservo/skills-over-mcp-demoabf2262), host2984fa2, SEP-2640 ata3e147con the canonicalsep/skills-extensionbranch.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-markeris a throwaway fixture, not a proposed production property. This isSKILL.mdfrontmattermetadata, not MCP_meta; theio.modelcontextprotocol.skills/convention from #60 is a separate mechanism and is unaffected.One thing worth the group's attention
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.
Two limitations are called out in the entry: host detection was observed in the unit-test harness driving the real discovery entry point rather than in the running application, and no single process spanned both ends — host-side evidence starts from the server's captured JSON.
A documentation-only proposal to
agentskills/agentskillsfollows, citing this finding.AI assistance: this finding, the experiment code and this description were drafted with Claude Code and reviewed by me.
🤖 Generated with Claude Code