Add Skills Provider for exposing agent skills as MCP resources

docs/development/v3-notes/v3-features.mdx

@@ -672,6 +672,49 @@ Documentation: [FileSystemProvider](/servers/providers/filesystem)
 
 ---
 
+## SkillsProvider
+
+v3.0 introduces `SkillsProvider` for exposing agent skills as MCP resources ([#2944](https://github.com/jlowin/fastmcp/pull/2944)). Skills are directories containing instructions and supporting files that teach AI assistants how to perform tasks—used by Claude Code, Cursor, VS Code Copilot, and other AI coding tools.
+
+**Usage**:
+
+```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 with a `SKILL.md` file becomes a discoverable skill. Clients see:
+- `skill://{name}/SKILL.md` - Main instruction file
+- `skill://{name}/_manifest` - JSON listing of all files with sizes and hashes
+- `skill://{name}/{path}` - Supporting files (via template or resources)
+
+**Two-layer architecture**:
+- `SkillProvider` - Handles a single skill folder
+- `SkillsDirectoryProvider` - Scans directories, creates a `SkillProvider` per valid skill
+
+**Vendor providers** with locked default paths:
+
+| Provider | Directory |
+|----------|-----------|
+| `ClaudeSkillsProvider` | `~/.claude/skills/` |
+| `CursorSkillsProvider` | `~/.cursor/skills/` |
+| `VSCodeSkillsProvider` | `~/.copilot/skills/` |
+| `CodexSkillsProvider` | `/etc/codex/skills/`, `~/.codex/skills/` |
+| `GeminiSkillsProvider` | `~/.gemini/skills/` |
+| `GooseSkillsProvider` | `~/.config/agents/skills/` |
+| `CopilotSkillsProvider` | `~/.copilot/skills/` |
+| `OpenCodeSkillsProvider` | `~/.config/opencode/skills/` |
+
+**Progressive disclosure**: By default, supporting files are hidden from `list_resources()` and accessed via template. Set `supporting_files="resources"` for full enumeration.
+
+Documentation: [Skills Provider](/servers/providers/skills)
+
+---
+
 ## OpenTelemetry Tracing
 
 v3.0 adds OpenTelemetry instrumentation for observability into server and client operations ([#2869](https://github.com/jlowin/fastmcp/pull/2869)).

docs/docs.json

@@ -113,6 +113,7 @@
                   "servers/providers/prompts-as-tools",
                   "servers/providers/local",
                   "servers/providers/filesystem",
+                  "servers/providers/skills",
                   "servers/providers/mounting",
                   "servers/providers/proxy",
                   "servers/providers/custom"

docs/servers/providers/skills.mdx

@@ -0,0 +1,287 @@
+---
+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.
+
+## 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 all skill resources
+    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
+```
+
+## 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>
+
+## Complete Example
+
+This example creates a server that exposes Claude Code skills, then uses a client to discover and read them.
+
+```python
+import asyncio
+import json
+
+from fastmcp import Client, FastMCP
+from fastmcp.server.providers.skills import ClaudeSkillsProvider
+
+async def main():
+    # Create server with Claude skills
+    mcp = FastMCP("Skills Demo")
+    mcp.add_provider(ClaudeSkillsProvider(reload=True))
+
+    async with Client(mcp) as client:
+        # List available skill resources
+        resources = await client.list_resources()
+        print("Available skills:")
+        for r in resources:
+            if r.uri.path and r.uri.path.endswith("SKILL.md"):
+                print(f"  - {r.name}: {r.description}")
+
+        # Read a specific skill's manifest
+        manifest_result = await client.read_resource("skill://pdf-processing/_manifest")
+        manifest = json.loads(manifest_result[0].text)
+        print(f"\nFiles in pdf-processing skill:")
+        for f in manifest["files"]:
+            print(f"  - {f['path']} ({f['size']} bytes)")
+
+        # Read the main skill file
+        skill_result = await client.read_resource("skill://pdf-processing/SKILL.md")
+        print(f"\nSkill content:\n{skill_result[0].text[:500]}...")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```