So the skill path for the github:// example is owner/repo/skills/refunds, right?

Yes

I know this is just an example - but I don't think the model typically knows about MCP servers in most client implementations (or do they in your investigations into existing read_resource impls?).

For tools, the host keeps track of which tools exposed to the model come from MCP servers; it doesn't disclose to the model which MCP servers are available or how tools map to individual MCP servers.

Similarly, I would expect hosts to potentially have something like a single read_skill progressive disclosure tool that can read skills locally on disk and from MCP servers. Especially wrt the section below "Unified Treatement of Filesystem and MCP Skills". It's not clear to me how this signature would support unified treatment, since local file-based skills wouldn't have a server input value.

@olaservo did an exploration here: #2527 (comment)

I did some digging in code and:

• claude code, codex, and fast-agent all have a single read_resource tool with a server param.
• gemini-cli and goose just take uri alone and seem to probe servers one-by-one until one hits... which seems pretty janky and IMO should be fixed regardless of skills.

but yes, it's non-normative and implementations are free to do what they like here.

Similarly, I would expect hosts to potentially have something like a single read_skill progressive disclosure tool that can read skills locally on disk and from MCP servers. Especially wrt the section below "Unified Treatement of Filesystem and MCP Skills". It's not clear to me how this signature would support unified treatment, since local file-based skills wouldn't have a server input value.

What I expect (but again, non-normative):

