Investigate: Should MCP support delivering zipped skill directories (.skill bundles)?

[olaservo]

Context

In SEP-2093 discussion, @mgoldsborough raised a question about skills that are more than a single SKILL.md — directory structures with templates, reference docs, scoring rubrics, etc.:

skill-author/
├── SKILL.md
└── templates/
    ├── process.template.md
    ├── dialogue.template.md
    └── audit.template.md

The emerging convention for distributing these has been to zip the directory as a .skill bundle with SKILL.md at the root. The question is: how should multi-file skills be delivered over MCP?

@pja-ant responded that .zip/.skill distribution is a real thing — the Agent Skills spec still defines a skill as a directory containing at least a SKILL.md, and the zip is just a distribution mechanism. He noted that whether to support zipped skill directories over MCP is a question for this IG, and that for SEP-2093 purposes, mimeType on the resource can distinguish format.

Questions to investigate

1. Zip bundles vs. individual resources: Should multi-file skills be delivered as a single .skill/.zip blob via resources/read, or should each file be an individually addressable skill:// resource (as proposed in the Skill URI Scheme)?

2. Client capabilities: If we support both, how does a client signal which delivery method it prefers? Can mimeType alone (per SEP-2093) handle this, or do we need additional convention?

3. Relationship to SEP-2093 listable resources: SEP-2093 introduces per-resource capabilities: { list: true } and URI-scoped resources/list. This could enable a skill directory to be a listable resource whose children are the individual files — potentially making zip bundles unnecessary for MCP delivery while still supporting them for other distribution channels (git, registry, .well-known).

4. Convention recommendation: Should the MCP Skills Convention take a position on this? E.g., "skills served over MCP SHOULD expose individual files as sub-resources; .skill bundles are for out-of-band distribution only."

Related

• SEP-2093: Resource Contents Metadata and Capabilities
• Skill URI Scheme Proposal (sub-resource addressing)
• NimbleBrain .skill artifact format
• Agent Skills Discovery RFC (supports archive distribution with SHA-256 digests)
• Approaches doc: Distribution and Provenance Considerations — Sam Morrow's note that MCP servers should not provide platform-specific bundles and skills should remain text-based context

[mgoldsborough]

Thanks for formalizing this @olaservo. Couple thoughts.

re: Q3/SEP-2093, I'd be concerned that listable resources with individually addressable children creates a chatty problem. A multi-file skill with 8 files means 8 resources/read calls just to load it. And resources/list returns a flat bag of URIs with no semantic grouping, so the client can't distinguish skill sub-resources from other resources anyway.

IMO, it's cleaner if skills over MCP should be a single resource read. One call, you get the full skill and it's on the client to determine what do to w/ the resources(s) it obtained. The skill:// URI scheme handles discovery - clients filter by uri to find skills.

The harder part is the delivery format issue. I'm wondering if this is more of a content negotiation problem, not a URI scheme problem. Similar to HTTP's Accept-Encoding, the server could advertise encoding capabilities per resource:

{
  "uri": "skill://server/blog-editor",
  "name": "Blog Editor Skill",
  "mimeType": "text/markdown",
  "capabilities": {
    "encodings": [
      "identity", "gzip"
    ]
  }
}

For a single-file skill, client reads it as plain text. For multi-file skill directories, client could request gzip, server responds with the compressed directory. Same URI, same resources/read but the encoding negotiation handles the hard part.

This is nice because it follows a pattern every developer already understands, it's not skill-specific (any large resource benefits from compression), and the server stays in control of supported formats.

[pja-ant]

Could we just use the application/zip mime Type?

{
  "uri": "skill://server/blog-editor",
  "name": "Blog Editor Skill",
  "mimeType": "application/zip"
}

if you want to share a non-zip file as well, you could just have different URI + mimeType?

[
  {
    "uri": "skill://server/blog-editor",
    "name": "Blog Editor Skill",
    "mimeType": "text/markdown"
  },
  {
    "uri": "skill://server/blog-editor.skill",
    "name": "Blog Editor Skill",
    "mimeType": "application/zip"
  }
]

[jonathanhefner]

In my opinion, for broad compatibility, using archives (either .zip or .tar.gz) for multi-file skills is a Good Idea™.

Skill files may have UNIX permissions set (e.g., +x for scripts). Skill files may also be symlinks. And as #61 (comment) points out, skills may also contain a large number of files (i.e., unreasonably many for individual resources/read calls).

Furthermore, if the client downloads and unpacks the archive, it may obviate the need to treat skills over MCP differently from regular skills (e.g., being unable to grep through reference files).

(For reference, over in the Agent Skills repo, we just proposed distributing skills as either a single SKILL.md file or a .zip/.tar.gz file.)

[pja-ant]

Some more thoughts here:

