diff --git a/README.md b/README.md index 48fe900..81a32eb 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ MCP servers give agents tools, but tools alone are insufficient for complex work Skills are *context*, and MCP is a *context protocol*. Agents already connect to remote services over MCP to get tools — they can get the know-how to use those tools through the same channel. A remote MCP server can serve both its tools and the instructions for using them together, as a single atomic unit. This also enables automatic discovery (connect to a server, find its skills), dynamic updates (server-side changes flow without reinstall), multi-server composition (skills orchestrating tools across servers), and enterprise distribution (RBAC, multi-tenant, version-adaptive content) — all through infrastructure MCP servers already provide. -See [why-and-when.md](docs/why-and-when.md) for the full value proposition and a guide for when MCP distribution applies vs. simpler alternatives. +See [why-and-when.md](docs/why-and-when.md) for the full value proposition and a guide for when MCP distribution applies vs. simpler alternatives. For an accessible external framing of the premise, see Angie Jones's ["Skills Over MCP"](https://aaif.io/blog/skills-over-mcp/) (Agentic AI Foundation) — "ship the manual with the product." ## Problem Statement diff --git a/docs/approaches.md b/docs/approaches.md index c361dfb..875976e 100644 --- a/docs/approaches.md +++ b/docs/approaches.md @@ -1,5 +1,7 @@ # Approaches Being Explored +> ℹ️ The design space has largely converged on the convention approach (Approach 6), now formalized as [SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640). This document is kept as a map of the alternatives that were considered; for the current direction, see the SEP. + > These are not mutually exclusive solutions. ## Design Principles diff --git a/docs/experimental-findings.md b/docs/experimental-findings.md index 2e2ea9e..6761b8b 100644 --- a/docs/experimental-findings.md +++ b/docs/experimental-findings.md @@ -1,5 +1,7 @@ # Experimental Findings +> ℹ️ **This document is not actively maintained.** It captures a snapshot of early findings. Current discussion and decisions are tracked in the [meeting notes discussions](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/categories/meeting-notes-skills-over-mcp-wg), [Discord #skills-over-mcp-wg](https://discord.com/channels/1358869848138059966/1464745826629976084), and on the [SEP-2640 PR](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640). + > **Contributing findings?** See [#50](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/50) for the contribution template proposal. ## McpGraph: Skills in MCP Server Repo diff --git a/docs/open-questions.md b/docs/open-questions.md index e4c4881..b56a1e7 100644 --- a/docs/open-questions.md +++ b/docs/open-questions.md @@ -1,5 +1,7 @@ # Open Questions +> ℹ️ **This document is not actively maintained.** It captures a snapshot of early discussion. Current open questions and decisions are tracked in the [meeting notes discussions](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/categories/meeting-notes-skills-over-mcp-wg), [Discord #skills-over-mcp-wg](https://discord.com/channels/1358869848138059966/1464745826629976084), and on the [SEP-2640 PR](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640). + ## 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 diff --git a/docs/related-work.md b/docs/related-work.md index 76eba6f..708a127 100644 --- a/docs/related-work.md +++ b/docs/related-work.md @@ -67,6 +67,8 @@ Projects that illustrate the problem space or use adjacent patterns. - **Anthropic's guidance on progressive disclosure:** [Equipping agents for the real world with agent skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) - **"MCP and Skills: Why Not Both?"** (Kurtis Van Gent): [kvg.dev/posts/20260125-skills-and-mcp/](https://kvg.dev/posts/20260125-skills-and-mcp/) — Frames MCP (connectivity) and Skills (context saturation) as complementary; discusses hybrid approaches +- **"Skills Over MCP"** (Angie Jones, Agentic AI Foundation): [aaif.io/blog/skills-over-mcp/](https://aaif.io/blog/skills-over-mcp/) — "Ship the manual with the product": bundle Agent Skills with MCP servers so agents get both tools and instructional guidance. Describes the working group's proposal (SEP-2640) — `skill://` resources, a `skill://index.json` catalog for lightweight discovery, and progressive disclosure of full instructions on demand +- **"Progressive Discovery in MCP, Part 2"** (Sam Morrow, GitHub MCP Server maintainer): [sam-morrow.com/blog/progressive-discovery-in-mcp-part-2](https://sam-morrow.com/blog/progressive-discovery-in-mcp-part-2) — Advocates skills-based progressive discovery to solve tool bloat: `skill://` resources, deferred tool loading via provider mechanisms (Anthropic `tool_reference`, OpenAI `defer_loading`), and the `io.modelcontextprotocol/tools` metadata namespace. Grounded in lessons from GitHub's MCP Server (100+ tools, 12M weekly calls) - **Conceptual spec visualization** (Keith Groves): [enact-465fb1fc.mintlify.app/specification/draft/server/skills](https://enact-465fb1fc.mintlify.app/specification/draft/server/skills) — "What if" exploration - **llms.txt convention:** [llmstxt.org](https://llmstxt.org/) — Convention for making documentation LLM-accessible; used by [MCPDoc](https://github.com/langchain-ai/mcpdoc) in a way similar to how skills work - **AWS Agent SOPs:** [docs.aws.amazon.com/…/agent-sops](https://docs.aws.amazon.com/aws-mcp/latest/userguide/agent-sops.html) — Pre-built operational workflows as skill-like guidance diff --git a/docs/sep-draft-skills-extension.md b/docs/sep-draft-skills-extension.md index 1e972a4..2b97c17 100644 --- a/docs/sep-draft-skills-extension.md +++ b/docs/sep-draft-skills-extension.md @@ -8,7 +8,7 @@ - **Extension Identifier**: `io.modelcontextprotocol/skills` - **PR**: [#2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) -> **NOTE:** This SEP has been submitted to the main MCP repository as [SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640); future review and comments happen there. This repo-local copy is the working draft maintained by the [Skills Over MCP Working Group](https://github.com/modelcontextprotocol/experimental-ext-skills) and may be revised as upstream review feedback is incorporated. Additional discussion welcome via [GitHub Issues](https://github.com/modelcontextprotocol/experimental-ext-skills/issues) or [Discord #skills-over-mcp-wg](https://discord.com/channels/1358869848138059966/1464745826629976084). +> ℹ️ **This repo-local copy is not actively maintained and may be out of date.** The canonical version of this SEP lives on the main MCP repository as [SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) — refer to it for the current text, and direct review and comments there. Additional discussion welcome via [GitHub Issues](https://github.com/modelcontextprotocol/experimental-ext-skills/issues) or [Discord #skills-over-mcp-wg](https://discord.com/channels/1358869848138059966/1464745826629976084). ## Abstract