From 2207100104c907df3cc0b2062458abc8617e7acf Mon Sep 17 00:00:00 2001 From: olaservo Date: Sun, 19 Apr 2026 13:51:07 -0700 Subject: [PATCH 1/3] docs: add ADR for filesystem as host-side implementation detail Record the proposed decision that skills served over MCP MUST function without a local filesystem, while hosts MAY materialize resources as an optimization, with unified resolution semantics required either way. --- docs/decisions.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/decisions.md b/docs/decisions.md index 42f300f..07b131d 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -134,3 +134,23 @@ 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: Filesystem is a host-side implementation detail + +**Status:** Proposed + +**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. + +**Decision:** The Skills Extension SEP treats the filesystem as a host-side implementation detail. Specifically: + +- A skill served over MCP MUST function correctly on hosts that have no access to a local filesystem. Skill content, supporting files, and relative-path resolution MUST be expressible entirely through MCP resource operations. +- Hosts MAY materialize skill resources into a local filesystem as a performance or compatibility optimization. +- Regardless of materialization strategy, relative-path resolution within a skill MUST produce the same result as URI-based resolution. A skill that references `references/guide.md` from its `SKILL.md` resolves to the same content whether the host loads it from disk or from `resources/read` on the originating server. + +**Rationale:** The value of filesystem-agnosticism is a consumer-side guarantee: a skill author writes one skill and knows it will run on any conformant host, from a cloud-code CLI with disk access to a stateless remote agent. Requiring MCP-served skills to work without a filesystem preserves this guarantee. Permitting host-side materialization preserves the use cases Peter flagged on March 24 (local server example from Jake, performance optimization for large skills, filesystem-native tooling integration). Requiring unified resolution semantics closes the gap that would otherwise make materialization a behavior-divergence source. The SEP's "Hosts: Unified Treatment" section already aspires to this at SHOULD level; this ADR promotes the semantic requirement to MUST while keeping the implementation a host choice. + +**References:** +- Archive distribution ADR — companion decision on packaging (forthcoming) +- [SEP PR #69](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/69), "Hosts: Unified Treatment of Filesystem and MCP Skills" section From 92e909f605543b80875d38c6e098ba050f270734 Mon Sep 17 00:00:00 2001 From: olaservo Date: Sun, 19 Apr 2026 14:08:55 -0700 Subject: [PATCH 2/3] docs: link companion archive distribution ADR (#83) --- docs/decisions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions.md b/docs/decisions.md index 07b131d..44feb13 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -152,5 +152,5 @@ For background on the ADR format, see [adr.github.io](https://adr.github.io/). **Rationale:** The value of filesystem-agnosticism is a consumer-side guarantee: a skill author writes one skill and knows it will run on any conformant host, from a cloud-code CLI with disk access to a stateless remote agent. Requiring MCP-served skills to work without a filesystem preserves this guarantee. Permitting host-side materialization preserves the use cases Peter flagged on March 24 (local server example from Jake, performance optimization for large skills, filesystem-native tooling integration). Requiring unified resolution semantics closes the gap that would otherwise make materialization a behavior-divergence source. The SEP's "Hosts: Unified Treatment" section already aspires to this at SHOULD level; this ADR promotes the semantic requirement to MUST while keeping the implementation a host choice. **References:** -- Archive distribution ADR — companion decision on packaging (forthcoming) +- [PR #83](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/83) — companion ADR on archive distribution - [SEP PR #69](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/69), "Hosts: Unified Treatment of Filesystem and MCP Skills" section From 0f82fe57ce458b9c270960b0a18c34ef66e6e685 Mon Sep 17 00:00:00 2001 From: olaservo Date: Sun, 19 Apr 2026 14:20:33 -0700 Subject: [PATCH 3/3] docs: update ADR 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 44feb13..934ebf8 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: Filesystem is a host-side implementation detail +### 2026-04-19: Filesystem is a host-side implementation detail **Status:** Proposed