From 33a0d12922ca1980038f4c4056b67f42d1f1cb2a Mon Sep 17 00:00:00 2001 From: olaservo Date: Mon, 20 Apr 2026 18:22:18 -0700 Subject: [PATCH 1/6] docs: add comparison of convention vs. new primitive approaches for skills in MCP --- docs/approaches.md | 6 ++- docs/convention-vs-new-primitive.md | 59 +++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+), 2 deletions(-) create mode 100644 docs/convention-vs-new-primitive.md diff --git a/docs/approaches.md b/docs/approaches.md index b00d516..c889793 100644 --- a/docs/approaches.md +++ b/docs/approaches.md @@ -17,7 +17,9 @@ Several design considerations are emerging from community discussion: The approaches below span a spectrum. At one end, skills become a first-class MCP primitive with dedicated protocol methods (Approach 1). At the other, existing primitives are used with documented conventions (Approach 6). A key question for this WG is whether convention can prove patterns before standardization — or whether the ecosystem needs protocol-level support to achieve reliable interoperability. These are not mutually exclusive; convention work can inform and de-risk a future protocol extension. -**Current status:** The convention approach (Approach 6) was pursued and quickly evolved into a formal Extensions Track SEP ([#69](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69)), building on convergence across 4+ independent `skill://` implementations. The SEP uses existing Resources primitives with zero protocol changes, positioning it between pure convention and a new primitive. See [#75](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/75) for tracking. +**Current status:** The convention approach (Approach 6) was pursued and quickly evolved into a formal Extensions Track SEP ([#69](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69)), building on convergence across 4+ independent `skill://` implementations. The SEP uses existing Resources primitives with zero protocol changes, positioning it between pure convention and a new primitive. See [#75](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/75) for tracking. A new primitive proposal ([PR #86](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/86)) has since been submitted, adding scoped primitives (tools, prompts, resources bundled inside a skill) as a differentiator from the convention approach. + +**For a structured comparison of the two active proposals, see [convention-vs-new-primitive.md](convention-vs-new-primitive.md).** ## 1. Skills as Distinct MCP Primitives @@ -35,7 +37,7 @@ Add Agent Skills as a first-class, discoverable primitive in MCP. A skill is a n - Progressive disclosure: clients load skill summaries at startup, fetch full instructions on demand - Mapping to existing SKILL.md format -**Status:** Draft, seeking sponsor. +**Status:** SEP-2076 was closed when the IG began exploring the resources-based approach. [PR #86](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/86) reopens the primitive path with `skills/list` and `skills/activate`, adding scoped primitives -- tools, prompts, resources, and nested skills that are bundled inside a skill and only become visible after activation. Authors: [Kurtis Van Gent](https://github.com/kurtisvg) and [Haoyu Wang](https://github.com/helloeve). **Community input:** diff --git a/docs/convention-vs-new-primitive.md b/docs/convention-vs-new-primitive.md new file mode 100644 index 0000000..3db0268 --- /dev/null +++ b/docs/convention-vs-new-primitive.md @@ -0,0 +1,59 @@ +# Convention vs. New Primitive + +> A recap of what to consider when evaluating how skills should be exposed over MCP. + +## Two Paths + +The community is exploring two broad approaches for skills over MCP: + +1. **Convention on existing primitives.** Skills exposed as `skill://` resources using existing MCP methods (`resources/list`, `resources/read`), formalized via the Skills Extension SEP ([#69 - draft extension](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69)). +2. **New protocol primitive.** Dedicated methods for listing and activating skills, a `skills` capability, and skill-specific notifications. An earlier proposal ([SEP-2076](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2076)) was closed when the IG began exploring the resources-based approach. [PR #86](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/86) reopens the primitive path with `skills/list` and `skills/activate`, adding scoped primitives (tools, prompts, resources, and nested skills) that are bundled inside a skill and only become visible after activation, rather than appearing in top-level lists. + +Note that these are not mutually exclusive -- convention can prove patterns that later inform a primitive. + +## Shared Work + +Both approaches delegate skill content format to the [Agent Skills specification](https://agentskills.io/specification). This means much of the implementation work is the same regardless of which path is chosen: + +| Work item | Convention approach | New primitive | +|---|---|---| +| Enumerate available skills | `skill://index.json` | `skills/list` | +| Model-driven loading | Host-provided `read_resource` tool | Dedicated `skills/activate` method | +| Multi-file skills | Sub-resources or archives | Same structural choice, different method names | +| Skill-level semantics (version, tools, invocation) | Frontmatter | Frontmatter | +| Transport-specific metadata | `_meta` | `_meta` or bespoke fields | +| Change notifications | `notifications/resources/list_changed` | `notifications/skills/list_changed` | + +The frontmatter/transport split is inherent to the decision (shared by both proposals) that the Agent Skills specification remains the authority for skill content. Neither approach eliminates it. That said, PR #86 partially shifts some frontmatter concerns into typed protocol fields -- `allowed-tools` becomes `contents.tools`, the SKILL.md body becomes an `instructions` string -- though other frontmatter fields (version, compatibility, invocation mode) don't have typed equivalents and would still rely on frontmatter. + +## Where They Differ + +**Protocol surface area.** A new primitive adds methods, capabilities, and notifications to the MCP spec. The convention approach uses infrastructure clients already need for resources. + +**Reusability.** The convention approach encourages clients to ship a host-provided `read_resource` tool, which unlocks model-driven access to any MCP resource -- not just skills. Several major clients already do this (Codex, Gemini CLI, Goose, fast-agent, Claude Code), and skills give the rest a concrete reason to follow. A skills-specific primitive solves skills but doesn't advance client support for the broader resources ecosystem. + +**Scoped primitives.** PR #86 introduces a new capability the convention approach does not have a direct equivalent for: tools, prompts, and resources that are structurally hidden from top-level lists and only surface when a skill is activated. This makes activation the gating mechanism for tool visibility, addressing tool bloat at the protocol level rather than through instructions. The convention approach relies on skill instructions to guide the model toward relevant tools, but all tools remain visible in `tools/list`. Whether this structural gating is necessary or whether other solutions are sufficient in practice is an open question -- one that implementation experience would help answer. + +**Identification.** The convention approach relies on URI schemes (`skill://`) and naming patterns for clients to identify skill resources. A new primitive provides structural identification -- if it came from `skills/list`, it's a skill. The convention is more flexible; the primitive is more explicit. + +**Reversibility.** Starting with convention and later adding a primitive is recoverable -- convention implementations continue to work and inform the primitive's design. Starting with a primitive and later changing direction puts more burden on client and server implementors. + +## Questions Worth Asking + +When evaluating which path is right for a particular use case or for the ecosystem broadly: + +1. **Is structural tool gating necessary, or are existing solutions for dynamic tool selection sufficient?** Scoped primitives (PR #86) hide tools from `tools/list` until activation. The convention approach delegates to other solutions for dynamic tool selection (such as tool search and other methods outside of the protocol itself). +2. **Would a new primitive accelerate client adoption, or add to the backlog?** Clients have already implemented support for resources (including model-facing tools for loading them). Several community projects have already been naturally using resources to represent skills. A new primitive is additional surface area on top of that. +3. **Do skills need protocol-level coordination with other primitives?** If skills need to interact with tools and prompts in ways that require dedicated protocol support (e.g., sampling with skill-aware tool visibility), convention may not be sufficient. + +## What Will Help the Debate + +Implementation experience on the convention approach -- what works, what's awkward, what genuinely fails. Friction reports with enough specificity to inform gap analysis. And engagement with both proposals, so that whichever path the ecosystem takes, the design is grounded in what implementers actually tried. + +## References + +- [SEP-2076: Skills as MCP Primitives](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2076) (closed) +- [PR #86: MCP-Native Skills](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/86) +- [PR #69: Skills Extension SEP](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69) +- [PR #2527: Recommend clients expose resource read to models](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2527) +- [Approaches](approaches.md) -- full landscape of approaches that the group has discussed. From 8977094da06aba2c05bf3326138dddb4f5432705 Mon Sep 17 00:00:00 2001 From: olaservo Date: Mon, 20 Apr 2026 18:27:04 -0700 Subject: [PATCH 2/6] docs: clarify limitations of server instructions in context management --- docs/approaches.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/approaches.md b/docs/approaches.md index c889793..dd08bb6 100644 --- a/docs/approaches.md +++ b/docs/approaches.md @@ -136,7 +136,10 @@ This pattern could enable loading primitives (tools) without the full "server" b Use server instructions as a pointer to a resource: "If you need to do X, fetch resource Y for further instructions." This defers loading skill content until needed, managing context more efficiently. -**Limitation:** May not work with off-the-shelf servers where you can't modify their instructions. +**Limitations:** + +- May not work with off-the-shelf servers where you can't modify their instructions. +- Server instructions may become more optional as a part of changes to MCP to make it [stateless](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575) ## 6. Official Convention as Intermediate Step From 39efa50762c11f7ce7b7b21a66996bafdb1c0433 Mon Sep 17 00:00:00 2001 From: olaservo Date: Mon, 20 Apr 2026 20:26:06 -0700 Subject: [PATCH 3/6] docs: update current status to clarify implementation details of convention approach --- docs/approaches.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/approaches.md b/docs/approaches.md index dd08bb6..d637534 100644 --- a/docs/approaches.md +++ b/docs/approaches.md @@ -17,7 +17,7 @@ Several design considerations are emerging from community discussion: The approaches below span a spectrum. At one end, skills become a first-class MCP primitive with dedicated protocol methods (Approach 1). At the other, existing primitives are used with documented conventions (Approach 6). A key question for this WG is whether convention can prove patterns before standardization — or whether the ecosystem needs protocol-level support to achieve reliable interoperability. These are not mutually exclusive; convention work can inform and de-risk a future protocol extension. -**Current status:** The convention approach (Approach 6) was pursued and quickly evolved into a formal Extensions Track SEP ([#69](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69)), building on convergence across 4+ independent `skill://` implementations. The SEP uses existing Resources primitives with zero protocol changes, positioning it between pure convention and a new primitive. See [#75](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/75) for tracking. A new primitive proposal ([PR #86](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/86)) has since been submitted, adding scoped primitives (tools, prompts, resources bundled inside a skill) as a differentiator from the convention approach. +**Current status:** The convention approach (Approach 6) was pursued and quickly evolved into a formal Extensions Track SEP ([#69](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69)), building on convergence across 4+ independent `skill://` and other Resource-based implementations. The SEP uses existing Resources primitives, positioning it between pure convention and a new primitive. A new primitive proposal ([PR #86](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/86)) has since been submitted, adding scoped primitives (tools, prompts, resources bundled inside a skill) as a differentiator from the convention approach. **For a structured comparison of the two active proposals, see [convention-vs-new-primitive.md](convention-vs-new-primitive.md).** From 1635b3e7f8a7b93815bb1476f86b09a1b8b471d7 Mon Sep 17 00:00:00 2001 From: olaservo Date: Mon, 20 Apr 2026 20:36:40 -0700 Subject: [PATCH 4/6] docs: refine explanation of scoped primitives and their impact on tool visibility --- docs/convention-vs-new-primitive.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/convention-vs-new-primitive.md b/docs/convention-vs-new-primitive.md index 3db0268..87a00b6 100644 --- a/docs/convention-vs-new-primitive.md +++ b/docs/convention-vs-new-primitive.md @@ -32,7 +32,7 @@ The frontmatter/transport split is inherent to the decision (shared by both prop **Reusability.** The convention approach encourages clients to ship a host-provided `read_resource` tool, which unlocks model-driven access to any MCP resource -- not just skills. Several major clients already do this (Codex, Gemini CLI, Goose, fast-agent, Claude Code), and skills give the rest a concrete reason to follow. A skills-specific primitive solves skills but doesn't advance client support for the broader resources ecosystem. -**Scoped primitives.** PR #86 introduces a new capability the convention approach does not have a direct equivalent for: tools, prompts, and resources that are structurally hidden from top-level lists and only surface when a skill is activated. This makes activation the gating mechanism for tool visibility, addressing tool bloat at the protocol level rather than through instructions. The convention approach relies on skill instructions to guide the model toward relevant tools, but all tools remain visible in `tools/list`. Whether this structural gating is necessary or whether other solutions are sufficient in practice is an open question -- one that implementation experience would help answer. +**Scoped primitives.** PR #86 introduces a new capability the convention approach does not have a direct equivalent for: tools, prompts, and resources that are structurally hidden from top-level lists and only surface when a skill is activated. This makes activation the gating mechanism for tool visibility, addressing tool bloat at the protocol level rather than through other solutions such as tool search and other dynamic tool loading mechanisms. Whether this structural gating is necessary to add to the protocol, or whether other solutions are sufficient in practice is still an open question. **Identification.** The convention approach relies on URI schemes (`skill://`) and naming patterns for clients to identify skill resources. A new primitive provides structural identification -- if it came from `skills/list`, it's a skill. The convention is more flexible; the primitive is more explicit. From 27194467543f500a44e6049f7d49912ece6bb4c4 Mon Sep 17 00:00:00 2001 From: olaservo Date: Mon, 20 Apr 2026 20:45:12 -0700 Subject: [PATCH 5/6] docs: enhance clarity on existing primitives and add reference to Primitive Grouping IG --- docs/convention-vs-new-primitive.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/convention-vs-new-primitive.md b/docs/convention-vs-new-primitive.md index 87a00b6..ee0d982 100644 --- a/docs/convention-vs-new-primitive.md +++ b/docs/convention-vs-new-primitive.md @@ -6,7 +6,7 @@ The community is exploring two broad approaches for skills over MCP: -1. **Convention on existing primitives.** Skills exposed as `skill://` resources using existing MCP methods (`resources/list`, `resources/read`), formalized via the Skills Extension SEP ([#69 - draft extension](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69)). +1. **Convention on existing primitives.** Skills exposed as indexed `skill://` or domain-specific resources using existing MCP methods (`resources/read`), formalized via the Skills Extension SEP ([#69 - draft extension](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69)). 2. **New protocol primitive.** Dedicated methods for listing and activating skills, a `skills` capability, and skill-specific notifications. An earlier proposal ([SEP-2076](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2076)) was closed when the IG began exploring the resources-based approach. [PR #86](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/86) reopens the primitive path with `skills/list` and `skills/activate`, adding scoped primitives (tools, prompts, resources, and nested skills) that are bundled inside a skill and only become visible after activation, rather than appearing in top-level lists. Note that these are not mutually exclusive -- convention can prove patterns that later inform a primitive. @@ -42,7 +42,7 @@ The frontmatter/transport split is inherent to the decision (shared by both prop When evaluating which path is right for a particular use case or for the ecosystem broadly: -1. **Is structural tool gating necessary, or are existing solutions for dynamic tool selection sufficient?** Scoped primitives (PR #86) hide tools from `tools/list` until activation. The convention approach delegates to other solutions for dynamic tool selection (such as tool search and other methods outside of the protocol itself). +1. **Is structural tool gating necessary, or are existing solutions for dynamic tool selection sufficient?** Scoped primitives (PR #86) hide tools from `tools/list` until activation. The convention approach delegates to other solutions for dynamic tool selection (such as tool search and other methods outside of the protocol itself). [The Primitive Grouping IG](https://github.com/modelcontextprotocol/experimental-ext-groupin) is also exploring general-purpose primitive grouping, which could address tool visibility at the protocol level independent of skills. 2. **Would a new primitive accelerate client adoption, or add to the backlog?** Clients have already implemented support for resources (including model-facing tools for loading them). Several community projects have already been naturally using resources to represent skills. A new primitive is additional surface area on top of that. 3. **Do skills need protocol-level coordination with other primitives?** If skills need to interact with tools and prompts in ways that require dedicated protocol support (e.g., sampling with skill-aware tool visibility), convention may not be sufficient. @@ -57,3 +57,4 @@ Implementation experience on the convention approach -- what works, what's awkwa - [PR #69: Skills Extension SEP](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69) - [PR #2527: Recommend clients expose resource read to models](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2527) - [Approaches](approaches.md) -- full landscape of approaches that the group has discussed. +- [Primitive Grouping IG Repo](https://github.com/modelcontextprotocol/experimental-ext-grouping) From 63c7b28dcb3221f9e79b6b5859ac8b7da6d799ef Mon Sep 17 00:00:00 2001 From: olaservo Date: Mon, 20 Apr 2026 20:47:56 -0700 Subject: [PATCH 6/6] docs: correct link to Primitive Grouping IG in evaluation criteria for skill exposure paths --- docs/convention-vs-new-primitive.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/convention-vs-new-primitive.md b/docs/convention-vs-new-primitive.md index ee0d982..f418cbf 100644 --- a/docs/convention-vs-new-primitive.md +++ b/docs/convention-vs-new-primitive.md @@ -42,7 +42,7 @@ The frontmatter/transport split is inherent to the decision (shared by both prop When evaluating which path is right for a particular use case or for the ecosystem broadly: -1. **Is structural tool gating necessary, or are existing solutions for dynamic tool selection sufficient?** Scoped primitives (PR #86) hide tools from `tools/list` until activation. The convention approach delegates to other solutions for dynamic tool selection (such as tool search and other methods outside of the protocol itself). [The Primitive Grouping IG](https://github.com/modelcontextprotocol/experimental-ext-groupin) is also exploring general-purpose primitive grouping, which could address tool visibility at the protocol level independent of skills. +1. **Is structural tool gating necessary, or are existing solutions for dynamic tool selection sufficient?** Scoped primitives (PR #86) hide tools from `tools/list` until activation. The convention approach delegates to other solutions for dynamic tool selection (such as tool search and other methods outside of the protocol itself). [The Primitive Grouping IG](https://github.com/modelcontextprotocol/experimental-ext-grouping) is also exploring general-purpose primitive grouping, which could address tool visibility at the protocol level independent of skills. 2. **Would a new primitive accelerate client adoption, or add to the backlog?** Clients have already implemented support for resources (including model-facing tools for loading them). Several community projects have already been naturally using resources to represent skills. A new primitive is additional surface area on top of that. 3. **Do skills need protocol-level coordination with other primitives?** If skills need to interact with tools and prompts in ways that require dedicated protocol support (e.g., sampling with skill-aware tool visibility), convention may not be sufficient.