diff --git a/docs/approaches.md b/docs/approaches.md new file mode 100644 index 0000000..f3e3d95 --- /dev/null +++ b/docs/approaches.md @@ -0,0 +1,72 @@ +# Approaches Being Explored + +> These are not mutually exclusive solutions. + +## 1. Skills as 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. + +**Proposal:** [SEP-2076](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2076) + +**Author:** [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. + +**Implementations:** +- [Ozz](https://github.com/JAORMX) started a discussion around [skills.json format proposal](https://github.com/modelcontextprotocol/registry/discussions/895) +- NimbleBrain has implemented this via a `skill` field in registry `_meta`, supporting `.skill` artifact bundles (ZIP containing SKILL.md + manifest.json). + - https://github.com/NimbleBrainInc/skills + - [registry.nimbletools.ai](https://registry.nimbletools.ai/) + +## 3. Skills as Tools + +Expose skills via tools like `list_skills` and `read_skills`. Server instructions can direct the agent to call the skill tool first. + +**Implementations:** + +- [skilljack-mcp](https://github.com/olaservo/skilljack-mcp) +- [skills-over-mcp](https://github.com/keithagroves/skills-over-mcp) + +This approach may also: + +- Expose skills as MCP resources +- Use Prompts for explicit skill invocation +- Use `tools/listChanged` and other notifications for dynamic updates without server re-initialization + +### Variant: Skills via Sampling + +Instead of exposing skill tools to the main agent, use MCP's Sampling with Tools capability ([SEP-1577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1577)). The server requests a sampling call with skill-specific tools (`read_skill_md`, `execute_script`, etc.) that are only visible during that sampling request. This keeps skill tools hidden from the main agent, addressing tool bloat. The server orchestrates skill execution; the main agent just sees the result. + +**Caveat:** Sampling has limited client support currently. + +**Source:** [jbnitorum](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2076#issuecomment-3806151745) + +## 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. + +This pattern could enable loading primitives (tools) without the full "server" boundary. + +**Community input:** + +> "MCP repos can also be used as libraries... a gateway in same language as bundle servers could also load primitives like tools, and not necessarily need or want the 'server' parts." [SamMorrowDrums](https://github.com/SamMorrowDrums) + +## 5. Server Instructions Reference + +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. + +## 6. Official Convention as Intermediate Step + +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`) +- Recommend metadata structure (version, tags, dependencies) aligned with agentskills.io +- Provide guidance on control model: resources for application-controlled, `skill()` tool for model-controlled +- 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."