This repository is the home of the official Model Context Protocol Skills extension (io.modelcontextprotocol/skills), based on SEP-2640, and of the Skills Over MCP Working Group's working documents.
| Resource | Where |
|---|---|
| Specification (source of truth) | specification/beta/skills.mdx — the extension spec, written against base protocol revision 2026-07-28 |
| Official documentation | modelcontextprotocol.io/extensions/skills/overview — condensed overview with examples and message flow |
| SEP-2640: Skills Extension | modelcontextprotocol.io/seps/2640-skills-extension — the accepted SEP (Status: Final; PR #2640 merged 2026-09-13) |
| Client support | Extension client matrix — which clients implement the extension |
The specification is a released revision and is not edited in place. The extension is at the Beta stage of the extension lifecycle. Changes are proposed as dated entries in the decision log (see AGENTS.md for the process) and, once accepted, land in a draft revision of the specification that ships as a new release.
ℹ️ The
docs/folder holds the decision log, the design rationale, and the implementations list. Earlier design documents, findings, and trackers are frozen indocs/archive/. None of it is part of the specification.
Charter: modelcontextprotocol.io/community/working-groups/skills-over-mcp — 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 and issues — proposals, decisions, implementations, and other in-flight contributions welcome.
| Document | Description |
|---|---|
| Specification | The Skills extension specification (io.modelcontextprotocol/skills) — source of truth |
| Decision Log | ADR-lite record of the group's decisions, and the vehicle for proposing changes to the specification |
| Rationale | Design rationale for the Resources-based extension |
| Implementations | Servers, SDKs, and hosts that serve or consume skills over MCP |
| Maintainers | Extension Maintainers for the Skills extension |
| 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 and the Motivation section of SEP-2640.
schema/beta/schema.ts exports the wire types in the released Beta specification. schema/beta/schema.json is generated from those types using the base protocol's typescript-json-schema generator and integer-number convention. It uses JSON Schema 2020-12 and the identifier https://modelcontextprotocol.io/ext-skills/beta/schema.json.
The identifier names the current Beta revision. A Beta revision may make breaking changes, so the same identifier can name different content after a new revision ships. Pin to a commit of this repository if you need fixed content.
The JSON file is a container of named $defs, like the core MCP schema. Validate a specific definition (for example #/$defs/ReadResourceDirectoryResult), not the container itself. The artifact is available in this repository; its $id does not require a network lookup. It includes the base definitions needed by the extension and the message-flow examples, so validation can run offline.
The released specification remains normative. CI checks all of its TypeScript declarations against the exported types and validates every JSON message example, including base resource reads and errors. Type generation preserves inherited required fields such as request _meta, ttlMs, and cacheScope, without depending on an SDK's interpretation.
This is structural validation. It does not enforce prose-only requirements such as digest integrity, manifest completeness, URI/frontmatter name agreement, consent, or the semantic requirement that successful skill results have resultType: "complete" (the published types inherit the base ResultType). Those still require semantic conformance tests and host-side checks.
See CONTRIBUTING.md for how to participate.