Define _meta scoping guidelines for skill resources

[olaservo]

Summary

• Refocuses docs/skill-meta-keys.md from recommending specific _meta keys to establishing scoping principles for when _meta is appropriate vs frontmatter, annotations, or the plugin/distribution layer
• Defines io.modelcontextprotocol.skills/ namespace convention for any future standardized keys
• Surveys existing implementations (NimbleBrain, FastMCP, Agent Skills spec) and identifies candidate keys deferred for future standardization (provenance, dependencies, content integrity, etc.)
• Applies the razor: "does this metadata also apply to non-MCP skills? If so, it should go in frontmatter"

Addresses #55

Context

Based on PR review feedback and Discord discussion:

• Skill-level semantics (version, invocation, allowed-tools) belong in frontmatter, not _meta
• Provenance and dependencies may be better solved at the plugin/distribution layer
• Namespace changed from io.agentskills/ to io.modelcontextprotocol.skills/

Test plan

• Review scoping principles against existing implementations and feedback
• Verify example is valid JSON and consistent with the skill URI scheme
• Confirm namespace convention aligns with MCP spec guidance

🤖 Generated with Claude Code

[JAORMX]

oh! this is really handy!

[pja-ant]

Hmm, this is maybe worth some more discussion.

I did put in the skill URI doc that we could use _meta for additional metadata, but I was more thinking metadata related to MCP-specific things rather than more generic skills metadata.

My sense is that for skills metadata, it should use the existing agentskills.io mechanism for that, which is YAML frontmatter. Certainly things like allowed-tools should not be in _meta when it is already in the YAML.

[olaservo]

I did put in the skill URI doc that we could use _meta for additional metadata, but I was more thinking metadata related to MCP-specific things rather than more generic skills metadata.

My sense is that for skills metadata, it should use the existing agentskills.io mechanism for that, which is YAML frontmatter. Certainly things like allowed-tools should not be in _meta when it is already in the YAML.

@pja-ant re: adding existing skills metadata to resources: my thinking was that the frontmatter in a skill file is still the source of truth, but if resources are the preferred way to expose skills through MCP, then it seems more ergonomic + predictable for clients to read that data from standardized _meta prefixes.

Weighing a few tradeoffs:

A few arguments for _meta carrying skill metadata:

• Enables discovery at list time: clients can filter/sort skills from resources/list without fetching and parsing each resource's content
• Consistent client interface: no need to understand frontmatter parsing to inspect skill properties
• Namespaced with reverse-DNS io.agentskills/, so that it clearly signals that it's an agent skill file (which can support alternative filtering/indexing besides the URI scheme)

Against:

• Duplicates what's already in frontmatter
• Blurs the line between MCP transport metadata and skill-level semantics
• Clients that read the resource content already get frontmatter for free

One way to reconcile the 'deduplication' risk: treat _meta as a 'materialized view' projected from frontmatter at list time, not a second source of truth. That way the server derives it and frontmatter stays authoritative. That keeps the layering clean while giving clients a predictable discovery surface.

What do you think?

[pja-ant]

@olaservo Those are good points!

I see the optimization argument most compelling: it would be nice to avoid pulling the whole file just to get the frontmatter. Not sure I agree with the "consistent client interface" argument since I think we want to be consistent with agent skills: you need to understand frontmatter to work with skills. I assume most clients are going to support more skills than just MCP skills, so they'll need to do that anyway.

Agree it would be good for servers to materialize the _meta from the frontmatter if we do this so that we avoid them getting out of sync.

I'm wondering how strong the optimization argument is though:

• Claude code for example loads all files from a plugin optimistically (syncs them down locally). As far as I'm aware, no one is asking for lazy loading or optimizations so that it can only pull front-matter.
• CC also sometimes needs to load the file itself (e.g. if frontmatter description is missing then it falls back to the first line of the skill).
• If you do end up loading the skill, the extra metadata is a pure pessimisation (redundant data) on every list of resources and every metadata read of a skill.

I imagine that what well-built clients will do is to read skills locally and try and keep them cached. Resources have lastModifiedTime metadata so a client can use that (+ change notifications) to keep things cached. My expectation is that metadata reads will greatly outnumber content reads, so we should optimize for light metadata reads and rely on caching to reduce/amortize the cost of getting the frontmatter.

If I'm wrong and we're actually in a world where clients read a small % of skill contents in general then yes this would mean that we'd be reading more skills than necessary.

If this happen though, we can add the optimization later. If we add the optimization now, it's much more difficult to remove it. I'd wager 10:1 that we never need that optimization.

[olaservo]

I imagine that what well-built clients will do is to read skills locally and try and keep them cached. Resources have lastModifiedTime metadata so a client can use that (+ change notifications) to keep things cached. My expectation is that metadata reads will greatly outnumber content reads, so we should optimize for light metadata reads and rely on caching to reduce/amortize the cost of getting the frontmatter.

If I'm wrong and we're actually in a world where clients read a small % of skill contents in general then yes this would mean that we'd be reading more skills than necessary.

If this happen though, we can add the optimization later. If we add the optimization now, it's much more difficult to remove it. I'd wager 10:1 that we never need that optimization.

@pja-ant it makes sense that we don't want to over-optimize before knowing that it's a problem, and that we wouldn't prefer to recommend alternatives (such as caching). There is another angle I originally had in mind when creating this doc but then I got a little fixated on mapping existing frontmatter. Will add some revisions (or close this PR) this after airing those thoughts in the discord channel.

Edit: adding a link to the related discord thread: https://discord.com/channels/1358869848138059966/1482008994062274610