47fc34a92e* docs: add combined skills glossary Adds docs/glossary.md with working definitions for Skills Over MCP terminology, addressing #51. Combines the strongest definitions from three open glossary PRs (#103, #101, #93): - Core terms covering all 10 terms requested in #51 (skill, instruction, primitive, resource, convention, context, progressive disclosure, control model, first-class primitive, server/skill author, discovery), with Agent Skills alignment/divergence noted where relevant. - Distribution and ecosystem terms (skill resource, skill:// URI, skill metadata, server-skill pairing, multi-server composition, ephemeral availability, provenance). - Cross-referenced from the README documents table. Co-authored-by: kiku-jw <25382531+kiku-jw@users.noreply.github.com> Co-authored-by: luohui1 <187920557+luohui1@users.noreply.github.com> Co-authored-by: EfeDurmaz16 <75971010+EfeDurmaz16@users.noreply.github.com> * docs: align glossary with latest SEP-2640 and decision log Reconcile the combined glossary against the current SEP-2640 text and the Working Group decision log: - First-class primitive: reflect that the WG considered and declined a skills/list method (2026-06-05), keeping skills as Resources, rather than framing it as a still-open option. - Add Skill index (skill://index.json), Archive, and Directory listing (resources/directory/read) terms — settled spec concepts that were missing (decisions 2026-04-19, 2026-06-05, 2026-06-09). - Skill metadata: ground in SKILL.md frontmatter and note _meta is reserved for transport-specific keys under io.modelcontextprotocol.skills/ (decision 2026-03-16); index copies frontmatter verbatim. - Provenance: note the WG treats it as a distribution/plugin-layer concern, not standardized skill metadata (decision 2026-03-16). - References: add SEP-2640 and the Decision Log. * docs: incorporate June 16 WG meeting clarifications From the 2026-06-16 Skills Over MCP WG meeting notes (postdates the decision log): - Skill metadata: distinguish the two reserved namespaces — the io.modelcontextprotocol/ prefix inside the frontmatter metadata block vs. the io.modelcontextprotocol.skills/ prefix on resource _meta. - Add Compatibility term: the frontmatter compatibility field is free-text and LLM-evaluated (not a deterministic gate); hosts screen execution-requiring skills by convention, and the WG holds that execution/environment signaling belongs in the Agent Skills spec. * docs: update glossary terms to SEP-2640 v1 (skills/list, skills/get, digests; archives removed) --------- Co-authored-by: kiku-jw <25382531+kiku-jw@users.noreply.github.com> Co-authored-by: luohui1 <187920557+luohui1@users.noreply.github.com> Co-authored-by: EfeDurmaz16 <75971010+EfeDurmaz16@users.noreply.github.com>
52 lines
5.6 KiB
Markdown
52 lines
5.6 KiB
Markdown
# Skills Over MCP Working Group
|
|
|
|
> ⚠️ **Experimental** — This repository is an incubation space for the Skills Over MCP Working Group. Contents are exploratory and do not represent official MCP specifications or recommendations.
|
|
|
|
**📄 SEP-2640 (Skills Extension):** [modelcontextprotocol#2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) — **the source of truth for the v1 spec text.** Review and comments belong on the PR. The copy in this repo is a synced baseline for discussion; see [`docs/sep-draft-skills-extension.md`](docs/sep-draft-skills-extension.md).
|
|
**Charter:** [modelcontextprotocol.io/community/skills-over-mcp/charter](https://modelcontextprotocol.io/community/skills-over-mcp/charter) — mission, scope, membership, active work items, and success criteria.
|
|
**Project board:** [Skills Over MCP WG](https://github.com/orgs/modelcontextprotocol/projects/38/views/1)
|
|
**Meeting notes:** [Skills Over MCP WG 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)
|
|
**Open work:** [Pull requests](https://github.com/modelcontextprotocol/experimental-ext-skills/pulls) — proposals, decisions, implementations, and other in-flight contributions welcome.
|
|
|
|
## Why Skills Over MCP?
|
|
|
|
MCP servers give agents tools, but tools alone are insufficient for complex workflows — tool descriptions tell an agent *what* a tool does, not *how to orchestrate* multiple tools to achieve a goal. Skills bridge this gap. They are structured "how-to" knowledge: multi-step workflows, conditional logic, and orchestration instructions that can run to hundreds of lines.
|
|
|
|
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. 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
|
|
|
|
Native "skills" support in host applications demonstrates demand for rich workflow instructions, but there's no convention for exposing equivalent functionality through MCP primitives. Current limitations include:
|
|
|
|
- **Server instructions load only at initialization** — new or updated skills require re-initializing the server
|
|
- **Complex workflows exceed practical instruction size** — some skills require hundreds of lines of markdown with references to bundled files
|
|
- **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
|
|
|
|
See [problem-statement.md](docs/problem-statement.md) for full details.
|
|
|
|
## Repository Contents
|
|
|
|
| Document | Description |
|
|
| :--- | :--- |
|
|
| [Problem Statement](docs/problem-statement.md) | Current limitations and gaps |
|
|
| [Why Skills Over MCP?](docs/why-and-when.md) | Value proposition and decision guide |
|
|
| [Use Cases](docs/use-cases.md) | Key use cases driving this work |
|
|
| [Approaches](docs/approaches.md) | Approaches being explored (not mutually exclusive) |
|
|
| [SEP-2640: Skills Extension](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) | Proposal to serve skills over MCP via the Resources primitive. The v1 baseline text is kept at [`docs/sep-draft-skills-extension.md`](docs/sep-draft-skills-extension.md), synced from the canonical SEP. Comments and review of v1 happen on the PR; changes beyond v1 are proposed as entries in the [decision log](docs/decisions.md). |
|
|
| [Open Questions](docs/open-questions.md) | Unresolved questions with community input (see also [issues](https://github.com/modelcontextprotocol/experimental-ext-skills/issues) and [meeting notes](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/categories/meeting-notes-skills-over-mcp-wg)) |
|
|
| [Experimental Findings](docs/experimental-findings.md) | Results from implementations and testing |
|
|
| [Related Work](docs/related-work.md) | SEPs, implementations, and external resources |
|
|
| [Threat Model](docs/threat-model.md) | Threat model for skills served over MCP (SEP-2640), with delivery-model recommendations and an archive appendix |
|
|
| [Skills Extension Candidates](docs/skills-extension-candidates.md) | MCP servers, dev tools, SDKs, and skills repositories that are candidates for adopting the skills extension |
|
|
| [Client MCP Support](docs/client-mcp-support.md) | Survey of model-facing MCP resource loading and SEP-2640 support across open-source clients |
|
|
| [Decision Log](docs/decisions.md) | Record of key decisions with context and rationale |
|
|
| [Rationale](docs/rationale.md) | Design rationale for SEP-2640's Resources-based skills extension |
|
|
| [Glossary](docs/glossary.md) | Working definitions for key Skills Over MCP terms |
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for how to participate.
|