skills: add SEP-2640 protocol support

[vijaydeepsinha]

Summary

Adds Python SDK support for [SEP-2640 (Skills Extension)]): skills/list, skills/get, and resources/directory/read as protocol primitives, SEP-2640 conformance validation, and capability negotiation. This SDK does not provide filesystem discovery, catalog indexing, or caching/refresh policy — those belong to a higher-level provider built on top of this.

Motivation and Context

SEP-2640 defines a convention for serving Agent Skills over MCP using the Resources primitive. The Python SDK has no support for it today. This PR adds the extension using the SDK's existing Extension/MethodBinding mechanism (the same one backing the shipped Apps extension, SEP-2133) — no schema or codegen changes, no new required dependencies.

What's included

• src/mcp/shared/skills.py — wire types (Skill, SkillResource, params/results), SEP-2640 conformance validation (name/URI/frontmatter consistency, digest format, resource-manifest completeness, the 512-entry/16 MiB limits), and verify_skill_resource (digest+size integrity check for content already read).
• src/mcp/server/skills.py — the Skills extension: handler-based (list_skills, get_skill, optional read_directory), validates results against SEP-2640 before they hit the wire, gates the SEP-2549 ttlMs/cacheScope fields to protocol version 2026-07-28+.
• src/mcp/client/skills.py — list_skills/get_skill/read_directory (auto-paginating, with cursor-repeat detection), read_skill_uri (a thin, discoverable resources/read alias), verify_skill_resource re-exported for client use.
• docs/advanced/skills.md + docs_src/skills/ — a new doc page with a runnable example, explicitly scoping what the SDK does and doesn't do.

Server usage

from mcp.server.skills import Skills
from mcp.shared.skills import ListSkillsResult, GetSkillResult

async def list_skills(ctx, params):
    return ListSkillsResult(skills=[...])

async def get_skill(ctx, params):
    if params.uri != "skill://git-workflow/SKILL.md":
        raise MCPError(code=INVALID_PARAMS, message="unknown skill")
    return GetSkillResult(skill=...)

mcp = MCPServer("catalog", extensions=[Skills(list_skills=list_skills, get_skill=get_skill)])
mcp.add_resource(TextResource(uri="skill://git-workflow/SKILL.md", ...))  # file content is served normally

Client usage

from mcp.client.skills import get_skill, list_skills, read_skill_uri, verify_skill_resource

skills = await list_skills(client.session)
skill = await get_skill(client.session, "skill://git-workflow/SKILL.md")
result = await read_skill_uri(client.session, skill.uri)
verify_skill_resource(skill, skill.uri, result.contents[0].text.encode())

Protocol version / compatibility notes

• capabilities.extensions (SEP-2133) and ttlMs/cacheScope (SEP-2549) are 2026-07-28+-only wire fields in this SDK's existing type surface — this is pre-existing, documented SDK behavior (docs/advanced/extensions.md), not something this PR changes. Skills gates its own cache fields to match.
• A JSON-RPC -32602 error returns HTTP 200 on the classic (pre-2026-07-28) wire and HTTP 400 on the modern (2026-07-28+) wire. This is existing, spec-mandated (SEP-2575) SDK-wide transport behavior — every handler in the SDK gets it automatically via the shared ERROR_CODE_HTTP_STATUS table; nothing Skills-specific.
• No breaking changes to any existing public API. All new files; the only touched existing file is mkdocs.yml (one nav entry).

How Has This Been Tested?

• tests/{shared,server,client,docs_src}/test_skills.py — 100% line+branch coverage on all three new modules (shared/skills.py, server/skills.py, client/skills.py), verified via coverage report --fail-under=0.
• Full suite: ./scripts/test → 6000+ passed, 0 failed, 100% total coverage, strict-no-cover clean.
• ruff format/ruff check, pyright, markdownlint, mkdocs build --strict (Zensical), README-snippet check: all clean.
• Cross-version: uv run --python 3.10 pytest tests/*/test_skills.py passes.

Conformance

Ran the SEP-2640 scenarios end-to-end against a real server and client built on this implementation (server scenarios exercise this PR's server; client scenarios exercise this PR's client against a hostile server the harness stands up):

Scenario	Checks	Result
sep-2640-skills-enumeration (skills/list + skills/get)	30	✅ 30/30
sep-2640-skills-manifest (SKILL.md resource metadata)	6	✅ 6/6
sep-2640-skills-directory (resources/directory/read)	7	✅ 7/7
sep-2640-client-no-prefetch	1	✅ PASS
sep-2640-client-verify-digest	1	✅ PASS
sep-2640-client-verify-size	1	✅ PASS
sep-2640-client-verify-frontmatter	1	✅ PASS
sep-2640-client-verify-unlisted	1	✅ PASS

43 wire checks + 5 client checks, 0 failures, 0 warnings.

Also manually verified via a live server against a Postman collection covering both the session-based (2025-11-25) and stateless (2026-07-28) wires.

Breaking Changes

None. New files only; no existing public API is modified.

Deliberate scope exclusions (and why)

• Filesystem discovery/indexing/caching: this SDK gives the protocol primitives only; a higher-level provider library (e.g. one that walks a directory tree and computes digests) builds on top of Skills, list_skills, and get_skill.
• Client-side frontmatter parsing: SEP-2640 requires hosts to parse a SKILL.md's YAML frontmatter and compare it field-by-field against the held entry. This SDK does not ship that comparison, to avoid adding a new required YAML dependency to the core SDK for a check any host already has the means to do with whatever YAML library it uses elsewhere. verify_skill_resource covers the digest/size half (no new dependency needed for that). Documented explicitly in docs/advanced/skills.md's "What this SDK doesn't do".
• Skills types living in mcp-types instead of mcp.shared: mcp-types is generated from the official, versioned MCP JSON Schema; SEP-2640 is an extension, not core spec vocabulary, so its types are hand-written and live alongside the extension code — the same placement the existing Apps extension (SEP-2133) uses.

Types of changes

• New feature (non-breaking change which adds functionality)
• Documentation update

Checklist

• I am assigned to the linked issue (or it is labeled help wanted, or I'm a maintainer) — N/A while targeting my own fork; will file/link before retargeting to upstream
• I have disclosed any AI assistance and can explain the change in my own words
• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Implemented with AI assistance (Claude Code). Commits carry Co-Authored-By trailers for the Claude models used (Claude Sonnet 5 and Claude Opus 4.8). I've reviewed the implementation, reasoning, and conformance results directly, and can explain and defend any part of it in my own words.