• Client enumerate skills for all servers by reading skill://index.json
• They create a map of skill-name to skill metadata. The skill metadata says whether it is a local file or MCP-backed skill + which server it came from (or anything else).
• They have a single read_skill tool that keys on skill-name and when invoked uses the metadata to decide whether to do a local file read or MCP resources/read (note: the model doesn't need to use read_resource for this -- just read_skill and it is backed by a resource/read for MCP skills).
• read_resource is mostly needed for reading related files as part of the skill, e.g. if the skill references skill://code-review/checklist.json then the model will need to read that using a read_resource tool and make sure it is disambiguated.

That matches how I'm thinking about too, I recommend adding it to the SEP

Done!

Good callout on boundaries here 👍🏼
Probably a good idea to wait until this SEP lands, but was curious if there is an RFC on how we could leverage this in Agent Skills specs, or if there has already been a conversation. Sorry if my question had already been addressed. I'm still catching up on the topic.

I'm in touch with the Agent Skills folks and they are happy with this proposal since it keeps the Agent Skills format and just focuses on delivery. Once it lands can maybe chat with them about linking to it from the agentskills.io site as a reference.

I don't understand this constraint. I think it's quite valid to have skills nested into skills. Do we have a very strong reason to impose such constraint and reduce forward compatibility?

I think we can relax this. I think there was a good reason earlier on but I don't recall it and maybe the reason just went away after some iterations. Not sure if you remember any reason for this @olaservo? Seems actually quite useful to nest sub-skills for the pathological cases.

The Agent Skills spec currently does not specify how skill should be packaged or related to each other. Many clients only support skills at the top level, with a handful supporting nesting (although sometimes only a level or two).

If a skill is nested inside the folder; does that change how index.json looks? Is the recommendation that the index.json only highlight the top level skills?

@pja-ant I think that nesting used to be more ambiguous when the URI shape was doing more of the work. The index and the directory-read method came after we added this constraint. Now that we have those, skill identity can get asserted by the index rather than inferred from the path, so I think we can relax it.

Like Kurtis mentioned, the spec doesn't disallow it and client nesting support varies. Should we frame this as servers MAY nest and not something hosts must support? A host that only handles top-level skills can still treat every entry as flat like they would in a plain filesystem.

@addy007-icy I think a nested SKILL.md is its own skill root with its own index entry, so index.json stays a flat list and nested skills just show up as additional entries whose URLs share a path prefix with the parent. That way a host walking the parent treats a child SKILL.md as a boundary rather than subsuming the entire subtree. That could keep relative-path resolution clearer and enable the top-level-skill-as-entry-point pattern that we have mentioned as a valid way to handle a giant/hierarchical set of skills.

We had a brief discussion in ai-catalog about this. It's not fully clear that any form of Markdown allows for frontmatter. I think this is fine, but it might be strictly speaking wrong.

Yeah I think strictly speaking you are right, but the agent skills spec is SKILL.md (markdown suffix) with YAML frontmatter. I think the ship has sailed...

I wonder if we do want to be more specific here. I assume that gateway authors would really love some definitions here to ensure they can rely on governance. E.g. we can say you must map the frontmatter to _meta, hence allowing additional governance at intermediate steps.

I am sure you all thought about this, so I am curious what am I missing here.

There's not really a lot in the skills spec frontmatter that relates to governance. If people do add their own governance metadata then of course they can add it and this line gives a carve out for where it should go, but forcing implementations to mirror it just introduces potential for things to get out of sync (servers that are fronting dynamic skills would need to expand and re-parse the frontmatter on any upstream change) and it otherwise just adds a lot of overhead for unclear value.

What's the motivation for including archives? This feels like something that clients will have a hard time reasoning about, since there is no additional IT admin control if the archives don't contain zip-bombs, malicious materials, etc, compared to a marketplace.

Archives are highly requested here since otherwise a skill that potentially contains 100s or 1000s of files would require that the client pulls them one-by-one using resources/read, putting a lot of unnecessary strain on both the server and client. They are also a standard format for distributing skills.

It's true that zip bombs are a threat, but you have to deal with that anyway: even if the skill wasn't archived for delivery, it could still have a reference file skill://my-skill/references/data.zip that the client has to extract. Clients just need to deal with this.

Why does the URI need to be without a trailiing slash? that feels like an arbitrary limitation?

The alternative of allowing either IMO would just lead to incompatibility: some servers may only accept one or the other / some clients may normalize one way or the other -- leads to incompatibility. Having one correct approach and avoids the need for normalization (e.g. you blocklist access to skill://dangerous/dir but the client requests skill://dangerous/dir/ and if you forget to normalize then it falls over).

Hm. This makes sense. One thing I Worry about is that Gateway authors cannot easily introspect this on the protocol level or enhance attributes via _meta, e.g. signing them or verifying that a skill has been checked/verified in a form, or add other provenance or policy metadata. I wish we could find a way to put this into _meta on a directory/read, or a new skills/list. I am a bit torn, I do think modelling it purely on resources is a good idea in principle for backwards compatibility but it comes with some real drawbacks.

I mean you can put _meta on a resources/read of skill://index.json and the index contains the full frontmatter which is another place to put that kind of metadata that is specific to skills. The resources/read on the individual skills can also contains _meta metadata.

Why use hexadecimal and not BASE64? Most modern SRI formats use base64. We might want to do that? We might even just use SRI so people can even choose if they want sha256,sha384 or sha512. It's the de-factor default for modern package management / integrity verification and serializes more compact.

https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity

Honest answer is that we were following https://github.com/cloudflare/agent-skills-discovery-rfc#integrity-and-verification initially.

Other answer: hex appears to be the industry standard here. base64 seems to be a primarily an npm-ecosystem thing, but outside of that hex dominates: OCI, cargo, pip, homebrew, apt - all use hex.

This is correct, the hex digest is the prevelant norm for this.

One thing to consider is to enforce size being available for any served file for skill. I think we missed this in the original spec, but now that you enforce verification, you enforce that the client reads the full content and hence it needs to understand the max bounds it should read in advance or discard if it's too big.

So maybe we say, if you have a skill you MUST use size

Makes sense. Can add it.

We should give this lots of scrutiny. I assume that this will be the basis for a rework of resource handling to look more like a filesystem API.

One thing is that this file might become very large right? It also means it might be served without size so a potential unconstraint read, and lastly, since it's json it can't be read sequentially or partially. @sambhav here who mentioned that he might have some pathological use-cases. also @clareliguori because AWS also tends to have those. Any concerns?

We discussed a bit in the working group. @jonathanhefner (IIRC) made a good point that even with 10000 skills, we're talking megabytes (uncompressed) at most. It's not a huge amount.

There are alternatives as well for servers that have far too many skills, e.g. just adding a find_skill(query) tool that returns a ResourceLink. Alternatively you can have skill groups where e.g. you just add a skill://writing/SKILL.md to your index and when you read the skill it just says "go and read skill://writing/genres to find other more specific instructions" and the model can explore with the directory read verb. Of course that wouldn't include all 10000 of your skills in the system prompt, but if you have >10000 skills then you don't want to do that anyway.

This all feels like it plays into the broader progressive discovery picture and trying to solve these pathological cases here feels like trying to boil the ocean.

I'm fine with it not being paginated, even with 100k entries it will still be reasonable to fetch. Also the SEP specifies that not every skill needs to be in the index, which is perfect as it allows for progressive discovery if needed.

One option if we are really worried is making it jsonl, but this is fine for now.

I am curious how we potentially adapt (or adjust) if there are upstream breaking changes (do we expect any with Skills)? I suspect that for the most part this is a non-issue since this spec formalizes the distribution mechanism, but it might be worth spelling out.

I can add more text here. Generally, I would not expect breaking changes from skills without some form of backwards compatibility otherwise everyone's skills would just stop working (which would include MCP-delivered ones).

For some clarity, could add some language like:

In the event that the Agent Skills specification changes in a backwards incompatible way, clients MUST honor any backwards compatibility mechanisms provided by the Agent Skills specification and SHOULD continue to support the Agent Skills specification as it existed prior to any incompatible change.

We could also just advertise the supported agentskills spec range in the extension's capabilites.

Unfortunately agent skills doesn't have any versioning.

This feels a bit counter to the previous guarantees of skill readability:

A server is not required to make its skills enumerable. A skill's URI is directly readable via resources/read whether or not it appears in any index, and hosts MUST support loading a skill given only its URI (see Hosts: End-to-End Integration). This is the baseline: if a model has the URI — from server instructions, from another skill, from the user — it can read the skill.

Wouldn't this effectively contradict the MUST you just mentioned about addressability of a skill for an entire distribution class?

This also might introduce weirdness because the client now needs to know that the skill came from the archive vs. server and route to the unpacked version. Should there be a carve-out for how clients can address a local extracted cache vs. server-served skills?

Not sure I follow. For archives, the skill will still be available via the archive, e.g. a skill://code-review.zip is still readable via read_resource even if that skill is not in the index.

I could clarify with:

A skill's URI — either its SKILL.md resource or an archive resource containing it — is directly readable via resources/read whether or not it appears in any index…

Another point here:

"the host unpacks the archive locally and addresses its contents under skill://<name>/<file-path>, where <name> is frontmatter.name"

frontmatter.name is refunds. So acme/billing/refunds unpacks to skill://refunds/.... And acme/support/refunds also unpacks to skill://refunds/.... The two skills the prefix existed to separate now address the same location on the host. Second one fetched overwrites the first, or the host has two skills at one URI, depending on implementation.

Do you need to introduce a skillPath?

urgh, yeah this section is incorrect. The archive should unpack to just raw reference paths, not resource URIs (since you aren't going to load these as resources anyway).

Should be something like:

…the host unpacks the archive locally; relative references within the skill resolve against the unpacked root, per Internal References.

I am a bit uneasy about the digest logic, TBH. We're saying that the artifact is SKILL.md but then there is also the ability to load supporting files, like scripts. If the skill is "Use server.py to do FooBar" and we only create a digest for the Markdown file, doesn't it mean that now any of the supporting code can be... whatever server wants it to be?

The digest is primarily for caching purposes to avoid refetching the skill.

For verification, I think at some level you have to accept that you can't lock down absolutely everything. If we (somehow) expanded the digest to cover all the relevant resources, but then the skill says something like "call tool get_script, which returns a script file and run that" - we can't guarantee that the tool result is consistent across every usage.

These need to be MUSTs. From a security standpoint, hosts should never let skills transit from server to host without transparent origin and consent, because that now enables local execution.

Generally agree for standard chat-bot like clients, but I think it depends on context. e.g. for skills that have already been vetted in some way or pre-signed off on (particularly thinking about fully autonomous use cases) then clients would need a way to use those skills without a human in the loop.

For example: a customer support agent may use a skill to guide their conversation with customers. It would be a show-stopper if that skill needed a human sign off before the agent could do its job.