- MDX 96.1%
- TypeScript 3.9%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
4870967b38* docs: sync SEP copy with upstream commit b405ba5 Re-syncs docs/sep-draft-skills-extension.md from the canonical sep/skills-extension branch (twelve commits, 2026-08-11 to 2026-08-21) and updates the pinned commit reference in the header. Most of the removed lines are the Rationale section, which upstream replaced with a pointer to docs/rationale.md in this repo. That text is not lost, it now lives in one place instead of two. The rest: per-skill limits and a `size` field, an explicit "dynamic" marker in place of the omit-`resources` rule, (server, URI) as a skill's identity, on-demand retrieval with write-isolated caches, the window in which a host is acting on a skill, and `resultType` on every sample result. * docs: update rationale for the SEP sync Three passages said dynamically generated skills omit `resources`, which is no longer valid, and the per-file-digests section offered "cache the whole set at approval time" as the pinning primitive, which the SEP now forbids. Adds a section on why an enclosing skill's manifest includes its nested skills, recording the answer given on the concerns doc: content-bound approval binds to the `resources` set, so the set has to be complete. * docs: re-sync SEP copy to upstream commit 753b9f2 Picks up the table reformatting from 753b9f2 and updates the pinned commit in the file header. No specification text changed between b405ba5 and 753b9f2. * docs: record why hosts retrieve skill files on demand The SEP prohibits fetching a skill's files ahead of need but explains it in one sentence, and the reasoning for the cache-integrity rule that accompanies it is only in the upstream commit messages. Add a rationale section covering the server-load argument, why lazy retrieval leaves content-bound approval intact, and what it gives up relative to staging the whole resources set at approval time. * docs: tighten the on-demand retrieval rationale Merges the two paragraphs that both argued late retrieval is still safe, and drops the restatement of the cache mechanics -- write-isolation, re-hashing on access, digest labels not counting as verification -- which Security Implications owns. The rationale needs the shape of the trade, not a second copy of the rules. Also corrects the limits sentence. 512 files and 16 MiB are host-support floors, not a cap on what a server may serve: a skill above them is not invalid, it just loses guaranteed portability. Drops the threat-model link. The rotation point it supported is correct, but the document still names `install` its recommended baseline and argues for immutability on the grounds that there is "no second live read to diverge" -- the model this section prohibits. Restore the link after the threat model is revised. * docs: trim the on-demand retrieval rationale Server load is one reason for retrieving late, not the only one. The paragraph on what late retrieval gives up restated verification rules the spec already carries. |
||
| .github | ||
| docs | ||
| .gitignore | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| README.md | ||
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 — 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.
Charter: modelcontextprotocol.io/community/skills-over-mcp/charter — mission, scope, membership, active work items, and success criteria.
Project board: Skills Over MCP WG
Meeting notes: Skills Over MCP WG discussions
Discord: #skills-over-mcp-wg
Open work: Pull requests — 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 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" (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 for full details.
Repository Contents
| Document | Description |
|---|---|
| Problem Statement | Current limitations and gaps |
| Why Skills Over MCP? | Value proposition and decision guide |
| Use Cases | Key use cases driving this work |
| Approaches | Approaches being explored (not mutually exclusive) |
| SEP-2640: Skills Extension | Proposal to serve skills over MCP via the Resources primitive. The v1 baseline text is kept at 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. |
| Open Questions | Unresolved questions with community input (see also issues and meeting notes) |
| Experimental Findings | Results from implementations and testing |
| Related Work | SEPs, implementations, and external resources |
| Threat Model | Threat model for skills served over MCP (SEP-2640), with delivery-model recommendations and an archive appendix |
| Decision Log | Record of key decisions with context and rationale |
| Rationale | Design rationale for SEP-2640's Resources-based skills extension |
Contributing
See CONTRIBUTING.md for how to participate.