π The fast, Pythonic way to build MCP servers and clients.
Consolidate skills examples around verified Skill values (#6093)
nate nowack18ab63d01e7f
diff --git a/docs/servers/skills.mdx b/docs/servers/skills.mdxindex 9c21f52e1..7b2280681 100644--- a/docs/servers/skills.mdx+++ b/docs/servers/skills.mdx@@ -93,7 +93,20 @@ class FolderSkills(SkillCatalogProvider):]```-For recursive folder discovery that skips invalid skills, use `SkillsDirectoryProvider(path, experimental_skills=True)`. Presets like `ClaudeSkillsProvider` point it at a coding agent's own skills folder.+For recursive folder discovery that skips invalid skills, use `SkillsDirectoryProvider(path, experimental_skills=True)`. To discover a coding agent's own skills folder through the extension, pass its path explicitly:++```python+from pathlib import Path++from fastmcp import FastMCP+from fastmcp.server.providers.skills import SkillsDirectoryProvider++root = Path.home() / ".claude" / "skills"+provider = SkillsDirectoryProvider(root, experimental_skills=True)+mcp = FastMCP("Local Skills", providers=[provider])+```++Presets such as `ClaudeSkillsProvider` expose ordinary resources and do not accept the `experimental_skills` option.## Access control@@ -111,12 +124,17 @@ A [proxy](/servers/providers/proxy) passes a backend's skill files through as refrom fastmcp import FastMCPfrom fastmcp.server.providers.proxy import ProxyClient, ProxyProvider-backend = ProxyProvider(lambda: ProxyClient("https://backend.example/mcp"), skills=True)+backend = ProxyProvider(+ lambda: ProxyClient("https://backend.example/mcp", mode="auto"),+ skills=True,+)gateway = FastMCP("Gateway")gateway.add_provider(backend)```+A custom `ProxyClient` factory needs `mode="auto"` to negotiate the modern protocol used by Skills. Directly constructed `ProxyClient` instances default to the legacy handshake. `create_proxy(..., skills=True)` handles protocol mirroring for you.+Backend entries pass through unchanged, and the same access rules apply: a skill shows up only if the gateway serves every one of its files from that backend to that caller. A backend without the Skills extension contributes nothing. To namespace a backend's skills, mount a proxy instead:```python@@ -148,7 +166,7 @@ You get metadata, not content. [`ClientGroup.list_skills()`](/clients/client-gro### Read a whole skill-`read_skill()` fetches every file in the skill's manifest, checks each one's size and SHA-256 digest, and returns a `Skill`. It uses `skills/get` when the extension was negotiated, falling back to FastMCP's `_manifest` resource when the extension is unavailable or doesn't know the skill:+`read_skill()` fetches every file in the skill's manifest, checks each one's size and SHA-256 digest, and returns a `Skill`. When the extension supplies an entry, the downloaded frontmatter must also match it. The existing 512-file and 16 MiB limits are checked before downloading file contents. It uses `skills/get` when the extension was negotiated, falling back to FastMCP's `_manifest` resource when the extension is unavailable or doesn't know the skill:```pythonfrom fastmcp import Client@@ -176,6 +194,8 @@ async with Client("http://localhost:8000/mcp") as client:Downloads now require valid `SKILL.md` frontmatter with a `name` matching the skill's URI and a `description`; add these fields to older resource-only skills before downloading them. Digest or size mismatches raise an error before writing. `overwrite=True` replaces the existing skill folder, including removing locally added files.+If a folder uses a custom main filename, create a standard `SKILL.md` with those fields and update affected relative references before exporting it as a skill. Existing resource providers can still serve the original documents through `resources/read`.+## Current limits- A provider added with a namespace or other transforms isn't discoverable; mount a server instead.diff --git a/examples/skills/README.md b/examples/skills/README.mdindex 7f5ae14b5..a2c74e66c 100644--- a/examples/skills/README.md+++ b/examples/skills/README.md@@ -1,104 +1,34 @@-# Skills Provider Example+# Skills over MCP-This example demonstrates how to expose agent skills (like Claude Code skills) as MCP resources.+The server loads the two sample folders into `Skill` values and publishes them+through `SkillCatalogProvider`. Each `SKILL.md` declares its name and description;+supporting files retain their exact bytes.-## Structure+Run the client from the repository root:+```bash+uv run python -m examples.skills.client```-skills/-βββ README.md # This file-βββ server.py # MCP server that exposes skills-βββ client.py # Example client that discovers and reads skills-βββ sample_skills/ # Example skills directory- βββ pdf-processing/- β βββ SKILL.md # Main skill file- β βββ reference.md # Supporting documentation- βββ code-review/- βββ SKILL.md # Main skill file-```--## Running the Example--1. Start the server:- ```bash- uv run python examples/skills/server.py- ```--2. In another terminal, run the client:- ```bash- uv run python examples/skills/client.py- ```--## How It Works--The skills provider system has a two-layer architecture:--- **`SkillProvider`** - Handles a single skill folder, exposing its files as resources-- **`SkillsDirectoryProvider`** - Scans a directory, creates a `SkillProvider` per folder-- **`ClaudeSkillsProvider`** - Convenience subclass for Claude Code skills (~/.claude/skills/)--For each skill, the provider exposes:-- A **Resource** for the main file (`skill://{name}/SKILL.md`)-- A **Resource** for a synthetic manifest (`skill://{name}/_manifest`)-- Supporting files via **ResourceTemplate** or **Resources** (configurable)--### Progressive Disclosure--When a client lists resources, they see skill names and descriptions (from frontmatter) without fetching the full content. This keeps the discovery cost low.--By default, supporting files are exposed via ResourceTemplate (hidden from `list_resources()`). Set `supporting_files="resources"` to make them visible:--```python-SkillsDirectoryProvider(roots=skills_dir, supporting_files="resources")-```--### The Manifest--The `_manifest` resource provides a JSON listing of all files in a skill:--```json-{- "skill": "pdf-processing",- "files": [- {"path": "SKILL.md", "size": 1234, "hash": "sha256:abc..."},- {"path": "reference.md", "size": 5678, "hash": "sha256:def..."}- ]-}-```--This enables clients to download entire skills for local use.-## Usage Examples+It connects to the example server in memory, discovers entries through the+Skills extension, verifies each complete skill and exports it to a temporary+directory. The temporary copies are removed when the example exits. No local+agent's skills folder is changed.-### Single Skill+The last connection uses resource-only discovery with `list_skill_summaries()`.+`read_skill()` downloads the same content through the `_manifest` fallback, so+this also works when the connection does not negotiate Skills.-```python-from pathlib import Path-from fastmcp import FastMCP-from fastmcp.server.providers.skills import SkillProvider+To launch the server over stdio for another MCP client:-mcp = FastMCP("My Skill")-mcp.add_provider(SkillProvider(Path.home() / ".claude/skills/pdf-processing"))-mcp.run()+```bash+uv run python -m examples.skills.server```-### All Skills in a Directory+For live recursive folder discovery, use+`SkillsDirectoryProvider(root, experimental_skills=True)`. The catalog in this+example holds snapshots: changing a source file does not mutate an existing+`Skill`.-```python-from fastmcp.server.providers.skills import SkillsDirectoryProvider--mcp = FastMCP("Skills")-mcp.add_provider(SkillsDirectoryProvider(roots=Path.home() / ".claude" / "skills"))-mcp.run()-```--### Claude Code Skills (default location)--```python-from fastmcp import FastMCP-from fastmcp.server.providers.skills import ClaudeSkillsProvider--mcp = FastMCP("My Skills")-mcp.add_provider(ClaudeSkillsProvider()) # Uses ~/.claude/skills/-mcp.run()-```+See [Skills over MCP](https://gofastmcp.com/servers/skills) for custom loaders,+access control, mounts and installing skills into a local agent.diff --git a/examples/skills/client.py b/examples/skills/client.pyindex d5005ac23..7eaad8401 100644--- a/examples/skills/client.py+++ b/examples/skills/client.py@@ -1,65 +1,29 @@-"""Example: Skills Client--This example shows how to discover and download skills from a skills server.--Run this client (it starts its own server internally):- uv run python examples/skills/client.py-"""+"""Discover, read and export Skills: uv run python -m examples.skills.client"""import asyncio-import jsonfrom pathlib import Path+from tempfile import TemporaryDirectory+from examples.skills.server import mcpfrom fastmcp import Client-from fastmcp.server.providers.skills import SkillsDirectoryProvider-+from fastmcp.skills import SkillsClientExtension+from fastmcp.utilities.skills import list_skill_summaries-async def main():- # Create a skills provider pointing at our sample skills- skills_dir = Path(__file__).parent / "sample_skills"- provider = SkillsDirectoryProvider(roots=skills_dir)- # Connect to a FastMCP server with this provider- from fastmcp import FastMCP-- mcp = FastMCP("Skills Server")- mcp.add_provider(provider)+async def main() -> None:+ async with Client(mcp, extensions=[SkillsClientExtension()]) as client:+ for entry in await client.list_skills():+ skill = await client.read_skill(entry.uri)+ print(f"{skill.name}: {skill.description}")+ print(f"Verified files: {', '.join(skill.files)}")+ with TemporaryDirectory() as directory:+ folder = skill.to_directory(Path(directory) / skill.name)+ print(f"Exported {folder.name} to a temporary directory")async with Client(mcp) as client:- print("Connected to skills server\n")-- # List available resources- print("=== Available Resources ===")- resources = await client.list_resources()- for r in resources:- print(f" {r.uri}")- if r.description:- print(f" Description: {r.description}")- print()-- # List resource templates- print("=== Resource Templates ===")- templates = await client.list_resource_templates()- for t in templates:- print(f" {t.uri_template}")- print()-- # Read a skill's main file- print("=== Reading pdf-processing/SKILL.md ===")- result = await client.read_resource("skill://pdf-processing/SKILL.md")- print(result[0].text[:500] + "...\n")-- # Read the manifest to see all files- print("=== Reading pdf-processing/_manifest ===")- result = await client.read_resource("skill://pdf-processing/_manifest")- manifest = json.loads(result[0].text)- print(json.dumps(manifest, indent=2))- print()-- # Read a supporting file via template- print("=== Reading pdf-processing/reference.md ===")- result = await client.read_resource("skill://pdf-processing/reference.md")- print(result[0].text[:500] + "...\n")+ summaries = await list_skill_summaries(client)+ skill = await client.read_skill(summaries[0].uri)+ print(f"Resource-only discovery and download: {skill.name}")if __name__ == "__main__":diff --git a/examples/skills/download_skills.py b/examples/skills/download_skills.pydeleted file mode 100644index c6e571c57..000000000--- a/examples/skills/download_skills.py+++ /dev/null@@ -1,82 +0,0 @@-"""Example: Downloading skills from an MCP server.--This example shows how to use the skills client utilities to discover-and download skills from any MCP server that exposes them via a skills provider.--Run this script:- uv run python examples/skills/download_skills.py--This example creates an in-memory server with sample skills. In practice,-you would connect to a remote server URL instead.-"""--import asyncio-import tempfile-from pathlib import Path--from rich.console import Console-from rich.panel import Panel-from rich.table import Table-from rich.tree import Tree--from fastmcp import Client, FastMCP-from fastmcp.server.providers.skills import SkillsDirectoryProvider-from fastmcp.utilities.skills import list_skills, sync_skills--console = Console()---async def main():- # For this example, we'll create an in-memory server with skills.- # In practice, you'd connect to a remote server URL.- skills_dir = Path(__file__).parent / "sample_skills"- mcp = FastMCP("Skills Server")- mcp.add_provider(SkillsDirectoryProvider(roots=skills_dir))-- async with Client(mcp) as client:- # 1. Discover what skills are available on the server- console.print()- console.print(- Panel.fit(- "[bold]Discovering skills on MCP server...[/bold]",- border_style="blue",- )- )-- skills = await list_skills(client)-- table = Table(title="Skills Available on Server", show_header=True)- table.add_column("Skill", style="cyan")- table.add_column("Description")- for skill in sorted(skills, key=lambda s: s.name):- table.add_row(skill.name, skill.description)- console.print(table)-- # 2. Download all skills to a local directory- console.print()- console.print(- Panel.fit(- "[bold]Downloading all skills to local directory...[/bold]",- border_style="green",- )- )-- with tempfile.TemporaryDirectory() as tmp:- paths = await sync_skills(client, tmp)-- tree = Tree(f"[bold]{tmp}[/bold]")- for skill_path in sorted(paths, key=lambda p: p.name):- skill_branch = tree.add(f"[cyan]{skill_path.name}/[/cyan]")- for f in sorted(skill_path.rglob("*")):- if f.is_file():- rel = f.relative_to(skill_path)- skill_branch.add(str(rel))-- console.print(tree)- console.print(- f"\n[green]β[/green] Downloaded {len(paths)} skills to local directory"- )---if __name__ == "__main__":- asyncio.run(main())diff --git a/examples/skills/sample_skills/code-review/SKILL.md b/examples/skills/sample_skills/code-review/SKILL.mdindex 0c57545d8..3944084c6 100644--- a/examples/skills/sample_skills/code-review/SKILL.md+++ b/examples/skills/sample_skills/code-review/SKILL.md@@ -1,4 +1,5 @@---+name: code-reviewdescription: Review code for quality, maintainability, and correctnessversion: "1.0.0"tags: [code, review, quality]diff --git a/examples/skills/sample_skills/pdf-processing/SKILL.md b/examples/skills/sample_skills/pdf-processing/SKILL.mdindex 2490f6792..e0059e4ba 100644--- a/examples/skills/sample_skills/pdf-processing/SKILL.md+++ b/examples/skills/sample_skills/pdf-processing/SKILL.md@@ -1,4 +1,5 @@---+name: pdf-processingdescription: Extract text from PDFs, fill forms, and merge documentsversion: "1.0.0"tags: [document, pdf, extraction]diff --git a/examples/skills/server.py b/examples/skills/server.pyindex a5cd49947..eef184262 100644--- a/examples/skills/server.py+++ b/examples/skills/server.py@@ -1,49 +1,14 @@-"""Example: Skills Provider Server--This example shows how to expose agent skills as MCP resources.-Skills can be discovered, browsed, and downloaded by any MCP client.--Run this server:- uv run python examples/skills/server.py--Then use the client example to interact with it:- uv run python examples/skills/client.py-"""+"""Serve sample Skills. Run with: uv run python -m examples.skills.server"""from pathlib import Path-from fastmcp import FastMCP-from fastmcp.server.providers.skills import (- SkillsDirectoryProvider,-)--# Create server-mcp = FastMCP("Skills Server")--# Option 1: Load a single skill-# mcp.add_provider(SkillProvider(Path.home() / ".claude/skills/pdf-processing"))--# Option 2: Load all skills from a custom directory-skills_dir = Path(__file__).parent / "sample_skills"-mcp.add_provider(SkillsDirectoryProvider(roots=skills_dir, reload=True))--# Option 3: Load skills from a platform's default location-# mcp.add_provider(ClaudeSkillsProvider()) # ~/.claude/skills/+from fastmcp import FastMCP, Skill+from fastmcp.skills.provider import SkillCatalogProvider-# Option 4: Load from multiple directories (in precedence order)-# mcp.add_provider(SkillsDirectoryProvider(roots=[-# Path.cwd() / ".claude/skills", # Project-level first-# Path.home() / ".claude/skills", # User-level fallback-# ]))+root = Path(__file__).parent / "sample_skills"+skills = [Skill.from_directory(folder) for folder in sorted(root.iterdir())]+mcp = FastMCP("Skills Server", providers=[SkillCatalogProvider(skills)])-# Other vendor providers available:-# - CursorSkillsProvider() β ~/.cursor/skills/-# - VSCodeSkillsProvider() β ~/.copilot/skills/-# - CodexSkillsProvider() β ~/.codex/skills/-# - GeminiSkillsProvider() β ~/.gemini/skills/-# - GooseSkillsProvider() β ~/.config/agents/skills/-# - CopilotSkillsProvider() β ~/.copilot/skills/-# - OpenCodeSkillsProvider() β ~/.config/opencode/skills/if __name__ == "__main__":mcp.run()