modelcontextprotocol/ext-skills
Watch
1
0
Fork
You've already forked ext-skills
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Clean and and re-organize repo docs (#146)

Browse source 
* docs: point README and AGENTS.md at the released spec and official docs

SEP-2640 is Final and the extension ships from specification/stable/skills.mdx,
so the README now leads with a Specification section linking the spec file,
the official docs page (modelcontextprotocol.io/extensions/skills/overview),
the published SEP, and the client matrix. The experimental banner is replaced
with a note that docs/ holds working documents; the charter, pulls, and issues
links move off the redirecting experimental-ext-skills / charter URLs.

AGENTS.md no longer names the SEP PR as the source of truth; it points agents
at the stable spec page and describes the decision-log flow against that file.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: accepted spec changes land in a draft revision, not the stable file

The stable specification is a released snapshot. README and AGENTS.md now say
accepted decision-log proposals go into a draft revision that ships as a new
release, matching the ext-tasks specification layout.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: move pre-release design documents to docs/archive

SEP-2640 is Final, so docs/ now holds only living working documents. Eight
historical documents move to docs/archive with an index explaining what each
was and what superseded it: the SEP baseline copy, why-and-when, use-cases,
approaches, skill-uri-scheme, glossary, client-mcp-support (superseded by the
official client matrix), and agent-plugins-analysis.

Files the published SEP links to by path (decisions, experimental-findings,
open-questions, problem-statement, rationale, related-work, skill-meta-keys)
stay in place so those links keep working. Cross-links are rewritten and
verified; the README contents table is trimmed to match.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: archive open-questions and skill-meta-keys

Both are pre-release documents whose outcomes live in the decision log and
the specification. The published SEP links to them by path; a companion
change in modelcontextprotocol/modelcontextprotocol repoints those links.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: fix sibling links inside archived open-questions and skill-meta-keys

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: keep only the decision log and rationale in docs/

threat-model, experimental-findings, findings-template, problem-statement,
and related-work move to docs/archive with index rows. The candidates
tracker and the archived client-support survey are removed in favor of the
official extension client matrix, and links to them are repointed there.

README drops the Why and Problem Statement sections, which duplicate the
SEP's Motivation and the official overview page. CONTRIBUTING routes new
implementation findings to GitHub issues.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: fix sibling links inside newly archived documents

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: add a concise implementations list

One table each for servers/SDKs and hosts, one line per entry, replacing the
retired candidates tracker and the related-work implementation tables. Seeded
from those plus PR #141 and issue #144.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: put tracking links in the Status column of the implementations list

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: add a vendor/community category to the implementations list

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: replace the interim reference package with the TypeScript SDK row

The @olaservo/ext-skills package is retired in favor of first-class skills
APIs in the TypeScript SDK (typescript-sdk#2798, phase 1 in #2818). The
archived related-work page now points at implementations.md for current
information.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: drop pre-SEP rows from the implementations list

They are already recorded in the archived related-work page; the list now
points there instead. FastMCP stays because its row tracks the migration to v1.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: add official SDK progress, Tachyon, and Inspector 2.6.0 to implementations

From the WG Discord channel and the SDK repos as of 2026-09-15: Go, TypeScript,
Python, and C# SDKs all have open SEP-2640 PRs (Go passes conformance); the
conformance suite merged; Inspector 2.6.0 shipped skills verification; Tachyon
reports a server implementation. Adds an "in progress" status for open PRs.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: track Goose host support via the official issue

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: only tag community rows in the implementations list

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: tag MCP-project rows as official in the implementations list

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: split the implementations list into SDKs, servers, and hosts

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: add MCPJam Inspector to hosts

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* Revise implementations table format and content

Updated the implementations table to include language and status columns.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Correct links and clarify documentation references

Updated links to SEP-2640 and clarified document references.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Sambhav Kothari <sambhavs.email@gmail.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Ola Hungerford 2026-09-15 21:56:20 -07:00 • committed by GitHub
commit 5adfff5952
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 115 additions and 305 deletions
Download patch file Download diff file Expand all files Collapse all files

60
README.md
View file

@ -1,51 +1,37 @@
# 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.
This repository is the home of the official [Model Context Protocol](https://modelcontextprotocol.io) **Skills extension** (`io.modelcontextprotocol/skills`), based on [SEP-2640](https://modelcontextprotocol.io/seps/2640-skills-extension), and of the Skills Over MCP Working Group's working documents.
**📄 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.
## Specification
| Resource | Where |
| :--- | :--- |
| **Specification (source of truth)** | [`specification/stable/skills.mdx`](specification/stable/skills.mdx) — the extension spec, written against base protocol revision `2026-07-28` |
| **Official documentation** | [modelcontextprotocol.io/extensions/skills/overview](https://modelcontextprotocol.io/extensions/skills/overview) — condensed overview with examples and message flow |
| **SEP-2640: Skills Extension** | [modelcontextprotocol.io/seps/2640-skills-extension](https://modelcontextprotocol.io/seps/2640-skills-extension) — the accepted SEP (Status: Final; [PR #2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) merged 2026-09-13) |
| **Client support** | [Extension client matrix](https://modelcontextprotocol.io/extensions/client-matrix) — which clients implement the extension |
The stable specification is a released snapshot and is not edited in place. Changes are proposed as dated entries in the [decision log](docs/decisions.md) (see [AGENTS.md](AGENTS.md) for the process) and, once accepted, land in a draft revision of the specification that ships as a new release.
> ℹ️ The [`docs/`](docs/) folder holds the [decision log](docs/decisions.md), the [design rationale](docs/rationale.md), and the [implementations list](docs/implementations.md). Earlier design documents, findings, and trackers are frozen in [`docs/archive/`](docs/archive/). None of it is part of the specification.
**Charter:** [modelcontextprotocol.io/community/working-groups/skills-over-mcp](https://modelcontextprotocol.io/community/working-groups/skills-over-mcp) — 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.
**Open work:** [Pull requests](https://github.com/modelcontextprotocol/ext-skills/pulls) and [issues](https://github.com/modelcontextprotocol/ext-skills/issues) — proposals, decisions, implementations, and other in-flight contributions welcome.
## 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 |
| [Specification](specification/stable/skills.mdx) | The Skills extension specification (`io.modelcontextprotocol/skills`) — source of truth |
| [Decision Log](docs/decisions.md) | ADR-lite record of the group's decisions, and the vehicle for proposing changes to the specification |
| [Rationale](docs/rationale.md) | Design rationale for the Resources-based extension |
| [Implementations](docs/implementations.md) | Servers, SDKs, and hosts that serve or consume skills over MCP |
| [Archive](docs/archive/) | Pre-release design documents, findings, and trackers, frozen when SEP-2640 was marked Final |
For the case for serving skills over MCP, see the [official overview](https://modelcontextprotocol.io/extensions/skills/overview) and the Motivation section of [SEP-2640](https://modelcontextprotocol.io/seps/2640-skills-extension).
## Contributing