From 6aa5ba7b2f3acf99ea3de32a877e979ed782bf45 Mon Sep 17 00:00:00 2001 From: olaservo Date: Mon, 13 Apr 2026 05:30:22 -0700 Subject: [PATCH 1/3] Update docs to reflect convention-to-SEP evolution The "MCP Skills Convention v0.1" (issue #43, now closed) graduated into the draft Skills Extension SEP (PR #69). Update docs to reflect this: - README: work tracking row now shows SEP with Peter as champion, success criteria notes the SEP as current direction - approaches.md: status note under Central Tension, status banner on Approach 6 noting it graduated to the SEP - skill-uri-scheme.md: status updated from Draft to incorporated into SEP, removed outdated "MCP Skills Convention" phrasing Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 4 ++-- docs/approaches.md | 6 +++++- docs/skill-uri-scheme.md | 4 ++-- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 8dcab44..8582685 100644 --- a/README.md +++ b/README.md @@ -102,10 +102,10 @@ This IG may propose becoming a Working Group if: | Experimental findings repo | Proposed | Ola | Dedicated repo for implementations and evaluation results | | SEP-2076 review | In Progress | Yu Yi | Skills as first-class primitive proposal | | Registry skills.json proposal | In Progress | Ozz | Skills metadata in registry schema | -| MCP Skills Convention v0.1 | Proposed | TBD | Documented pattern (not spec) for skills over existing primitives | +| Skills Extension SEP | In Review | Peter (@pja-ant) | Extensions Track SEP for `skill://` resource convention ([#75](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/75)); evolved from Convention v0.1 (#43) | ## Success Criteria - **Short-term:** Documented consensus on requirements and evaluation of existing approaches -- **Medium-term:** Clear recommendation (convention vs. protocol extension vs. both) +- **Medium-term:** Clear recommendation (convention vs. protocol extension vs. both) — the draft [Skills Extension SEP](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69) represents the IG's current direction: a formal extension using existing Resources primitives - **Long-term:** Interoperable skill distribution across MCP servers and clients diff --git a/docs/approaches.md b/docs/approaches.md index 1ee2180..66757f3 100644 --- a/docs/approaches.md +++ b/docs/approaches.md @@ -17,6 +17,8 @@ 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 IG 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. + ## 1. Skills as Distinct MCP Primitives Add Agent Skills as a first-class, discoverable primitive in MCP. A skill is a named bundle of instructions plus references to tools, prompts, and resources that together teach an agent how to perform a domain-specific workflow. @@ -131,6 +133,8 @@ Use server instructions as a pointer to a resource: "If you need to do X, fetch ## 6. Official Convention as Intermediate Step +> **Status:** This approach was pursued and graduated into the draft [Skills Extension SEP](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69) ([#75](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/75)). The SEP formalizes the convention as an Extensions Track specification using existing Resources primitives — zero protocol changes, backward compatible. Content format is delegated to [agentskills.io](https://agentskills.io/specification). The text below is preserved as historical context for how this approach was originally framed. + A documented "MCP Skills Convention" as a middle path between ad-hoc experiments and protocol extension. This could: - Define well-known URI schemes or naming patterns (e.g., resources matching `**/SKILL.md`). See [Skill URI Scheme Proposal](skill-uri-scheme.md) for a detailed survey and recommendation. @@ -139,7 +143,7 @@ A documented "MCP Skills Convention" as a middle path between ad-hoc experiments - Be documented in MCP docs as a "Pattern" — not in protocol schema, but officially recommended - Allow data gathering on adoption before considering protocol-level changes -This mirrors how other ecosystems (e.g., Kubernetes) graduate patterns: start as convention, prove value, then formalize. Could be a concrete IG deliverable: "MCP Skills Convention v0.1." +This mirrors how other ecosystems (e.g., Kubernetes) graduate patterns: start as convention, prove value, then formalize. **Advantages of the convention approach:** diff --git a/docs/skill-uri-scheme.md b/docs/skill-uri-scheme.md index 3301e12..cf4a4c7 100644 --- a/docs/skill-uri-scheme.md +++ b/docs/skill-uri-scheme.md @@ -3,13 +3,13 @@ > Proposed convention for identifying skill resources over MCP. **Issue:** [#44](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/44) -**Status:** Draft +**Status:** Incorporated into the draft [Skills Extension SEP](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69). This survey informed the SEP's URI scheme design; see also [PR #70](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/70) for subsequent refinements (multi-segment paths, path-name decoupling). --- ## Summary -This document surveys existing URI patterns for skill resources across implementations, analyzes their trade-offs, and proposes a recommended `skill://` URI scheme for the MCP Skills Convention. +This document surveys existing URI patterns for skill resources across implementations, analyzes their trade-offs, and proposes a recommended `skill://` URI scheme for skill resources over MCP. ## Survey of Existing Patterns From cb6df6ab2c22ea532ccb102b5f1498bdc4e9840a Mon Sep 17 00:00:00 2001 From: olaservo Date: Mon, 13 Apr 2026 06:38:56 -0700 Subject: [PATCH 2/3] Add cross-reference links from docs to tracking issues Link open questions, approaches, use cases, and experimental findings to their corresponding GitHub issues so readers can find the active discussion without hunting through the issues list. - open-questions.md: "Tracked in" and "See also" links on Q1, Q4, Q5, Q7, Q8, Q12, Q13 - approaches.md: "See also" links on Approach 3, distribution section, and sampling variant - use-cases.md: "See also" links on UC3 (multi-server) and UC4 (progressive disclosure) - experimental-findings.md: contribution template note and skill reliability link Supersedes #56. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/approaches.md | 5 +++++ docs/experimental-findings.md | 4 ++++ docs/open-questions.md | 16 ++++++++++++++++ docs/use-cases.md | 4 ++++ 4 files changed, 29 insertions(+) diff --git a/docs/approaches.md b/docs/approaches.md index 66757f3..4c08373 100644 --- a/docs/approaches.md +++ b/docs/approaches.md @@ -62,6 +62,7 @@ Examples: - Expose skills via tools like `list_skills` and `read_skills`. Server instructions can direct the agent to call the skill tool first. - Expose skills as resources (e.g. skill://...), which can also be exposed through tools +**See also:** [#41](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/41) — Server-side reference implementation, [#55](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/55) — Recommended _meta keys for skill resources **Implementations:** @@ -99,6 +100,8 @@ Several design considerations have been suggested in community discussion and pr - **Git-based distribution:** Versioned distribution via git (tags, pinned refs) can be viable without a formal registry. Clare Liguori (AWS) noted that Terraform operated without a formal registry for a long time — Feb 26 office hours. - **Domain-level discovery:** The [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) proposes `/.well-known/skills/` for organizations to publish skills at predictable URLs with content integrity (SHA-256 digests). This is complementary to MCP — it handles discovery and distribution while MCP handles runtime consumption. +**See also:** [#44](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/44) — Define well-known URI schemes and naming patterns for skill resources + **Community input:** > "Installless/temporary/ephemeral skill availability while server is installed feels like a good pattern. Clients could optionally offer to permanently install." — [Sam Morrow](https://github.com/SamMorrowDrums) (GitHub), via Discord @@ -115,6 +118,8 @@ Instead of exposing skill tools to the main agent, use MCP's Sampling with Tools **Source:** [jbnitorum](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2076#issuecomment-3806151745) +**See also:** [#42](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/42) — Test skills-via-sampling approach + ## 4. Gateway/Composition Pattern A gateway-style server that provides a group of MCPs as one, ensuring they get requisite configuration and instructions to work in harmony. diff --git a/docs/experimental-findings.md b/docs/experimental-findings.md index 01cf717..2e2ea9e 100644 --- a/docs/experimental-findings.md +++ b/docs/experimental-findings.md @@ -1,5 +1,7 @@ # Experimental Findings +> **Contributing findings?** See [#50](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/50) for the contribution template proposal. + ## McpGraph: Skills in MCP Server Repo **Repo:** [TeamSparkAI/mcpGraph](https://github.com/TeamSparkAI/mcpGraph) @@ -86,3 +88,5 @@ Multiple community members have independently reported that models do not reliab > "Skills are ephemeral and/or time decaying — it clicks once and then give it some time and they lose the plot." — Kryspin (qcompute), via Discord > "I've seen lazy load skills with various degrees of success, actually looks like it might be model specific… [best pattern is] putting them in with a subagent that similarly named or mentions the topic in their description." — Kryspin (qcompute), via Discord + +**See also:** [#37](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/37) — Compare skill delivery mechanisms: file-based vs MCP-based diff --git a/docs/open-questions.md b/docs/open-questions.md index 29d2687..3339e7b 100644 --- a/docs/open-questions.md +++ b/docs/open-questions.md @@ -2,6 +2,8 @@ ## 1. Is this a registry problem or an MCP server problem? +> **See also:** [#44](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/44) — Define well-known URI schemes and naming patterns for skill resources + Should skills be discoverable through registry metadata ("if you install this server, also install this skill") or contained within the MCP server itself? A third option is emerging: domain-level discovery via `/.well-known/skills/` (see [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc)). This decouples skill discovery from both registries and MCP servers — an organization publishes skills at a predictable URL on its own domain. This could complement MCP-level discovery rather than replace it: `.well-known` handles "find available skills," MCP handles "load and use them at runtime." @@ -18,6 +20,8 @@ Or is the separation between "primitive server" and "skill that uses the primiti ## 4. How should skills relate to multiple servers? +> **Tracked in:** [#39](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/39) — Research skill dependency declaration and host-mediated resolution + A skill orchestrating tools from several servers can't live in any single server's instructions. **Related:** [agentskills/agentskills#110](https://github.com/agentskills/agentskills/issues/110) — Discusses how skills should declare their tool/server dependencies. The lack of explicit dependency configuration makes multi-server skill execution unpredictable: if required servers and tools aren't already loaded, the skill can't reliably execute. @@ -36,6 +40,9 @@ The agentskills.io spec currently has a freeform [compatibility field](https://a ## 5. Do clients actually leverage skills when presented via MCP? +> **Tracked in:** [#38](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/38) — Survey client resource-loading support across major MCP clients +> **See also:** [#37](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/37) — Compare skill delivery mechanisms: file-based vs MCP-based + Early experiments suggest they do, but more rigorous testing is needed. **Community input:** @@ -48,10 +55,14 @@ Early experiments suggest they do, but more rigorous testing is needed. ## 7. What would MCP have had to get right for skills to have been shipped over MCP from the beginning? +> **See also:** [#47](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/47) — Create evaluation matrix mapping approaches to requirements + — [Keith Groves](https://github.com/keithagroves) ## 8. What could MCP reasonably change so that it will be the obvious choice for new formats? +> **See also:** [#54](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/54) — The case for custom metadata instead of a URI convention + — [Keith Groves](https://github.com/keithagroves) **Community input:** @@ -94,6 +105,8 @@ Note: Some apps like Claude Code have started to indicate in the skill frontmatt ## 12. Why not just resources? +> **See also:** [#54](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/54) — The case for custom metadata instead of a URI convention, [#55](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/55) — Define recommended _meta keys for skill resources + **Core Maintainer input:** > "Why not just resources? That feels like the obvious implementation since skills are just files and resources already exist to expose files. i.e. just expose skills as resources the same as they're currently exposed on the filesystem and then just use the existing Agent Skills specification — client can find skills using resources/list to find SKILL.md files." — [Peter Alexander](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2076#discussion_r2736299627) @@ -108,6 +121,9 @@ See also [Approaches](approaches.md) for more notes on using resources. ## 13. What is the optimal relationship between skills and MCP? +> **Tracked in:** [#75](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/75) — Skills Extension SEP +> **See also:** [#47](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/47) — Create evaluation matrix mapping approaches to requirements + Skills already work as simple files that agents load directly. Adding MCP to the process should provide clear value beyond what standalone skills already offer. **Community input:** diff --git a/docs/use-cases.md b/docs/use-cases.md index 8d5cc05..1d3334f 100644 --- a/docs/use-cases.md +++ b/docs/use-cases.md @@ -30,6 +30,8 @@ Skills that leverage tools from multiple off-the-shelf servers where you can't ( Beyond multi-server tool orchestration, skills themselves may be composable — one skill depending on another skill's output or behavior. This extends the dependency model beyond tool availability to skill availability, and raises questions about declarative dependency metadata. See [Open Question 4](open-questions.md#4-how-should-skills-relate-to-multiple-servers) for the emerging proposal on host-mediated dependency resolution. +**See also:** [#39](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/39) — Skill dependency declaration, [#45](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/45) — Worked examples for multi-server composition + ## 4. Progressive Disclosure Skills broken into linked sets of files for effective context management, loaded progressively as the agent needs them rather than all at once. @@ -46,6 +48,8 @@ Skills broken into linked sets of files for effective context management, loaded **Related:** [Anthropic's guidance on progressive disclosure](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) +**See also:** [#45](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/45) — Worked examples for progressive disclosure, [#40](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/40) — Client-side reference implementation for model-driven resource loading + ## 5. Server-Skill Pairing Servers that are difficult or impossible to use effectively without an accompanying skill. From ef8e52e85661428897f5fe18e8c426027d7d7553 Mon Sep 17 00:00:00 2001 From: olaservo Date: Tue, 14 Apr 2026 06:15:40 -0700 Subject: [PATCH 3/3] Slim README to link to charter for governance content The charter at modelcontextprotocol.io/community/skills-over-mcp/charter is the canonical source for mission, scope, membership, work items, and success criteria. Remove duplicate sections from README and link to the charter instead, reducing drift risk. README now focuses on repo-specific content: - Experimental banner - Quick links (charter, project board, meeting notes, Discord) - Why Skills Over MCP? (entrypoint) - Problem Statement (brief, links to docs/) - Repository Contents table - Contributing link Removed (now in charter): Mission, Scope, Stakeholder Groups, Facilitators, Lifecycle, Work Tracking, Success Criteria. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 79 +++++-------------------------------------------------- 1 file changed, 6 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 8582685..8a0bfa3 100644 --- a/README.md +++ b/README.md @@ -2,25 +2,10 @@ > ⚠️ **Experimental** — This repository is an incubation space for the Skills Over MCP Interest Group. Contents are exploratory and do not represent official MCP specifications or recommendations. -## Mission - -This Interest Group explores how "[agent skills](https://agentskills.io/)" (rich, structured instructions for agent workflows) can be discovered and consumed through MCP. Native skills support in host applications demonstrates strong demand, but the community hasn't aligned on whether existing MCP primitives suffice or what conventions to standardize. Cross-cutting collaboration is needed because solutions touch the protocol spec, registry schema, SDK implementations, and client behavior. - -## Scope - -### In Scope - -- **Requirements gathering:** Documenting use cases, constraints, and gaps in current MCP primitives for skill distribution -- **Pattern exploration:** Testing and evaluating approaches (skills as tools, resources, registry metadata, protocol primitives) -- **Coordination:** Bridging discussions across Registry WG, Agents WG, and external stakeholders (Agent Skills spec owners, FastMCP, PydanticAI) -- **Proof of concepts:** Maintaining a shared repo of reference implementations and experimental findings - -### Out of Scope - -- **Approving spec changes:** This IG does not have authority to approve protocol changes; recommendations flow through the SEP process -- **Registry schema decisions:** Coordinate with Registry WG; this IG explores requirements but doesn't own the schema -- **Client implementation mandates:** We can document patterns but not require specific client behavior -- **Plugin/bundle packaging:** Some use cases surface a broader need for installable bundles (skills + servers + subagents + configuration as a single artifact). How to solve for this is out of scope. +**Charter:** [modelcontextprotocol.io/community/skills-over-mcp/charter](https://modelcontextprotocol.io/community/skills-over-mcp/charter) — mission, scope, membership, active work items, and success criteria. +**Project board:** [Skills Over MCP IG](https://github.com/orgs/modelcontextprotocol/projects/38/views/1) +**Meeting notes:** [Skills Over MCP IG discussions](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/categories/meeting-notes-skills-over-mcp-ig) +**Discord:** [#skills-over-mcp-ig](https://discord.com/channels/1358869848138059966/1464745826629976084) ## Why Skills Over MCP? @@ -53,59 +38,7 @@ See [problem-statement.md](docs/problem-statement.md) for full details. | [Experimental Findings](docs/experimental-findings.md) | Results from implementations and testing | | [Related Work](docs/related-work.md) | SEPs, implementations, and external resources | | [Decision Log](docs/decisions.md) | Record of key decisions with context and rationale | -| [Meeting Notes](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/categories/meeting-notes-skills-over-mcp-ig) | Published after each working session | -| [Contributing](CONTRIBUTING.md) | How to participate | - -## Stakeholder Groups - -| Group | Overlap | -| :--- | :--- | -| Agents WG | How agents consume server metadata, skill activation | -| Registry WG | Skills discovery/distribution, registry schema changes | -| Primitive Grouping WG | Progressive disclosure patterns | - -## Facilitators - -| Role | Name | Organization | GitHub | -| :--- | :--- | :--- | :--- | -| Maintainer | Ola Hungerford | Nordstrom / MCP Maintainer | [@olaservo](https://github.com/olaservo) | -| Facilitator | Bob Dickinson | TeamSpark.ai | [@BobDickinson](https://github.com/BobDickinson) | -| Facilitator | Rado | Stacklok / MCP Maintainer | [@rdimitrov](https://github.com/rdimitrov) | -| Facilitator | Yu Yi | Google | [@erain](https://github.com/erain) | -| Facilitator | Ozz | Stacklok | [@JAORMX](https://github.com/JAORMX) | -| Facilitator | Kaxil Naik | Astronomer / Apache Airflow PMC | [@kaxil](https://github.com/kaxil) | - -## Lifecycle - -**Current Status: Active Exploration** - -### Graduation Criteria (IG → WG) - -This IG may propose becoming a Working Group if: - -- Clear consensus emerges on an approach requiring sustained spec work -- Cross-cutting coordination requires formal authority delegation -- At least two Core Maintainers sponsor WG formation - -### Retirement Criteria - -- Problem space resolved (conventions established, absorbed into other WGs) -- Insufficient participation to maintain momentum -- Community consensus that skills don't belong in MCP protocol scope - -## Work Tracking - -| Item | Status | Champion | Notes | -| :--- | :--- | :--- | :--- | -| Requirements alignment | In Progress | All facilitators | Review approaches, identify common requirements and gaps | -| Agent Skills spec coordination | In Progress | Ola | Use [agentskills/agentskills Discussions](https://github.com/agentskills/agentskills/discussions) for intersecting topics; see [contributing guide](https://github.com/agentskills/agentskills/blob/main/CONTRIBUTING.md) | -| Experimental findings repo | Proposed | Ola | Dedicated repo for implementations and evaluation results | -| SEP-2076 review | In Progress | Yu Yi | Skills as first-class primitive proposal | -| Registry skills.json proposal | In Progress | Ozz | Skills metadata in registry schema | -| Skills Extension SEP | In Review | Peter (@pja-ant) | Extensions Track SEP for `skill://` resource convention ([#75](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/75)); evolved from Convention v0.1 (#43) | -## Success Criteria +## Contributing -- **Short-term:** Documented consensus on requirements and evaluation of existing approaches -- **Medium-term:** Clear recommendation (convention vs. protocol extension vs. both) — the draft [Skills Extension SEP](https://github.com/modelcontextprotocol/experimental-ext-skills/pull/69) represents the IG's current direction: a formal extension using existing Resources primitives -- **Long-term:** Interoperable skill distribution across MCP servers and clients +See [CONTRIBUTING.md](CONTRIBUTING.md) for how to participate.