From 4d96a40cf45795df115e3c9368cba7ca6b02dace Mon Sep 17 00:00:00 2001 From: olaservo Date: Wed, 4 Feb 2026 06:21:47 -0700 Subject: [PATCH] Enhance documentation with key elements and community input for skills approach and open questions --- docs/approaches.md | 25 +++++++++++++++++++++++++ docs/open-questions.md | 6 ++++++ 2 files changed, 31 insertions(+) diff --git a/docs/approaches.md b/docs/approaches.md index 1ecfc52..ee32e31 100644 --- a/docs/approaches.md +++ b/docs/approaches.md @@ -16,6 +16,20 @@ Add Agent Skills as a first-class, discoverable primitive in MCP. A skill is a n **Author:** [Yu Yi](https://github.com/erain) +**Key elements:** + +- New protocol methods: `skills/list` and `skills/get` +- A `skills` server capability +- A `notifications/skills/list_changed` notification +- Progressive disclosure: clients load skill summaries at startup, fetch full instructions on demand +- Mapping to existing SKILL.md format + +**Status:** Draft, seeking sponsor. + +**Community input:** + +> "My main motivation is: we have so many MCP servers already available, how can we leverage them to distribute Skills?" — [Yu Yi](https://github.com/erain) + ## 2. Skills as Registry Metadata Add skill references to MCP registry entries so users know to install associated skills alongside servers. @@ -39,6 +53,10 @@ Expose skills via tools like `list_skills` and `read_skills`. Server instruction - [skilljack-mcp](https://github.com/olaservo/skilljack-mcp) - [skills-over-mcp](https://github.com/keithagroves/skills-over-mcp) +**Community input:** + +> "I wonder if a better way to approach this with existing primitives is by implementing a Skill() tool and establishing this as a standard recommendation for servers and clients, rather than adding a new primitive to MCP." — [Ola Hungerford](https://github.com/olaservo) + This approach may also: - Expose skills as MCP resources @@ -80,3 +98,10 @@ A documented "MCP Skills Convention" as a middle path between ad-hoc experiments - 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." + +**Advantages of the convention approach:** + +- Since MCP supports dynamically updating tools, the latest skills manifest can be included in tool descriptions +- Skills can also be modeled as Resources (using `skill://` URI) for application-controlled access +- Prompts could support explicit skill invocation +- The convention and protocol extension approaches are not mutually exclusive — convention can prove patterns before standardization diff --git a/docs/open-questions.md b/docs/open-questions.md index fec6b4c..6eb05b4 100644 --- a/docs/open-questions.md +++ b/docs/open-questions.md @@ -86,6 +86,12 @@ Note: Some apps like Claude Code have started to indicate in the skill frontmatt > "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) +**Community input:** + +> "I'd like Skills to be 'more official' than generic resources — which could be ANYTHING. More specifically, skill as a separate spec may advance in the near future, e.g. versioning etc., so having MCP as an official distribution mechanism and support it in the current and future form is important." — [Yu Yi](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2076#discussion_r2747846895) + +> "If the conclusion is 'just use resources', I am fine with that direction too — but then we should standardize a way to identify and list workflow resources as 'skills' so clients can reliably surface them (otherwise we are back to out-of-band conventions)." — [sebthom](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/2167#issuecomment-3824771018) + ## 13. What is the optimal relationship between skills and MCP? 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.