Define recommended _meta keys for skill resources

[olaservo]

Summary

• Adds docs/skill-meta-keys.md proposing recommended _meta key conventions for skill resources served over MCP
• Defines core keys (io.agentskills/version, io.agentskills/invocation) and experimental extended keys (allowed-tools, requires, category) using reverse-DNS namespace
• Surveys existing implementations (NimbleBrain, FastMCP, Agent Skills spec) and provides concrete resources/list response examples

Closes #55

Test plan

• Review proposed _meta keys against existing implementations
• Verify examples are 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?

[sambhav]

Given this will be an MCP extension should we not use a io.modelcontextprotocol reverse domain?

[olaservo]

My original thought with io.agentskills/ was because it would align with the agentskills.io spec and create a transparent mapping to frontmatter fields.

A couple thoughts on each option:

• io.modelcontextprotocol/ would signal this is MCP-official, but ties skill metadata to MCP even though skills are agnostic to MCP
• io.agentskills/ would keep the namespace tied to the skills ecosystem, which exists independently of MCP. This could make the mapping to standard frontmatter fields more obvious.

[LucaButBoring]

I'd prefer io.modelcontextprotocol given that this isn't really under the ownership of the Agent Skills community; we can do a subdomain like io.modelcontextprotocol.skills or something to make the association more explicit if needed. I think it might be poor form for us (or anyone, really) to use unowned domains in extension keys without permission from the domain owner.

[LucaButBoring]

Unrelated but interesting future idea (out of scope for this IG): Defining a new .well-known document or TXT records to verify ownership of any extensions and/or extension schema

[olaservo]

I think it might be poor form for us (or anyone, really) to use unowned domains in extension keys without permission from the domain owner.

Yes totally, to be clear, we'd only use io.agentskills/ if it was agreed on with the agentskills.io spec maintainers (which is something this IG is positioned to coordinate on). io.modelcontextprotocol.skills/ seems like another good option though.

Unrelated but interesting future idea (out of scope for this IG): Defining a new .well-known document or TXT records to verify ownership of any extensions and/or extension schema

I like that idea, created some notes here based on some preliminary research on related work: https://gist.github.com/olaservo/fa58f7574e3c4b41e92f16869c972455

[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