Set up the rest of the starting docs

.gitignore

@@ -0,0 +1 @@
+.claude/settings.local.json

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

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.
+
+## 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
 
-- 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.
+- **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

docs/approaches.md

@@ -0,0 +1,111 @@
+# Approaches Being Explored
+
+> These are not mutually exclusive solutions.
+
+## Design Principles
+
+Whatever approach is adopted, community members have highlighted several principles:
+
+> "There should be intentional focus on making it easy for server authors to create and expose skills... client hosts are strongly incentivized to have a relatively uniform way to discover and consume them — at least from the point of view of a server author — while also leaving room for client host innovation." — [Peder Holdgaard Pedersen](https://github.com/PederHP)
+
+## Central Tension: Convention vs. Protocol Extension
+
+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.
+
+## 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)
+
+**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.
+
+**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/)
+
+**Community input:**
+
+> "We view skills as an opportunity to use them as both a standalone (general-purpose capabilities) & MCP-paired (tool-specific guidance). For the main registry, the binding could be softer: optional fields like suggestedSkills or recommendedSkills rather than definitive pairing, since skill authorship is often decoupled from server authorship." — [Mat Goldsborough](https://github.com/mgoldsborough)
+
+## 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)
+
+**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
+- 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."
+
+**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

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(<n>)` 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.