Skip to main content
Skills over MCP follows the draft SEP-2640 extension. The wire contract may change before the extension becomes final. Only serve skills you trust, and hosts should require user approval before activating a skill or its allowed tools.
Skills let an MCP server ship its operating manual alongside its tools. Hosts can first inspect the small skill catalog, then read SKILL.md and only the supporting references, scripts, templates, or assets needed for the task.

Zero-configuration setup

Create a conventional skills/ directory next to your server project. Its presence enables Skills over MCP automatically; no server option is required.
Every skill needs a SKILL.md whose name matches its directory:
All frontmatter fields are preserved. Supporting text, scripts, data, and binary files are exposed as individual MCP resources with raw-byte SHA-256 digests. Nested directories containing their own SKILL.md are published as independent skills as well as supporting content of their parent skill.

Configure discovery

With mcp-use dev --mcp-dir src/mcp, the conventional directory becomes src/mcp/skills. An explicit skills.directory remains relative to the project root. Missing directories are silent only for automatic discovery; true, {}, and custom configuration fail with an actionable error.

What hosts discover

When skills are enabled the server declares io.modelcontextprotocol/skills with directory reads. Hosts use:
  • skills/list for the deterministic skill catalog and complete digest sets.
  • skills/get to refresh or retrieve one skill by its SKILL.md URI.
  • resources/read for individual text or binary files.
  • resources/directory/read to inspect one directory level at a time.
The SDK does not inject skill text into server instructions or tool descriptions. Progressive disclosure and activation remain host decisions. mcp-use dev revalidates skills while the server runs. If one skill becomes invalid, the development server reloads with that skill omitted from the current catalog; every other valid skill remains available. The CLI logs the invalid skill and its validation error, and adds it back on the next successful reload. If every skill is invalid, the server advertises an empty catalog rather than serving stale skill content. mcp-use build remains strict: an invalid skill catalog fails the build. Successful builds embed the validated snapshot, so the production server does not need the source skill directory. Discovery and YAML validation are Node-only CLI concerns; the server and Edge runtime receive only the immutable embedded snapshot.

Specifications