diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0c1e7a1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,62 @@ +# Contributing + +## How to Participate + +This Interest Group welcomes contributions from anyone interested in skills distribution over MCP. You can participate by: + +- Joining discussions in the [#skills-over-mcp-ig Discord channel](https://discord.com/channels/1358869848138059966/1464745826629976084) (info on joining the Discord server [here](https://modelcontextprotocol.io/community/communication#discord)) +- Opening or commenting on GitHub Discussions in this repo +- Sharing experimental findings from your own implementations +- Contributing to documentation and pattern evaluation + +## Communication Channels + +| Channel | Purpose | Response Expectation | +| :--- | :--- | :--- | +| [Discord #skills-over-mcp-ig](https://discord.com/channels/1358869848138059966/1464745826629976084) | Quick questions, coordination, async discussion | Best effort | +| GitHub Discussions | Long-form technical proposals, experimental findings | Weekly triage | +| This repository | Living reference for approaches, findings, and decisions | Updated after meetings | + +## Meetings + +*To be scheduled* — likely biweekly working sessions once the group establishes momentum. + +Meeting norms: + +- Agendas published 24 hours in advance +- Notes published within 48 hours + +## Decision-Making + +As an Interest Group, we operate by **rough consensus** — we're exploring and recommending, not deciding. Outputs include: + +- Documented requirements and use cases +- Evaluated approaches with findings +- Recommendations to relevant WGs or as SEP proposals + +## Contribution Guidelines + +### Documenting Approaches and Findings + +When adding experimental findings or new approaches: + +- Include enough detail for others to reproduce or evaluate +- Note which clients and servers were tested +- Be explicit about what worked, what didn't, and what remains untested +- Attribute community input with GitHub handles and link to the source where possible + +### Community Input + +When adding quotes or input from community discussions: + +- Attribute to the contributor by name and GitHub handle +- Link to the original source (Discord thread, GitHub comment, etc.) where possible +- Present input as blockquotes to distinguish it from editorial content + +### Filing Issues + +Use GitHub Issues for: + +- Proposing new approaches or use cases +- Reporting gaps in documentation +- Tracking action items from meetings diff --git a/README.md b/README.md index d8993b4..ca30541 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,25 @@ # Skills Over MCP Interest Group -> ⚠️ **Experimental** — This repository is an incubation space for the [Skills Over MCP Interest Group](https://docs.google.com/document/d/1j-AGRcvLkYiiIJ9asmmF1mLLjjUiova7a9BgkSXtD4s/edit?usp=sharing). Contents are exploratory and do not represent official MCP specifications or recommendations. +> ⚠️ **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. +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 ## Problem Statement @@ -15,7 +30,70 @@ Native "skills" support in host applications demonstrates demand for rich workfl - **No discovery mechanism** — users installing MCP servers don't know if there's a corresponding skill they should also install - **Multi-server orchestration** — skills may need to coordinate tools from multiple servers -## Status +See [problem-statement.md](problem-statement.md) for full details. -- This repository is WIP and will ultimately replace [this public Google Document](https://docs.google.com/document/d/1j-AGRcvLkYiiIJ9asmmF1mLLjjUiova7a9BgkSXtD4s/edit?usp=sharing). -- Until this note is removed, please continue to use the above document and the [#skills-over-mcp-ig Discord channel](https://discord.com/channels/1358869848138059966/1464745826629976084) for ongoing discussion. +## Repository Contents + +| Document | Description | +| :--- | :--- | +| [Problem Statement](problem-statement.md) | Current limitations and gaps | +| [Use Cases](use-cases.md) | Key use cases driving this work | +| [Approaches](approaches.md) | Approaches being explored (not mutually exclusive) | +| [Open Questions](open-questions.md) | Unresolved questions with community input | +| [Experimental Findings](experimental-findings.md) | Results from implementations and testing | +| [Related Work](related-work.md) | SEPs, implementations, and external resources | +| [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 | [@TeamSparkAI](https://github.com/TeamSparkAI) | +| Facilitator | Rado | Stacklok / MCP Maintainer | | +| 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 | Not Started | TBD | Establish communication with agentskills.io maintainers | +| 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 | + +## Success Criteria + +- **Short-term:** Documented consensus on requirements and evaluation of existing approaches +- **Medium-term:** Clear recommendation (convention vs. protocol extension vs. both) +- **Long-term:** Interoperable skill distribution across MCP servers and clients diff --git a/docs/experimental-findings.md b/docs/experimental-findings.md new file mode 100644 index 0000000..d20297c --- /dev/null +++ b/docs/experimental-findings.md @@ -0,0 +1,63 @@ +# Experimental Findings + +## McpGraph: Skills in MCP Server Repo + +**Repo:** [TeamSparkAI/mcpGraph](https://github.com/TeamSparkAI/mcpGraph) +**Skill:** [mcpgraphtoolkit/SKILL.md](https://github.com/TeamSparkAI/mcpGraph/blob/main/skills/mcpgraphtoolkit/SKILL.md) (875+ lines) + +Bob Dickinson built a standalone SKILL.md file that lives in the same repo as the MCP server, but they weren't formally connected. The skill instructs agents on building directed graphs of MCP nodes to orchestrate tool calls. + +**Findings:** + +- Claude ignored the SKILL.md initially, even when the skill and server had similar descriptions +- Claude would fail at using the server tools a couple times, then read the skill and succeed +- Expected Claude to start with the skill ("I know how to do X") before the server ("I do X"), but it didn't + +**Resolution:** Added a server instruction telling the agent to read the SKILL.md before using the tool. That one change caused Claude to reliably read the skill first. + +**Remaining concerns:** + +- This workaround works for 1:1 skill-to-server case, but doesn't solve discovery — users installing from a registry don't know to also install the skill +- Distinguishes between "skill required to make the server work at all" vs. "skill that orchestrates tools you could use without it" — potentially different solutions needed + +## Skilljack MCP + +**Repo:** [olaservo/skilljack-mcp](https://github.com/olaservo/skilljack-mcp) + +Loads skills into tool descriptions. Uses dynamic tool updates to keep the skills manifest current. + +## worfcat's Three-Way Comparison + +Tested skills exposed in three ways across multiple clients: + +### 1. Skills as MCP Resources (with a simple `validate_skill` tool) + +**Result: Bad.** The model never used them or looked at them unless explicitly asked. + +### 2. Skills as Tools in an MCP Server (`list_skills` and `read_skills`) + +**Result: Mixed.** Needed some tool description tuning to get used. More brittle than native. Worked with Claude Code, OpenAI agent builder, and a few other clients. + +### 3. Native Skills (installing in `skills/` folder of Claude Code) + +**Result: Best.** Easiest, worked out of the box. + +**Key insight:** + +> "There is a many-many relationship between skills and tools. A skill should not require pieces of instruction like 'here's how you use this single tool'. If an instruction of how to use an MCP server is copied across skills, it should live at the server level. Context decomposition basically." + +**Note:** Claude Code's skill implementation is just a tool call — `Skill()` returns the SKILL.md file. Nothing fancy (at least for now). + +## FastMCP 3.0 Skills Support + +**URL:** [gofastmcp.com/servers/providers/skills](https://gofastmcp.com/servers/providers/skills) + +FastMCP added skills support in version 3.0. Worth examining for alignment with other approaches. + +**Related:** [jlowin/fastmcp#2694](https://github.com/jlowin/fastmcp/issues/2694) + +## PydanticAI Skills Support + +**PR:** [pydantic/pydantic-ai#3780](https://github.com/pydantic/pydantic-ai/pull/3780) + +Introduces support for agent skills with a tools-based approach. diff --git a/docs/problem-statement.md b/docs/problem-statement.md index 66587d8..a751f5b 100644 --- a/docs/problem-statement.md +++ b/docs/problem-statement.md @@ -1,6 +1,6 @@ # Problem Statement -Native "skills" support in host applications demonstrates demand for rich workflow instructions, but there's no convention for exposing equivalent functionality through MCP primitives. +[Agent Skills](https://agentskills.io/home) support in AI applications demonstrates demand for rich workflow instructions, but there's no convention for exposing equivalent functionality through MCP primitives. ## Current Limitations @@ -11,42 +11,13 @@ Native "skills" support in host applications demonstrates demand for rich workfl ## Key Use Cases -### 1. Complex Workflow Orchestration +See [use-cases.md](use-cases.md) for detailed use cases and community input. In summary: -Bob Dickinson's [mcpGraph](https://github.com/TeamSparkAI/mcpGraph) toolkit requires a skill file of 875+ lines to instruct agents on building directed graphs of MCP nodes. This orchestration logic is "way more than you'd want to put in instructions." - -### 2. Conditional Workflows - -Workflows that reference tools conditionally based on context, requiring rich structured instructions that can be dynamically loaded. - -### 3. Multi-Server Composition - -Skills that leverage tools from multiple off-the-shelf servers where you can't (or don't want to) modify their individual instructions. - -### 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. +1. **Complex Workflow Orchestration** — Multi-step workflows requiring 875+ lines of instruction (e.g., [mcpGraph](https://github.com/TeamSparkAI/mcpGraph)) +2. **Conditional Workflows** — Branching instructions dynamically loaded based on context +3. **Multi-Server Composition** — Skills leveraging tools from multiple off-the-shelf servers +4. **Progressive Disclosure** — Skills broken into linked file sets, loaded on demand ## Open Questions -1. **Is this a registry problem or an MCP server problem?** Should skills be discoverable through registry metadata ("if you install this server, also install this skill") or contained within the MCP server itself? - -2. **How do "first-class" skills differ from "skills as context"?** Native agent skills can be presented through the user agent, bundled with subagents, etc. Do MCP-surfaced skills lose capabilities compared to directly installed skills? - -3. **Should server.instructions be extended for richer content?** Or is the separation between "primitive server" and "skill that uses the primitive" the right abstraction? - -4. **How should skills relate to multiple servers?** A skill orchestrating tools from several servers can't live in any single server's instructions. - -5. **Do clients actually leverage skills when presented via MCP?** Early experiments suggest they do, but more rigorous testing is needed. - -6. **How do we coordinate with agent skills spec owners?** The contribution model for the skills spec isn't clear, and MCP-related efforts should be brought to their attention. - -7. **What would MCP have had to get right for skills to have been shipped over MCP from the beginning?** (https://github.com/keithagroves) - -8. **What could MCP reasonably change so that it will be the obvious choice for new formats?** (https://github.com/keithagroves) - -9. **Who gets visibility into skill content, and who decides when it gets loaded?** The control model question — model-controlled vs. application-controlled. (https://github.com/olaservo) - -10. **How should skills handle security and trust boundaries?** If skills can be abused for prompt injection, what mitigations should be spec'd? (provenance, gating, explicit policy) (https://github.com/Agent-Hellboy) - -11. **Should the control model be use-case specific?** Perhaps resources (application-controlled) for some use cases, tools (model-controlled) for others? Can a convention support both? (https://github.com/olaservo) +See [open-questions.md](open-questions.md) for the full list of unresolved questions with community input. diff --git a/docs/related-work.md b/docs/related-work.md new file mode 100644 index 0000000..3e82a91 --- /dev/null +++ b/docs/related-work.md @@ -0,0 +1,34 @@ +# Related Work + +## Open SEPs and Proposals + +| Proposal | Venue | Description | +| :--- | :--- | :--- | +| [SEP-2076](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2076) | MCP Spec | Agent Skills as a first-class MCP primitive | +| [skills.json format proposal](https://github.com/modelcontextprotocol/registry/discussions/895) | MCP Registry | Skills metadata in registry schema | +| [FastMCP #2694](https://github.com/jlowin/fastmcp/issues/2694) | FastMCP | Add Skills support | +| [PydanticAI #3780](https://github.com/pydantic/pydantic-ai/pull/3780) | PydanticAI | Introduce support for agent skills | + +## Implementations + +| Implementation | Author | URL | Notes | +| :--- | :--- | :--- | :--- | +| skilljack-mcp | Ola Hungerford | [github.com/olaservo/skilljack-mcp](https://github.com/olaservo/skilljack-mcp) | Skills as tools with dynamic updates | +| mcpGraph skill | Bob Dickinson | [github.com/TeamSparkAI/mcpGraph](https://github.com/TeamSparkAI/mcpGraph) | 875+ line skill for graph orchestration | +| skills-over-mcp | Keith Groves | [github.com/keithagroves/skills-over-mcp](https://github.com/keithagroves/skills-over-mcp) | Example using skills with current MCP primitives | +| chrome-devtools-mcp | Anthropic | [github.com/anthropics/anthropic-quickstarts/…/chrome-devtools-mcp](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-servers/chrome-devtools-mcp) | Real-world example: `skills/` folder requires separate install path | +| NimbleBrain skills repo | NimbleBrain | [github.com/NimbleBrainInc/skills](https://github.com/NimbleBrainInc/skills) | Monorepo with `.skill` artifact format | +| NimbleBrain registry | NimbleBrain | [registry.nimbletools.ai](https://registry.nimbletools.ai/) | Registry with skill metadata support | +| FastMCP 3.0 Skills | FastMCP | [gofastmcp.com/servers/providers/skills](https://gofastmcp.com/servers/providers/skills) | Native skills provider | +| mcp-cli | philschmid | [github.com/philschmid/mcp-cli](https://github.com/philschmid/mcp-cli) | Wraps MCP servers as CLI for progressive disclosure | +| mcp-execution | bug-ops | [github.com/bug-ops/mcp-execution](https://github.com/bug-ops/mcp-execution) | Compiles MCP servers into skill packages | +| Astronomer agents | Kaxil Naik | [github.com/astronomer/agents](https://github.com/astronomer/agents) | Skills distribution via MCP for Apache Airflow | + +## External Resources + +- **Agent Skills Standard:** [agentskills.io](https://agentskills.io/) +- **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 +- **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 +- **Apache Airflow AIP-91** (MCP integration): [cwiki.apache.org/…/AIP-91+-+MCP](https://cwiki.apache.org/confluence/display/AIRFLOW/AIP-91+-+MCP) +- **Video background:** [youtube.com/watch?v=CEvIs9y1uog](https://www.youtube.com/watch?v=CEvIs9y1uog)