π The fast, Pythonic way to build MCP servers and clients.
Shorten the skills docs page (#6079)
nate nowack558a9503845e
diff --git a/docs/servers/skills.mdx b/docs/servers/skills.mdxindex cd43af6dd..3cf7b9804 100644--- a/docs/servers/skills.mdx+++ b/docs/servers/skills.mdx@@ -1,7 +1,7 @@---title: Skills over MCPsidebarTitle: Skills-description: Serve agent skills from a FastMCP server so every connected agent reads the same maintained copy.+description: Serve agent skills from a FastMCP server so every agent reads the same copy.icon: wand-magic-sparkles---@@ -9,23 +9,11 @@ import { VersionBadge } from '/snippets/version-badge.mdx'<VersionBadge version="3.0.0" />-An agent skill is a `SKILL.md` file of instructions plus any supporting files those instructions refer to. Agents usually load skills from a local folder, so every machine needs its own copy and every copy drifts. Serving skills from an MCP server keeps one maintained copy: agents that connect read the current version, and an update ships when you deploy the server.--Clients see served skills in two ways:--- **As resources.** Each skill's files are ordinary MCP resources under `skill://` URIs. Every MCP client can list and read them today.-- **Through Skills discovery.** Since FastMCP 4.1.2, the [MCP Skills extension](https://modelcontextprotocol.io/seps/2640-skills-extension) adds `skills/list` and `skills/get`, which return each skill's frontmatter and a manifest of its files with sizes and SHA-256 digests. A host that supports the extension can offer your skills to its agent without a separate install step. This support is experimental in FastMCP, and only a handful of hosts read it so far.--The recommended path is to define each skill as a `Skill` object, and serve them with `SkillCatalogProvider`, which publishes them both as resources and through discovery. The rest of this page follows that path, then covers the folder-based providers and when to pick them.--## Define skills--<VersionBadge version="4.2.0" />--A `Skill` holds one skill's files in memory, exactly as they will be served. You can write it in Python, read it from a folder, or load it from an installed package.+A skill is a `SKILL.md` of instructions plus whatever files it points to. Most agents load skills from a local folder, which means every laptop has its own copy and none of them agree. Put the skills on an MCP server instead: one copy, and an update ships when you deploy.```python-from fastmcp import Skill+from fastmcp import FastMCP, Skill+from fastmcp.skills.provider import SkillCatalogProviderrelease_notes = Skill(name="release-notes",@@ -33,307 +21,86 @@ release_notes = Skill(instructions="# Release notes\n\nGroup changes by theme. Follow template.md.\n",files={"template.md": "## Highlights\n\n## Fixes\n"},)-```--The constructor writes `SKILL.md` from `name`, `description`, `instructions`, and any extra `frontmatter` you pass. Refer to supporting files by their path relative to the skill, as `template.md` does above; clients resolve that path against the skill's URI.--The other constructors read files you already have:--- `Skill.from_directory("skills/deploy")` reads a skill folder.-- `Skill.from_package("my_package", "skills/review")` reads a skill folder shipped inside an installed Python package.-- `Skill.from_files({"SKILL.md": ..., "notes.md": ...})` builds a skill from a mapping of relative paths to `str` or `bytes`.-Each one reads the files once and keeps their exact bytes, so later edits to a folder don't change the skill. A `Skill` is immutable and validated when you create it. Its `SKILL.md` needs [Agent Skills](https://agentskills.io/specification) frontmatter with a `name` made of lowercase letters, digits, and single hyphens, and a `description` of up to 1,024 characters. The description is what an agent reads to decide whether the skill applies, so say when to use it. A folder's name must match its `name`, and a skill may hold up to 512 files and 16 MiB in total.--A skill folder looks like this:--```text-skills/deploy/-βββ SKILL.md-βββ references/- βββ checklist.md+mcp = FastMCP("Team Skills")+mcp.add_provider(SkillCatalogProvider([release_notes]))```-```markdown-----name: deploy-description: Deploy the app to staging or production. Use before any release.------# Deploy+That's a skills server. Every client can read `skill://release-notes/SKILL.md` and `template.md` as ordinary resources. Clients that speak the [Skills extension](https://modelcontextprotocol.io/seps/2640-skills-extension) can also call `skills/list` and get each skill's description and a hashed manifest of its files, so a host can offer the skill without an install step. Few hosts do yet, and FastMCP's support is experimental, but you get both from the same provider. Run `fastmcp list server.py --skills` to see what you're serving.-Run through `references/checklist.md` before deploying.-```+## Where skills come from-## Serve skills+<VersionBadge version="4.2.0" />-`SkillCatalogProvider` serves a list of `Skill` objects. It registers `SkillsExtension` on the server for you, so adding the provider turns on Skills discovery.+A `Skill` is just files. Write it in Python as above, or load what you already have:```python-from fastmcp import FastMCP-from fastmcp.skills import Skill-from fastmcp.skills.provider import SkillCatalogProvider--release_notes = Skill(- name="release-notes",- description="Write release notes from merged pull requests.",- instructions="# Release notes\n\nGroup changes by theme. Follow template.md.\n",- files={"template.md": "## Highlights\n\n## Fixes\n"},-)+from fastmcp import Skill-mcp = FastMCP("Team Skills")deploy = Skill.from_directory("skills/deploy")-skills = SkillCatalogProvider([release_notes, deploy])-mcp.add_provider(skills)--if __name__ == "__main__":- mcp.run(transport="http", port=8000)+review = Skill.from_package("my_package", "skills/review")+triage = Skill.from_files({"SKILL.md": "---\nname: triage\ndescription: Triage issues.\n---\n"})```-Each skill is served at `skill://{name}/`. Every file is listed as a resource, along with a `_manifest` resource for clients that read skills without discovery.+Skills are validated when you build them and never change afterward; editing the folder later doesn't touch the loaded skill. The `description` is what an agent reads to decide whether to use the skill, so make it say when.-Pass a mapping to choose a skill's path, such as `{"team/review": review}`. The last segment must match the skill's name, and one skill's path can't sit inside another's.--### Load skills at request time--To serve skills that change while the server runs, such as rows in a database, subclass the provider and override `load_skills()`. FastMCP calls it once per MCP request, and every lookup in that request sees the same skills.+If your skills live somewhere that changes, like a database, override `load_skills()`. FastMCP calls it once per request:```python-from fastmcp import FastMCP-from fastmcp.skills import Skill+from fastmcp import Skillfrom fastmcp.skills.provider import SkillCatalogProvider-# Stands in for your storage: one dict of files per skill.-SKILL_ROWS = [- {"SKILL.md": "---\nname: triage\ndescription: Triage new issues.\n---\n# Triage\n"},-]-class StoredSkills(SkillCatalogProvider):async def load_skills(self) -> list[Skill]:- return [Skill.from_files(files) for files in SKILL_ROWS]---mcp = FastMCP("Stored Skills")-skills = StoredSkills()-mcp.add_provider(skills)-```--### Choose a provider--`SkillCatalogProvider` fits most servers. The folder providers read skills straight from disk on every request, which suits a skills folder you are still editing or one owned by a coding agent.--| You want to serve | Use |-|-------------------|-----|-| Skills written in code, shipped in a package, or loaded from storage | `SkillCatalogProvider` |-| A folder you edit while the server runs, or skills nested inside other skills | `SkillsDirectoryProvider` |-| A coding agent's own skills folder, such as `~/.claude/skills/` | A vendor provider, such as `ClaudeSkillsProvider` |-| One skill folder, as resources only | `SkillProvider` |--### Serve a skills folder from disk--`SkillsDirectoryProvider` publishes every skill folder under one or more roots. Set `experimental_skills=True` on it to turn on discovery; the provider then registers `SkillsExtension` for you.--```python-from pathlib import Path--from fastmcp import FastMCP-from fastmcp.server.providers.skills import SkillsDirectoryProvider--mcp = FastMCP("Folder Skills")-skills = SkillsDirectoryProvider(- roots=[Path.cwd() / "skills", Path.home() / ".claude" / "skills"],- experimental_skills=True,-)-mcp.add_provider(skills)+ rows = [{"SKILL.md": "---\nname: triage\ndescription: Triage issues.\n---\n"}]+ return [Skill.from_files(files) for files in rows]```-With `experimental_skills=True`, the provider reads files from disk on every request, serves a nested skill such as `skills/team/review/SKILL.md` as its own entry, applies the same validation and limits as `Skill`, and leaves invalid skills out of `skills/list` with a warning while keeping their files readable. Skill roots and their contents must not be symbolic links, and every file in a skill folder is published, including hidden files. When the same skill path appears in more than one root, discovery omits it.--Without the flag, the provider serves resources only and keeps its permissive behavior: frontmatter is optional, the first root wins on duplicate names, and links to folders elsewhere on disk are followed. A few options apply to this mode:--- `reload=True` re-scans the roots on every request, for local editing. Leave it off in production.-- `supporting_files="resources"` lists every supporting file in `resources/list`. By default, clients find them through each skill's `_manifest` and a `skill://{name}/{path*}` template.--Vendor providers are `SkillsDirectoryProvider` subclasses with roots fixed to a coding agent's skills folder. They take the same options except `roots`.--| Provider | Folder |-|----------|--------|-| `ClaudeSkillsProvider` | `~/.claude/skills/` |-| `CursorSkillsProvider` | `~/.cursor/skills/` |-| `VSCodeSkillsProvider` | `~/.copilot/skills/` |-| `CodexSkillsProvider` | `/etc/codex/skills/`, then `~/.codex/skills/` |-| `GeminiSkillsProvider` | `~/.gemini/skills/` |-| `GooseSkillsProvider` | `~/.config/agents/skills/` |-| `CopilotSkillsProvider` | `~/.copilot/skills/` |-| `OpenCodeSkillsProvider` | `~/.config/opencode/skills/` |--`SkillProvider(Path("skills/deploy"))` serves a single skill folder as resources. For discovery, serve `Skill.from_directory()` with `SkillCatalogProvider` instead.+If you're still editing a folder and want changes to show up live, serve it straight from disk with `SkillsDirectoryProvider(path, experimental_skills=True)`. Presets like `ClaudeSkillsProvider` do the same for a coding agent's own skills folder.## Access control-Skills discovery respects the same rules as resource reads. A skill is omitted from `skills/list` when any of its files is hidden from the caller, denied by `Middleware.check_resource_access`, or shadowed by another resource at the same URI. `check_resource_access` is the hook that [`AuthMiddleware`](/servers/authorization) and the default `on_read_resource` use, so implement custom resource authorization there; restrictions in other middleware hooks are invisible to discovery.+Discovery never shows a skill the caller can't read. If any of its files is hidden, denied by `check_resource_access` (what [`AuthMiddleware`](/servers/authorization) uses), or shadowed by another resource, the skill drops out of `skills/list`.## Mounted servers-Skills follow a [mounted server](/servers/composition) to its parent. The parent's `skills/list` includes the child's skills at the URIs the parent serves them at, so `mount(child, namespace="team")` turns `skill://review/SKILL.md` into `skill://team/review/SKILL.md`, and every file in the manifest moves with it. This works through any depth of mounts.--The parent lists a mounted skill only when it routes every file back to the child and the caller passes the parent's own access checks. A parent resource that shadows one of the files, or a parent middleware rule that denies one, hides the skill. Two mounts that publish the same skill URI hide each other's copy.--To limit discovery to specific providers instead, register the extension yourself. An explicit registration replaces the automatic one and doesn't include mounted servers.--```python-from fastmcp import FastMCP-from fastmcp.skills import Skill-from fastmcp.skills.extension import SkillsExtension-from fastmcp.skills.provider import SkillCatalogProvider--triage = Skill(name="triage", description="Triage new issues.", instructions="# Triage\n")--mcp = FastMCP("Team Skills")-public = SkillCatalogProvider([triage])-mcp.add_provider(public)-mcp.add_extension(SkillsExtension(providers=[public]))-```+Skills come along when you [mount](/servers/composition) a server, at the URIs the parent serves them at: `mount(child, namespace="team")` turns `skill://review/` into `skill://team/review/`. If you'd rather choose exactly which providers are discoverable, register the extension yourself with `mcp.add_extension(SkillsExtension(providers=[...]))` from `fastmcp.skills.extension`.## Read skills from a client-### Read skills as resources--Any MCP client can list a server's skills and read their files.--```python-import asyncio--from fastmcp import Client---async def main() -> None:- async with Client("http://localhost:8000/mcp") as client:- for resource in await client.list_resources():- print(resource.uri)-- result = await client.read_resource("skill://deploy/SKILL.md")- print(result[0].text)---asyncio.run(main())-```--Each skill's `_manifest` resource lists its files with sizes and hashes:--```json-{- "skill": "deploy",- "files": [- {"path": "SKILL.md", "size": 157, "hash": "sha256:751c708f..."},- {"path": "references/checklist.md", "size": 88, "hash": "sha256:a4ea8ebc..."}- ]-}-```-### Install skills into a local agent-Agents that only read skills from disk can still use a served copy. `sync_skills()` downloads every skill on the server into a local skills folder, and `download_skill()` downloads one. Both skip skills that already exist unless you pass `overwrite=True`.+Most agents still only read skills from disk. `sync_skills()` copies a server's skills into a local folder, and works with any server that serves skills as resources:```python-import asynciofrom pathlib import Pathfrom fastmcp import Clientfrom fastmcp.utilities.skills import sync_skills-AGENT_SKILLS_DIR = Path.home() / ".claude" / "skills"---async def main() -> None:- async with Client("http://localhost:8000/mcp") as client:- installed = await sync_skills(client, AGENT_SKILLS_DIR, overwrite=True)- for path in installed:- print(path)---asyncio.run(main())+async with Client("http://localhost:8000/mcp") as client:+ await sync_skills(client, Path.home() / ".claude" / "skills", overwrite=True)```-`fastmcp.utilities.skills` also provides `list_skill_summaries()`, which lists skill names from the resource listing, and `get_skill_manifest()`, which reads one manifest. These helpers work with any server that publishes skills as resources, with or without discovery. Earlier releases named the summary helper `list_skills()`; that name still works with a deprecation warning. It is unrelated to `client.list_skills()`, described next.-### Discover skills with the Skills extension-A client that opts into the extension can ask the server for its skills directly. Discovery requires a connection on a modern MCP protocol version, which `Client` negotiates by default.+Opt the client into the extension and ask:```python-import asyncio-from fastmcp import Clientfrom fastmcp.skills import SkillsClientExtension--async def main() -> None:- client = Client(- "http://localhost:8000/mcp",- extensions=[SkillsClientExtension()],- )- async with client:- for skill in await client.list_skills():- print(skill.uri, "-", skill.frontmatter.description)- for file in skill.resources:- print(" ", file.uri, file.size, file.digest)---asyncio.run(main())+client = Client("http://localhost:8000/mcp", extensions=[SkillsClientExtension()])+async with client:+ for skill in await client.list_skills():+ print(skill.uri, skill.frontmatter.description)```-`client.list_skills()` and `client.get_skill()` return `MCPSkill` objects: the wire record that describes a skill, much as `MCPTool` describes a tool. `Skill.to_mcp_skill()` builds the same record from a `Skill`. `client.list_skills()` follows every page of `skills/list`; use `list_skills_mcp()` to fetch one page at a time. A server that can't enumerate a skill's files sends `resources` as the string `"dynamic"` instead of a list; FastMCP servers always send a list.--Listing returns metadata only. The agent reads the files it needs through `resources/read`, and should check each file against its manifest record before using it:--```python-import asyncio-import base64-import hashlib--from fastmcp import Client-from fastmcp.skills import SkillsClientExtension---async def read_verified(client: Client, uri: str, size: int, digest: str) -> bytes:- contents = await client.read_resource(uri)- content = contents[0]- if hasattr(content, "blob"):- data = base64.b64decode(content.blob)- else:- data = content.text.encode()- actual = "sha256:" + hashlib.sha256(data).hexdigest()- if len(data) != size or actual != digest:- raise ValueError(f"{uri} changed since discovery; refresh with get_skill()")- return data---async def main() -> None:- client = Client(- "http://localhost:8000/mcp",- extensions=[SkillsClientExtension()],- )- async with client:- skill = await client.get_skill("skill://deploy/SKILL.md")- for file in skill.resources:- data = await read_verified(client, file.uri, file.size, file.digest)- print(file.uri, len(data), "bytes verified")---asyncio.run(main())-```--A mismatch means the file changed between discovery and the read. Refresh the entry with `client.get_skill(uri)` and read again. The client methods only transport entries; deciding when to load a skill, asking a user to approve it, and running anything it describes are the host's job.+You get metadata, not content. Read the files you need with `read_resource()`, and check each against its manifest `digest` before trusting it. [`ClientGroup.list_skills()`](/clients/client-groups) does the same across several servers.## Current limits-Skills discovery serves skills from `SkillCatalogProvider` and `SkillsDirectoryProvider` instances registered on the server you run or on servers mounted into it.--- A skill provider added with a namespace or other transforms is left out of `skills/list`. To namespace skills, mount a server that holds the provider. A server with server-level transforms lists no skills.-- A proxy in front of the server forwards the skill files as resources, but not `skills/list` or `skills/get`.-- `SkillCatalogProvider` does not nest skills inside other skills and has no built-in reload; override `load_skills()` for skills that change.-- The optional `directoryRead` capability is not implemented.--Resource mode has none of these limits.+- Skills behind a proxy are readable as resources but don't show up in `skills/list`.+- A provider added with a namespace or other transforms isn't discoverable; mount a server instead.+- `directoryRead` isn't implemented.