π The fast, Pythonic way to build MCP servers and clients.
Consolidate skills docs into one Skills over MCP page (#6049)
nate nowack87c686ae680a
diff --git a/docs/clients/client.mdx b/docs/clients/client.mdxindex 26fbeb018..149a21935 100644--- a/docs/clients/client.mdx+++ b/docs/clients/client.mdx@@ -60,7 +60,7 @@ Pass your server instance to `Client(server)` in a test to exercise tool discove### Discovering and Downloading Skills-An agent can also use the client to retrieve instructions and supporting files from servers that expose skills as resources. The [skills client utilities](/servers/providers/skills#client-utilities) provide `list_skills()` for discovery, `get_skill_manifest()` for inspecting files, and `download_skill()` or `sync_skills()` for saving them locally.+An agent can also use the client to retrieve instructions and supporting files from servers that expose skills as resources. The [skills client utilities](/servers/skills#install-skills-into-a-local-agent) provide `list_skills()` for discovery, `get_skill_manifest()` for inspecting files, and `download_skill()` or `sync_skills()` for saving them locally.## Choosing a Transportdiff --git a/docs/docs.json b/docs/docs.jsonindex e0f2e2519..d3ce0cef9 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -138,8 +138,7 @@"servers/providers/local","servers/providers/filesystem","servers/providers/proxy",- "servers/providers/skills",- "servers/providers/experimental-skills",+ "servers/skills","servers/composition","servers/providers/custom"]@@ -428,6 +427,14 @@]},"redirects": [+ {+ "destination": "/servers/skills",+ "source": "/servers/providers/skills"+ },+ {+ "destination": "/servers/skills#discover-skills-with-the-skills-extension",+ "source": "/servers/providers/experimental-skills"+ },{"destination": "/getting-started/whats-new","source": "/development/v4-notes/index"diff --git a/docs/getting-started/ai-assisted-development.mdx b/docs/getting-started/ai-assisted-development.mdxindex 6a9fbb468..a887e8712 100644--- a/docs/getting-started/ai-assisted-development.mdx+++ b/docs/getting-started/ai-assisted-development.mdx@@ -45,4 +45,4 @@ Run the server's tests and inspect the schemas and results that clients receive.For deployment work, also test the intended transport and authentication. Use local fixtures or a test account for operations that change data.-If your server's users need guidance for workflows spanning several operations, consider supplying skills with the server. The [Skills Provider](/servers/providers/skills) serves skill files as resources; the [Experimental Skills Extension](/servers/providers/experimental-skills) adds standard skills discovery. Check the installed FastMCP version and target host's support, and verify that the host actually reads and uses the skill. Discovery alone does not activate it.+If your server's users need guidance for workflows spanning several operations, consider supplying skills with the server. [Skills over MCP](/servers/skills) shows how to serve a skills folder as resources and through standard skills discovery. Check the installed FastMCP version and target host's support, and verify that the host actually reads and uses the skill. Discovery alone does not activate it.diff --git a/docs/servers/middleware.mdx b/docs/servers/middleware.mdxindex 3cf6ffd27..18d84120c 100644--- a/docs/servers/middleware.mdx+++ b/docs/servers/middleware.mdx@@ -712,7 +712,7 @@ Do not return error values or skip `call_next()` to indicate errorsβraise exce### Authorizing Resource Access-To restrict which resources a caller can read, implement `check_resource_access` rather than `on_read_resource`. The default `on_read_resource` calls it before every read, and features that describe resources without reading them, such as [Skills discovery](/servers/providers/experimental-skills), call it too, so a resource the caller cannot read is not advertised either. Raise `AuthorizationError` to deny access.+To restrict which resources a caller can read, implement `check_resource_access` rather than `on_read_resource`. The default `on_read_resource` calls it before every read, and features that describe resources without reading them, such as [Skills discovery](/servers/skills#access-control), call it too, so a resource the caller cannot read is not advertised either. Raise `AuthorizationError` to deny access.```pythonfrom fastmcp.exceptions import AuthorizationErrordiff --git a/docs/servers/providers/experimental-skills.mdx b/docs/servers/providers/experimental-skills.mdxdeleted file mode 100644index 28ce4503d..000000000--- a/docs/servers/providers/experimental-skills.mdx+++ /dev/null@@ -1,82 +0,0 @@-----title: Experimental Skills Extension-sidebarTitle: Skills Extension (Experimental)-description: Publish filesystem skills through standard MCP skills discovery-icon: flask------The existing `SkillsDirectoryProvider` can opt into experimental Skills discovery, letting clients discover filesystem skills through `skills/list` and `skills/get`, with frontmatter and a complete file manifest. Files remain ordinary MCP resources, readable through `resources/read`.--<Warning>-This API is experimental and may change without a deprecation period. It builds on the [MCP Skills extension](https://github.com/modelcontextprotocol/ext-skills/blob/main/specification/stable/skills.mdx). Directory reads, host-side activation, approval, installation, and execution are not implemented.-</Warning>--## Publish skills--Set `experimental_skills=True` on `SkillsDirectoryProvider`, register it directly on your server, and register `SkillsExtension` with the same provider instance. The configured directory contains skill directories; each skill needs a UTF-8 `SKILL.md` with valid Agent Skills frontmatter.--```python-from fastmcp import FastMCP-from fastmcp.skills.extension import SkillsExtension-from fastmcp.server.providers.skills import SkillsDirectoryProvider--mcp = FastMCP("Skills")-skills = SkillsDirectoryProvider("./skills", experimental_skills=True)-mcp.add_provider(skills)-mcp.add_extension(SkillsExtension(providers=[skills]))--if __name__ == "__main__":- mcp.run(transport="http")-```--For example, `skills/review/SKILL.md` can contain:--```markdown-----name: review-description: Review a code change for correctness and compatibility.------Read the changed code and verify the behavior it promises.-```--Its URI is `skill://review/SKILL.md`. A nested skill at `skills/team/review/SKILL.md` uses `skill://team/review/SKILL.md`. Parent manifests include all supporting files, including nested skills; each nested skill also has its own discovery entry.--The default `supporting_files="template"` exposes the main files and existing synthetic `_manifest` entries as resources and supporting files through resource templates. Use `supporting_files="resources"` to include each supporting file in `resources/list`.--## Discover and read--Explicitly enable the typed client extension and use a modern protocol connection. Listing retrieves metadata; read only the files you need.--```python-from fastmcp import Client-from fastmcp.skills import SkillsClientExtension--async def inspect_skills() -> None:- async with Client(- "http://localhost:8000/mcp",- mode="auto",- extensions=[SkillsClientExtension()],- ) as client:- entries = await client.list_skills()- for entry in entries:- print(entry.uri, entry.frontmatter.description)-```--`client.get_skill(uri)` refreshes one entry. Each static manifest includes the URI, byte size, and SHA-256 digest of every file. A host must verify resource contents against those records before using them, preserve the originating server's identity, and apply the extension's approval rules. The typed client methods transport entries; they do not activate or approve skills.--## Validation and updates--Listing scans the directories and hashes their current bytes. Looking up a skill by URI hashes only that skill; resource reads resolve their path directly without scanning the skill collection. Reads remain live, preserving CRLF newlines and binary content. If a file changes between discovery and reading, the host detects the mismatch and refreshes the entry. This is a point-in-time manifest, not an atomic filesystem snapshot.--Malformed skills are omitted with a warning. Duplicate root-relative skill paths are all omitted. Frontmatter must have unique string keys and JSON-compatible values; timestamps, binary scalars, non-finite numbers, and YAML aliases are rejected. Skill roots and their contents must not be symbolic links. Skills over the extension's limits of 512 files or 16 MiB in total are omitted. Every file in a skill directory is published, including hidden files, so keep version control directories and editor files out of skill roots.--The entire entry is omitted when any supporting resource or template is unavailable to the caller or resolves to a different backing file. Resource reads claimed by the extension bypass `ResponseCachingMiddleware`, so refreshing a manifest cannot leave the host repeatedly receiving old cached bytes.--## Supported composition--Use directly registered providers with `experimental_skills=True`. Server and provider transforms, namespacing, mounted skill sources, and proxies are not supported. Resource authorization uses `Middleware.check_resource_access`, the policy hook also called by the default `on_read_resource`. `AuthMiddleware` implements this hook, including transport handling and scope checks. Custom resource authorization should implement this hook; custom `on_read_resource` overrides must call `super()` to apply it. Arbitrary restrictions or content changes in other middleware hooks cannot be inferred by discovery and are unsupported unless the middleware keeps the skill metadata consistent.--Without `experimental_skills=True`, the [Skills Provider](/servers/providers/skills) keeps its existing behavior, including permissive frontmatter, synthetic `_manifest` resources, first-root duplicate precedence, and the `reload` setting. Opting in enables strict validation, nested skill identities, duplicate rejection, and live byte-preserving reads. The same `SkillProvider` resource implementation serves both modes, including the existing synthetic `_manifest`. Strict frontmatter validation only determines eligibility for `skills/list` and `skills/get`; files without valid frontmatter remain readable as ordinary resources. Experimental resources use generic descriptions without parsing the main file, so malformed frontmatter or non-UTF-8 bytes cannot prevent resource listing or manifest reads. Author-provided descriptions remain available in valid Skills discovery entries. The main file must be `SKILL.md`. Experimental reads are always live, regardless of `reload`.--Removing the extension registration disables standard skills discovery while the provider continues serving resources in its selected mode.diff --git a/docs/servers/providers/skills.mdx b/docs/servers/providers/skills.mdxdeleted file mode 100644index e28e0e6bd..000000000--- a/docs/servers/providers/skills.mdx+++ /dev/null@@ -1,306 +0,0 @@-----title: Skills Provider-sidebarTitle: Skills-description: Expose agent skills as MCP resources-icon: wand-magic-sparkles------import { VersionBadge } from '/snippets/version-badge.mdx'--<VersionBadge version="3.0.0" />--Agent skills are directories containing instructions and supporting files that teach an AI assistant how to perform specific tasks. Tools like Claude Code, Cursor, and VS Code Copilot each have their own skills directories where users can add custom capabilities. The Skills Provider exposes these skill directories as MCP resources, making skills discoverable and shareable across different AI tools and clients.--To opt into standard MCP `skills/list` and `skills/get` discovery, see [Experimental Skills Extension](/servers/providers/experimental-skills). The experimental option is disabled by default.--## Why Skills as Resources--Skills live in platform-specific directories (`~/.claude/skills/`, `~/.cursor/skills/`, etc.) and typically contain a main instruction file plus supporting reference materials. When you want to share skills between tools or access them from a custom client, you need a way to discover and retrieve these files programmatically.--The Skills Provider solves this by exposing each skill as a set of MCP resources. A client can list available skills, read the main instruction file, check the manifest to see what supporting files exist, and fetch any file it needs. This transforms local skill directories into a standardized API that works with any MCP client.--## Quick Start--Create a provider pointing to your skills directory, then add it to your server.--```python-from pathlib import Path--from fastmcp import FastMCP-from fastmcp.server.providers.skills import SkillsDirectoryProvider--mcp = FastMCP("Skills Server")-mcp.add_provider(SkillsDirectoryProvider(roots=Path.home() / ".claude" / "skills"))-```--Each subdirectory containing a `SKILL.md` file becomes a discoverable skill. Clients can then list resources to see available skills and read them as needed.--```python-from fastmcp import Client--async with Client(mcp) as client:- # List each skill's main file and manifest- resources = await client.list_resources()- for r in resources:- print(r.uri) # skill://my-skill/SKILL.md, skill://my-skill/_manifest-- # Read a skill's main instruction file- result = await client.read_resource("skill://my-skill/SKILL.md")- print(result[0].text)-```--## Skill Structure--A skill is a directory containing a main instruction file (default: `SKILL.md`) and optionally supporting files. The directory name becomes the skill's identifier.--```-~/.claude/skills/-βββ pdf-processing/-β βββ SKILL.md # Main instructions-β βββ reference.md # Supporting documentation-β βββ examples/-β βββ sample.pdf-βββ code-review/- βββ SKILL.md-```--The main file can include YAML frontmatter to provide metadata. If no frontmatter exists, the provider extracts a description from the first meaningful line of content.--```markdown-----description: Process and extract information from PDF documents------# PDF Processing--Instructions for handling PDFs...-```--## Resource URIs--Each skill exposes three types of resources, all using the `skill://` URI scheme.--The main instruction file contains the primary skill content. This is the resource clients read to understand what a skill does and how to use it.--```-skill://pdf-processing/SKILL.md-```--The manifest is a synthetic JSON resource listing all files in the skill directory with their sizes and SHA256 hashes. Clients use this to discover supporting files and verify content integrity.--```-skill://pdf-processing/_manifest-```--Reading the manifest returns structured file information.--```json-{- "skill": "pdf-processing",- "files": [- {"path": "SKILL.md", "size": 1234, "hash": "sha256:abc123..."},- {"path": "reference.md", "size": 567, "hash": "sha256:def456..."},- {"path": "examples/sample.pdf", "size": 89012, "hash": "sha256:ghi789..."}- ]-}-```--Supporting files are any additional files in the skill directory. These might be reference documentation, code examples, or binary assets.--```-skill://pdf-processing/reference.md-skill://pdf-processing/examples/sample.pdf-```--<Note>-Skill files, including the main file, must resolve within the skill directory. Links to files within that directory are supported. A skill folder can itself be a link, such as an entry in `~/.claude/skills` that points to a checkout elsewhere; the skill's files must then resolve within the folder it links to.-</Note>--## Provider Architecture--The Skills Provider uses a two-layer architecture to handle both single skills and skill directories.--### SkillProvider--`SkillProvider` handles a single skill directory. It loads the main file, parses any frontmatter, scans for supporting files, and creates the appropriate resources.--```python-from pathlib import Path--from fastmcp import FastMCP-from fastmcp.server.providers.skills import SkillProvider--mcp = FastMCP("Single Skill")-mcp.add_provider(SkillProvider(Path.home() / ".claude" / "skills" / "pdf-processing"))-```--Use `SkillProvider` when you want to expose exactly one skill, or when you need fine-grained control over individual skill configuration.--### SkillsDirectoryProvider--`SkillsDirectoryProvider` scans one or more root directories and creates a `SkillProvider` for each valid skill folder it finds. A folder is considered a valid skill if it contains the main file (default: `SKILL.md`).--```python-from pathlib import Path--from fastmcp import FastMCP-from fastmcp.server.providers.skills import SkillsDirectoryProvider--mcp = FastMCP("Skills")-mcp.add_provider(SkillsDirectoryProvider(roots=Path.home() / ".claude" / "skills"))-```--When scanning multiple root directories, provide them as a list. The first directory takes precedence if the same skill name appears in multiple roots.--```python-from pathlib import Path--from fastmcp import FastMCP-from fastmcp.server.providers.skills import SkillsDirectoryProvider--mcp = FastMCP("Skills")-mcp.add_provider(SkillsDirectoryProvider(roots=[- Path.cwd() / ".claude" / "skills", # Project-level skills first- Path.home() / ".claude" / "skills", # User-level fallback-]))-```--## Vendor Providers--FastMCP includes pre-configured providers for popular AI coding tools. Each vendor provider extends `SkillsDirectoryProvider` with the appropriate default directory for that platform.--| Provider | Default Directory |-|----------|-------------------|-| `ClaudeSkillsProvider` | `~/.claude/skills/` |-| `CursorSkillsProvider` | `~/.cursor/skills/` |-| `VSCodeSkillsProvider` | `~/.copilot/skills/` |-| `CodexSkillsProvider` | `/etc/codex/skills/` and `~/.codex/skills/` |-| `GeminiSkillsProvider` | `~/.gemini/skills/` |-| `GooseSkillsProvider` | `~/.config/agents/skills/` |-| `CopilotSkillsProvider` | `~/.copilot/skills/` |-| `OpenCodeSkillsProvider` | `~/.config/opencode/skills/` |--Vendor providers accept the same configuration options as `SkillsDirectoryProvider` (except for `roots`, which is locked to the platform default).--```python-from fastmcp import FastMCP-from fastmcp.server.providers.skills import ClaudeSkillsProvider--mcp = FastMCP("Claude Skills")-mcp.add_provider(ClaudeSkillsProvider()) # Uses ~/.claude/skills/-```--`CodexSkillsProvider` scans both system-level (`/etc/codex/skills/`) and user-level (`~/.codex/skills/`) directories, with system skills taking precedence.--## Supporting Files Disclosure--The `supporting_files` parameter controls how supporting files (everything except the main file and manifest) appear to clients.--### Template Mode (Default)--With `supporting_files="template"`, supporting files are accessed through a `ResourceTemplate` rather than being listed as individual resources. Clients see only the main file and manifest in `list_resources()`, then discover supporting files by reading the manifest.--```python-from pathlib import Path--from fastmcp.server.providers.skills import SkillsDirectoryProvider--# Default behavior - supporting files hidden from list_resources()-provider = SkillsDirectoryProvider(- roots=Path.home() / ".claude" / "skills",- supporting_files="template", # This is the default-)-```--This keeps the resource list compact when skills contain many files. Clients that need supporting files read the manifest first, then request specific files by URI.--### Resources Mode--With `supporting_files="resources"`, every file in every skill appears as an individual resource in `list_resources()`. Clients get full enumeration upfront without needing to read manifests.--```python-from pathlib import Path--from fastmcp.server.providers.skills import SkillsDirectoryProvider--# All files visible as individual resources-provider = SkillsDirectoryProvider(- roots=Path.home() / ".claude" / "skills",- supporting_files="resources",-)-```--Use this mode when clients need to discover all available files without additional round trips, or when integrating with tools that expect flat resource lists.--## Reload Mode--Enable reload mode to re-scan the skills directory on every request. Changes to skills take effect immediately without restarting the server.--```python-from pathlib import Path--from fastmcp.server.providers.skills import SkillsDirectoryProvider--provider = SkillsDirectoryProvider(- roots=Path.home() / ".claude" / "skills",- reload=True,-)-```--With `reload=True`, the provider re-discovers skills on each `list_resources()` or `read_resource()` call. New skills appear, removed skills disappear, and modified content reflects current file state.--<Warning>-Reload mode adds overhead to every request. Use it during development when you're actively editing skills, but disable it in production.-</Warning>--## Client Utilities--FastMCP provides utilities for downloading skills from any MCP server that exposes them. These are standalone functions in `fastmcp.utilities.skills`.--### Discovering Skills--Use `list_skills()` to see what skills are available on a server.--```python-from fastmcp import Client-from fastmcp.utilities.skills import list_skills--async with Client("http://skills-server/mcp") as client:- skills = await list_skills(client)- for skill in skills:- print(f"{skill.name}: {skill.description}")-```--### Downloading Skills--Use `download_skill()` to download a single skill, or `sync_skills()` to download all available skills.--```python-from pathlib import Path--from fastmcp import Client-from fastmcp.utilities.skills import download_skill, sync_skills--async with Client("http://skills-server/mcp") as client:- # Download one skill- path = await download_skill(client, "pdf-processing", Path.home() / ".claude" / "skills")-- # Or download all skills- paths = await sync_skills(client, Path.home() / ".claude" / "skills")-```--Both functions accept an `overwrite` parameter. When `False` (default), existing skills are skipped. When `True`, existing files are replaced.--### Inspecting Manifests--Use `get_skill_manifest()` to see what files a skill contains before downloading.--```python-from fastmcp import Client-from fastmcp.utilities.skills import get_skill_manifest--async with Client("http://skills-server/mcp") as client:- manifest = await get_skill_manifest(client, "pdf-processing")- for file in manifest.files:- print(f"{file.path} ({file.size} bytes, {file.hash})")-```diff --git a/docs/servers/skills.mdx b/docs/servers/skills.mdxnew file mode 100644index 000000000..602eaa43f--- /dev/null+++ b/docs/servers/skills.mdx@@ -0,0 +1,336 @@+---+title: Skills over MCP+sidebarTitle: Skills+description: Serve a folder of agent skills from a FastMCP server so every connected agent reads the same maintained copy.+icon: wand-magic-sparkles+---++import { VersionBadge } from '/snippets/version-badge.mdx'++<VersionBadge version="3.0.0" />++An agent skill is a folder with a `SKILL.md` file of instructions and 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 in your repository: agents that connect read the current version, and an update ships when you deploy the server.++FastMCP serves a skills folder in two ways at once:++- **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 few hosts read it yet.++The rest of this page builds one server that does both, then shows what each kind of client sees.++## Lay out the skills folder++Keep skills in a folder in the repository that owns them, one folder per skill. The folder name is the skill's name and becomes its URI.++```text+skills/+βββ server-authoring/+β βββ SKILL.md+β βββ references/+β βββ testing.md+βββ client-cli/+ βββ SKILL.md+```++Start each `SKILL.md` with [Agent Skills](https://agentskills.io/specification) frontmatter. Skills discovery requires a `name` equal to the folder 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.++```markdown+---+name: server-authoring+description: Build, extend, and review MCP servers in this repository.+---++# Server authoring++Before changing a tool, read `references/testing.md` and test through an in-memory client.+```++Refer to supporting files by their path relative to the skill folder, as `references/testing.md` does above. Clients resolve that path against the skill's URI.++## Serve the folder++`SkillsDirectoryProvider` publishes every skill folder under a root directory. Setting `experimental_skills=True` on it, and registering `SkillsExtension` with the same provider instance, also turns on Skills discovery.++```python+from pathlib import Path++from fastmcp import FastMCP+from fastmcp.server.providers.skills import SkillsDirectoryProvider+from fastmcp.skills.extension import SkillsExtension++SKILLS_DIR = Path(__file__).parent / "skills"++mcp = FastMCP("Team Skills")+skills = SkillsDirectoryProvider(SKILLS_DIR, experimental_skills=True)+mcp.add_provider(skills)+mcp.add_extension(SkillsExtension(providers=[skills]))++if __name__ == "__main__":+ mcp.run(transport="http", port=8000)+```++Save this as `server.py` next to the `skills/` folder and run `python server.py`. The server can carry tools, resources, and prompts as usual; skills are one more provider.++To serve skills as resources only, leave out `experimental_skills=True` and the `SkillsExtension` line. To turn discovery off again later, remove both.++## Read skills as resources++Any MCP client sees each skill as two listed resources: its `SKILL.md` and a synthetic `_manifest`.++```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://server-authoring/SKILL.md")+ print(result[0].text)+++asyncio.run(main())+```++```text+skill://client-cli/SKILL.md+skill://client-cli/_manifest+skill://server-authoring/SKILL.md+skill://server-authoring/_manifest+```++Supporting files are not listed one by one. Each skill exposes a resource template, `skill://server-authoring/{path*}`, and the manifest names the files that template serves:++```json+{+ "skill": "server-authoring",+ "files": [+ {"path": "SKILL.md", "size": 214, "hash": "sha256:751c708f..."},+ {"path": "references/testing.md", "size": 88, "hash": "sha256:a4ea8ebc..."}+ ]+}+```++Read a supporting file by joining its path onto the skill's URI, such as `skill://server-authoring/references/testing.md`. To list every file as its own resource instead, see [supporting files](#list-supporting-files-as-resources).++### 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`.++```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())+```++`fastmcp.utilities.skills` also provides `list_skills()`, 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.++## 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.++```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())+```++```text+skill://client-cli/SKILL.md - Discover and call tools on an existing MCP server from the command line.+ skill://client-cli/SKILL.md 179 sha256:6208dfcc...+skill://server-authoring/SKILL.md - Build, extend, and review MCP servers in this repository.+ skill://server-authoring/SKILL.md 214 sha256:751c708f...+ skill://server-authoring/references/testing.md 88 sha256:a4ea8ebc...+```++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://server-authoring/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. `client.list_skills()` follows every page of `skills/list`; use `list_skills_mcp()` to fetch one page at a time.++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.++## Configure the provider++### Search several roots++Pass a list to serve more than one folder. When the same skill name appears in more than one root, the first root wins in resource mode. In discovery mode, duplicate skill paths are omitted from `skills/list`.++```python+from pathlib import Path++from fastmcp import FastMCP+from fastmcp.server.providers.skills import SkillsDirectoryProvider++mcp = FastMCP("Skills")+mcp.add_provider(+ SkillsDirectoryProvider(+ roots=[+ Path.cwd() / "skills",+ Path.home() / ".claude" / "skills",+ ]+ )+)+```++### List supporting files as resources++With the default `supporting_files="template"`, clients find supporting files through each skill's manifest. Set `supporting_files="resources"` to list every file in `resources/list` as well, for clients that expect a flat resource list.++```python+from pathlib import Path++from fastmcp.server.providers.skills import SkillsDirectoryProvider++skills = SkillsDirectoryProvider(Path("skills"), supporting_files="resources")+```++### Pick up edits without restarting++In resource mode the provider scans its roots once. Set `reload=True` to re-scan on every request while you edit skills locally; it adds a directory scan to each request, so leave it off in production. Discovery mode ignores `reload` and always serves current files.++```python+from pathlib import Path++from fastmcp.server.providers.skills import SkillsDirectoryProvider++skills = SkillsDirectoryProvider(Path("skills"), reload=True)+```++### Serve one skill++`SkillProvider` serves a single skill folder, for a server that ships exactly one skill.++```python+from pathlib import Path++from fastmcp import FastMCP+from fastmcp.server.providers.skills import SkillProvider++mcp = FastMCP("Release Skill")+mcp.add_provider(SkillProvider(Path("skills") / "server-authoring"))+```++`SkillProvider` serves resources only; Skills discovery reads from `SkillsDirectoryProvider`.++### Serve a coding agent's skills folder++Vendor providers are `SkillsDirectoryProvider` subclasses whose roots are fixed to a coding agent's default 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/` |++```python+from fastmcp import FastMCP+from fastmcp.server.providers.skills import ClaudeSkillsProvider++mcp = FastMCP("My Claude Skills")+mcp.add_provider(ClaudeSkillsProvider())+```++## What discovery mode changes++Setting `experimental_skills=True` makes the provider stricter, because a discovery entry promises exact bytes:++- **Validation.** A skill without valid frontmatter is left out of `skills/list` with a warning, but its files stay readable as resources. Frontmatter must have unique string keys and JSON-compatible values; timestamps, binary values, non-finite numbers, and YAML aliases are rejected.+- **Nested skills.** A skill folder inside another skill, such as `skills/team/review/SKILL.md`, gets its own entry with the URI `skill://team/review/SKILL.md`. The parent's manifest includes the nested files too.+- **Exact reads.** Files are read from disk on every request and returned byte for byte, including CRLF line endings and binary content. Reads that discovery depends on bypass `ResponseCachingMiddleware`.+- **Limits.** A skill with more than 512 files or 16 MiB in total is omitted. Skill roots and their contents must not be symbolic links.+- **Everything is published.** Every file in a skill folder becomes part of the skill, including hidden files, so keep version control and editor files out of skill folders.+- **Generic resource descriptions.** Listed resources carry descriptions such as `Skill: server-authoring` instead of the frontmatter description, so a malformed file can't break resource listing. The author's description appears in the discovery entry.++The manifest is a point-in-time record, not a filesystem snapshot. If a file changes between discovery and a read, the digest check above catches it.++Without the flag, the provider keeps its permissive resource-mode behavior: frontmatter is optional, the description falls back to the first line of the file, links to skill folders elsewhere on disk are followed, and the first root wins on duplicate names.++## 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 or denied by `Middleware.check_resource_access`, the hook that [`AuthMiddleware`](/servers/authorization) and the default `on_read_resource` use. Implement custom resource authorization in that hook so discovery can apply it; restrictions applied in other middleware hooks are invisible to discovery.++## Current limits++Skills discovery currently serves skills from `SkillsDirectoryProvider` instances registered directly on the server you run.++- `SkillsExtension` raises when the server or the skills provider has transforms, including namespaces, or when the provider is not registered directly on the same server.+- Skills in a [mounted server](/servers/composition) are served as resources through the parent, but the parent does not list them in `skills/list`.+- A proxy in front of the server forwards the skill files as resources, but not `skills/list` or `skills/get`.+- The optional `directoryRead` capability is not implemented.++Resource mode has none of these limits. Serve skills as resources everywhere, and add discovery on the server that clients connect to directly.