docs: reinstate digest field in skill://index.json for caching and integrity (#96)

docs/decisions.md

@@ -199,3 +199,22 @@ For background on the ADR format, see [adr.github.io](https://adr.github.io/).
 - [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
+
+---
+
+### 2026-06-02: Reinstate the `digest` field in `skill://index.json`
+
+**Status:** Proposed
+
+**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.
+
+**Decision:** Reinstate the per-entry `digest` field in `skill://index.json`, matching the upstream Agent Skills discovery index (a `sha256:<hex>` content hash). The SEP's index-format description and field table are updated to add `skills[].digest`. With this change, the binding's only remaining divergences from the upstream index format are the `url` field's MCP-resource-URI semantics and the MCP-specific `mcp-resource-template` `type` value; `digest` and `archive` both align with upstream.
+
+**Rationale:** Caching is the practical driver. Absent a resource-level freshness mechanism in the current spec, the index digest is the client's primary signal for whether cached skill content is still current; skill payloads are large enough that blindly refetching on every index poll is wasteful. Notably, the caching argument that was marginal over HTTP — where we resisted the digest because standard HTTP caching already exists — is the one that carries the decision over MCP, precisely because MCP has no equivalent caching layer or `resources/metadata`/ETag facility yet. The digest may become redundant once the protocol grows such a facility, at which point this binding can defer to it; but omitting it now leaves clients with no freshness signal within the reading model this SEP defines, a near-term cost too large to accept for the sake of avoiding an eventual redundancy. A secondary benefit raised in discussion is tamper and drift detection: a client can compare the advertised digest against cached content and warn the user when a skill has changed — including the case where an agent has modified skill content locally — for example on a `/skills list` view. A further consideration, raised by Jonathan Hefner in both the upstream thread and the June 2 session, is consistency across interdependent skills: when a client reads the index and then fetches several skills in sequence, a digest lets it detect content shifting underneath it mid-fetch and retry. The original integrity argument for *omitting* the field still holds — integrity is not the digest's job over a single authenticated connection — but integrity was never the reason to *include* it; caching is. Finally, reinstating the field realigns the binding with the upstream discovery format, consistent with the SEP's framing as a transport binding that delegates format to agentskills.io — the same principle the SEP already invokes to permit `archive` distribution (see the related decision below).
+
+**References:**
+- [SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) — Skills Extension; canonical text on the `sep/skills-extension` branch. The "Enumeration via `skill://index.json`" section currently states `digest` is omitted and the index field table has no `digest` row — both to be updated.
+- [agentskills/agentskills#254](https://github.com/agentskills/agentskills/pull/254) — upstream Agent Skills well-known discovery index defining the per-entry `digest` (`sha256:<hex>`) for integrity and caching; includes the Peter Alexander / Jonathan Hefner thread weighing the same trade-off over HTTP.
+- [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.