• If we do allow for shipping skills as zip then it creates a front-matter loading problem as you cannot read the front-matter without downloading and extracting the entire skill (which could be very large).
• I see that the .well-known proposal duplicates the front-matter into an index.json. We could also duplicate into _meta (cc @olaservo), but this has problems: (1) duplication introduces an avenue for divergence, (2) YAML to JSON (and vice versa) is lossy, (3) clients end up reading the frontmatter multiple times, which is wasteful.
• zip/tar.gz, while mostly portable, do come with portability issues on Windows, e.g. the aforementioned UNIX permissions and symlinks don't map neatly to Windows and there's also potential issues with case sensitivity differences.
• While extracting to the filesystem works well for agents that have access to the filesystem, it creates a whole bunch of headaches for those that do not: you now have to provide a in-memory virtual filesystem and requisite tools to your agent. If they were just MCP resources then a single read_resource would suffice.

That's a lot of FUD. Not totally opposed to supporting this, but I do wonder if this is giving a lot of bang for buck. In my experience, skills generally don't have a lot of files, and those that do often don't need the model to load all the files when invoked. I'm wondering if this complexity is worth it? Requesting many files over a single HTTP connection really isn't that much more expensive that requesting one.

[jonathanhefner]

(2) YAML to JSON (and vice versa) is lossy, (3) clients end up reading the frontmatter multiple times, which is wasteful.

Could you elaborate on these two points?

For description, when would the conversion be lossy?

Also, what did you mean by "clients end up reading the frontmatter multiple times"?

• zip/tar.gz, while mostly portable, do come with portability issues on Windows, e.g. the aforementioned UNIX permissions and symlinks don't map neatly to Windows and there's also potential issues with case sensitivity differences.

Windows does not support UNIX permissions, but it also doesn't need them (i.e., no checks). 😄 Note, that WSL does support (and need) them, though.

For symlinks, it's a bit more questionable. Both Windows and WSL support symlinks, but Windows (not WSL) requires elevated permissions to create them. I would probably advise skills to not use symlinks, but they are possible to use (i.e., not forbidden), so I think skill distribution mechanisms should either support them (e.g., via archives) or explicitly handle their presence (e.g., logging an error message and omitting the skill from the list of skills).

• While extracting to the filesystem works well for agents that have access to the filesystem, it creates a whole bunch of headaches for those that do not: you now have to provide a in-memory virtual filesystem and requisite tools to your agent. If they were just MCP resources then a single read_resource would suffice.

My personal take here is that "skills over MCP" should establish that as a client capability and offer tiered behavior. If a client does not support filesystem access, then "skills over MCP" should only list single-file skills (just SKILL.md). If a client does support filesystem access, "skills over MCP" can also list multi-file skills as archives. (Although that kind of filtering could be done client-side based on MIME type, it might be helpful for the server to know what the client supports.)

I realize that goes against what a lot of people are thinking, but, to me, it seems like there is a fundamental impedance mismatch for multi-file skills when there is no filesystem access. If someone wants something like multi-file skills without filesystem access, I feel like they would be better off using a single-file skill + tools.

[pja-ant]

For description, when would the conversion be lossy?

description probably isn't lossy, but more generally YAML has a bunch of features that JSON does not have (anchors, non-string keys, tags, documents, sets, typing) that do not exist in JSON. Shouldn't matter for core Skills fields, but if some extension uses some of these features from YAML then they can't be reflected in JSON.

Also, what did you mean by "clients end up reading the frontmatter multiple times"?

I meant that if you put the front-matter in both the _meta and the SKILL.md then the client ends up downloading it twice. It's a minor point.

I realize that goes against what a lot of people are thinking, but, to me, it seems like there is a fundamental impedance mismatch for multi-file skills when there is no filesystem access. If someone wants something like multi-file skills without filesystem access, I feel like they would be better off using a single-file skill + tools.

Why couldn't they just host all the files as MCP resources and let the model read them when needed? Don't need a filesystem and gets you multi-file without having to introduce new concepts (zip files, different mime type handling).

[jonathanhefner]

Why couldn't they just host all the files as MCP resources and let the model read them when needed? Don't need a filesystem and gets you multi-file without having to introduce new concepts (zip files, different mime type handling).

It's similar to the difference between writing a script that targets files vs a script that targets REST APIs. Yes, you can read data from either, but the network barrier makes it impractical to do things like run grep unless you prefetch all the files. If your script doesn't need to do those kinds of operations or if you write the script such that it does prefetch files, then it works. But, obviously, not all scripts are designed that way.

If we're building a distribution mechanism for skills, then I feel like we should either support skills as they are being written today, or explicitly say that we only support skills written in a particular way.

[pja-ant]

Thanks, I think that's the relevant delta: if you see skills primarily as scripts for doing things rather than instructions for how to use tools. I was expecting MCP-delivered skills would primarily be the latter since they probably are going to be instructing you how to do different things with their tools, but that's may not be a valid assumption.

Agree that if you are delivering scripts that are asking you to e.g. grep through other resources then it's not going to work well (unless someone builds mcp-fuse!)

[masterkidan]

I'd like to point out one limitation from this, as I did try to do this. For security reasons even if the MCP protocol did provide a zip file, the zip/tarball will only be downloadable to the sandbox'd VM coding environment that the desktop clients run (like claude or chatgpt). We will need some user involvement to actually place them in a folder that's relevant for the clients to pick them up (as part of their install directory) and then use them in RAG workflows.