modelcontextprotocol/ext-skills
Watch
1
0
Fork
You've already forked ext-skills
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: update decision log to reflect accepted statuses for filesystem and archive implementation details (#97)

Browse source
This commit is contained in:
Ola Hungerford 2026-06-09 10:27:26 -07:00 • committed by GitHub
commit 8c116b577b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 31 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

34
docs/decisions.md
View file

@ -166,7 +166,7 @@ For background on the ADR format, see [adr.github.io](https://adr.github.io/).
### 2026-04-19: Filesystem is a host-side implementation detail
**Status:** Proposed
**Status:** Accepted
**Context:** Previous meetings surfaced an open question: whether the Skills Extension SEP should require, forbid, or remain silent on a local filesystem as a host capability. The SEP as drafted is de facto filesystem-agnostic (resources are URI-addressable, `read_resource` is the recommended loading path) but does not state this as a normative requirement, leaving skill authors without a portability guarantee and hosts without clear scope.
@ -186,7 +186,7 @@ For background on the ADR format, see [adr.github.io](https://adr.github.io/).
### 2026-04-19: Archives permitted as server-side packaging optimization
**Status:** Proposed
**Status:** Accepted
**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.
@ -204,7 +204,7 @@ For background on the ADR format, see [adr.github.io](https://adr.github.io/).
### 2026-06-02: Reinstate the `digest` field in `skill://index.json`
**Status:** Proposed
**Status:** Accepted
**Context:** SEP-2640's `skill://index.json` binding follows the [Agent Skills well-known discovery index](https://github.com/agentskills/agentskills/pull/254) with two stated differences — the `url` field carries a full MCP resource URI, and the per-entry `digest` field is omitted "(integrity is the transport's concern over an authenticated MCP connection)" — plus one MCP-specific addition, the `mcp-resource-template` `type` value. In the upstream index each skill entry carries a `digest` (a `sha256:<hex>` content hash) serving two purposes: (1) integrity — letting an index host attest that a served skill matches what the index advertised, which matters when the index and the skill artifacts live on different hosts (e.g., index on one domain, archives on a CDN); and (2) caching — a client stores the digest, refetches only the index, and skips refetching unchanged skill content, which can run to tens of MB. The same trade-off was argued upstream on [agentskills#254](https://github.com/agentskills/agentskills/pull/254), where Peter Alexander questioned the digest's value over HTTP (standard HTTP caching could cover it) and Jonathan Hefner defended it on cross-domain integrity and lockstep-consistency grounds. Over MCP, purpose (1) does not apply, since the same server serves both the index and the skill resources; and the cleaner long-term answer to (2) — a general resource-freshness mechanism (resource metadata or ETags) — does not exist in the base protocol today. The omission was revisited in the June 2, 2026 Working Session and in the [#skills-over-mcp-wg](https://discord.com/channels/1358869848138059966/1464745826629976084) Discord channel, where the group converged on putting `digest` back.
@ -218,3 +218,31 @@ For background on the ADR format, see [adr.github.io](https://adr.github.io/).
- [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) — Cloudflare provenance for the index format and SHA-256 digests.
- [Meeting Notes — Skills Over MCP WG](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/categories/meeting-notes-skills-over-mcp-wg) — June 2, 2026 Working Session.
- [#skills-over-mcp-wg Discord](https://discord.com/channels/1358869848138059966/1464745826629976084) — latest digest reinstatement thread.
---
### 2026-06-05: Decouple the index schema from `.well-known`; keep it a file with verbatim frontmatter and per-skill archives
**Status:** Proposed
**Context:** SEP-2640's index was originally specified as the [Agent Skills `.well-known` discovery index](https://github.com/agentskills/agentskills/pull/254) with a few MCP-specific differences (see 2026-06-02), so that a client consuming the HTTP `.well-known` index could consume `skill://index.json` with the same code. Peter Alexander reported being unable to confirm that the upstream `.well-known` agent-skills discovery spec will land: it has implementations in the wild but no governance momentum into the agentskills.io spec itself. Binding the SEP's index to a stalled upstream blocks progress, so the thread converged on defining the WG's own schema.
**Decision:**
- **Decouple the index schema from the `.well-known` discovery format.** The WG defines its own `skill://index.json` schema rather than mirroring upstream; alignment with `.well-known` is no longer a design constraint.
- **Keep the index as a file resource; do not elevate to a `skills/list` protocol method.** Elevation was considered — the principal motivation for a file had been matching `.well-known`, now removed — and set aside.
- **Each skill entry carries `url`, `digest`, a `frontmatter` object, and an `archives` array:**
- `frontmatter` is a *full, verbatim copy* of the skill's `SKILL.md` frontmatter. The schema designates no specific fields and neither includes nor excludes any — it is the whole block.
- `archives` is a list of `{ url, mediaType, digest }`, each describing one archive representation of the skill (e.g. `application/gzip`, `application/zip`).
- **Archives move from separate `type: "archive"` index entries (see 2026-04-19) to the per-skill `archives` array.** This amends the representation in that decision; archives remain a server-side packaging option, now expressed as a property of the skill rather than a sibling entry.
**Rationale:**
- *Decoupling.* The upstream `.well-known` format has real implementations but is not progressing through agentskills.io governance, and the SEP cannot wait on it; owning the schema unblocks the WG. The cost is divergence from a format that has consumers, so the schema should stay close enough to re-converge if upstream revives — but the hard dependency is removed. This retires the "mirror/realign with upstream" rationale that the 2026-04-19 (archives) and 2026-06-02 (digest) decisions invoked. Both still stand on their own merits — archives for dual-format distribution, digest for caching and cross-fetch consistency — but neither is justified by upstream alignment any longer.
- *File over method.* A `skills/list` method would make "skill" a named concept in the protocol, which conflicts with the skills-as-files philosophy of the SEP and of skills themselves. The capabilities a method would add — enumeration, pagination, change notification — are already available from resource improvements (a directory-style listing and `resources/list_changed`), so a method adds primitive surface without a matching gain. Keeping a file also leaves the index free to advertise non-skill entry types (e.g. primitive groups) as a progressive-discovery entry point later; that flexibility is a side effect of decoupling, explicitly not an in-scope expansion here.
- *Verbatim frontmatter.* `name` and `description` live in the frontmatter per the [Agent Skills spec](https://agentskills.io/specification#frontmatter); promoting them to top-level entry properties would require special-case logic to avoid duplicating them and would invite recurring debate over which fields belong in the index. Copying the full frontmatter block verbatim avoids both, keeps the index's skill semantics pinned to the agent-skills spec (no drift), and automatically covers client-side compatibility filtering (raised by Bloomberg): `compatibility`, `metadata`, and any other fields arrive by definition rather than being individually whitelisted.
- *Archives as a per-skill array.* Expressing archives as a property of the skill, rather than as separate entries, resolves the "archive + `SKILL.md` simultaneously" item without duplicating `name`/`description`/frontmatter across two entries, and lets a server offer several formats, each with its own `mediaType` and `digest`. Per-archive `digest` mirrors the entry-level digest's caching/consistency role for each packaged form.
**References:**
- [#skills-over-mcp-wg Discord](https://discord.com/channels/1358869848138059966/1464745826629976084) — index-schema thread, 2026-06-04/05 (Peter Alexander, Ola Hungerford, Sam Kothari).