Skip to content

πŸš€ 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.mdx
index 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 re
from fastmcp import FastMCP
from 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:
```python
from 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.md
index 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.py
index 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 json
from pathlib import Path
+from tempfile import TemporaryDirectory
+from examples.skills.server import mcp
from 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.py
deleted file mode 100644
index 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.md
index 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-review
description: Review code for quality, maintainability, and correctness
version: "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.md
index 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-processing
description: Extract text from PDFs, fill forms, and merge documents
version: "1.0.0"
tags: [document, pdf, extraction]
diff --git a/examples/skills/server.py b/examples/skills/server.py
index 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()