From 94bbc86962922f6ad701d42f376e7c0349ad594d Mon Sep 17 00:00:00 2001 From: olaservo Date: Sun, 19 Apr 2026 13:51:25 -0700 Subject: [PATCH 1/3] docs: add decision record for archive distribution type Formalizes the April 18 decision to permit type: "archive" entries in skill://index.json as a server-side packaging optimization, reinstating symmetry with the Agent Skills discovery RFC. --- docs/decisions.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/decisions.md b/docs/decisions.md index 42f300f..2462ca4 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -134,3 +134,20 @@ For background on the ADR format, see [adr.github.io](https://adr.github.io/). - [PR #2586](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2586) — charter conversion (merged 2026-04-16) - [Charter](https://modelcontextprotocol.io/community/skills-over-mcp/charter) - [Group governance](https://modelcontextprotocol.io/community/working-interest-groups) + +--- + +### 2026-04-18: Archives permitted as server-side packaging optimization + +**Status:** Proposed + +**Context:** On 2026-03-24, a commit to the Skills Extension SEP (PR #69, [`9e73838c`](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69/commits/9e73838cda478f3bba4996a06a69d3142fb0a91c)) removed `type: "archive"` from the `skill://index.json` schema with the rationale that archives do not apply when files are individually addressable. On further review, there are three costs not addressed in the original commit: asymmetry with the Agent Skills discovery RFC, which defines both `skill-md` and `archive` distribution types; loss of atomicity across multi-file skill reads; and N+1 round trips for hosts that pre-materialize skills. + +**Decision:** Permit `type: "archive"` entries in `skill://index.json`, matching the Agent Skills discovery RFC. An archive entry's `url` points to a single resource (mime type `application/zip` or `application/x-tar`) whose content unpacks into the skill's URI namespace at `skill:///`. Servers choose per-skill between individual-file and archive distribution; hosts observe an identical virtual namespace either way. + +**Rationale:** The SEP is positioned as a pure transport binding that delegates format to the Agent Skills specification. Dropping a distribution type the format spec defines contradicts that framing. Reinstating archives as a server-side packaging option — rather than a client-visible mode split — preserves the "skills as virtual filesystem" model (post-unpack view is identical to individual-file distribution) while recovering atomicity and round-trip properties. The main property lost is per-file subscription granularity, which is acceptable because subscription is not currently part of the skill reading model in the SEP. + +**References:** +- Commit [`9e73838c`](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69/commits/9e73838cda478f3bba4996a06a69d3142fb0a91c) — original removal, PR #69 +- [Agent Skills discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) — upstream format source +- April 14, 2026 office hours — discussion treated archives as supported From b3a5af3b7cb0fb7cf5dfb4461788cedd39f553aa Mon Sep 17 00:00:00 2001 From: olaservo Date: Sun, 19 Apr 2026 13:53:06 -0700 Subject: [PATCH 2/3] docs: correct decision record date to 2026-04-19 --- docs/decisions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions.md b/docs/decisions.md index 2462ca4..ebd4d5c 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -137,7 +137,7 @@ For background on the ADR format, see [adr.github.io](https://adr.github.io/). --- -### 2026-04-18: Archives permitted as server-side packaging optimization +### 2026-04-19: Archives permitted as server-side packaging optimization **Status:** Proposed From e4b1fe902bccadfbe8c8e095c373c549173aded7 Mon Sep 17 00:00:00 2001 From: olaservo Date: Sun, 19 Apr 2026 14:03:31 -0700 Subject: [PATCH 3/3] docs: add permissions/symlinks motivation and issue #61 reference --- docs/decisions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/decisions.md b/docs/decisions.md index ebd4d5c..a674d8b 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -141,7 +141,7 @@ For background on the ADR format, see [adr.github.io](https://adr.github.io/). **Status:** Proposed -**Context:** On 2026-03-24, a commit to the Skills Extension SEP (PR #69, [`9e73838c`](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69/commits/9e73838cda478f3bba4996a06a69d3142fb0a91c)) removed `type: "archive"` from the `skill://index.json` schema with the rationale that archives do not apply when files are individually addressable. On further review, there are three costs not addressed in the original commit: asymmetry with the Agent Skills discovery RFC, which defines both `skill-md` and `archive` distribution types; loss of atomicity across multi-file skill reads; and N+1 round trips for hosts that pre-materialize skills. +**Context:** On 2026-03-24, a commit to the Skills Extension SEP (PR #69, [`9e73838c`](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69/commits/9e73838cda478f3bba4996a06a69d3142fb0a91c)) removed `type: "archive"` from the `skill://index.json` schema with the rationale that archives do not apply when files are individually addressable. On further review, there are four costs not addressed in the original commit: asymmetry with the Agent Skills discovery RFC, which defines both `skill-md` and `archive` distribution types; loss of atomicity across multi-file skill reads; N+1 round trips for hosts that pre-materialize skills; and loss of UNIX file metadata (executable bits, symlinks) that has no representation when each file is served as an individual MCP resource. **Decision:** Permit `type: "archive"` entries in `skill://index.json`, matching the Agent Skills discovery RFC. An archive entry's `url` points to a single resource (mime type `application/zip` or `application/x-tar`) whose content unpacks into the skill's URI namespace at `skill:///`. Servers choose per-skill between individual-file and archive distribution; hosts observe an identical virtual namespace either way. @@ -149,5 +149,6 @@ For background on the ADR format, see [adr.github.io](https://adr.github.io/). **References:** - Commit [`9e73838c`](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69/commits/9e73838cda478f3bba4996a06a69d3142fb0a91c) — original removal, PR #69 +- [Issue #61](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/61) — thread weighing archive vs. individual-file distribution - [Agent Skills discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) — upstream format source - April 14, 2026 office hours — discussion treated archives as supported