Skip to content

πŸš€ 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.mdx
index cd43af6dd..3cf7b9804 100644
--- a/docs/servers/skills.mdx
+++ b/docs/servers/skills.mdx
@@ -1,7 +1,7 @@
---
title: Skills over MCP
sidebarTitle: 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 SkillCatalogProvider
release_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 Skill
from 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 asyncio
from pathlib import Path
from fastmcp import Client
from 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 Client
from 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.