Document serving skills from a directory

Author: vijaydeepsinha

docs/advanced/skills.md

@@ -22,6 +22,10 @@ skim that page first.
     list, or a directory you walk yourself — and you serve each skill's files as ordinary resources
     through `MCPServer.add_resource` or an `@mcp.resource(...)` template handler.
 
+    `SkillCatalog` is a provider built on top of `Skills` that implements these handlers for a
+    source of skill files, such as a local directory. See
+    [Serving skills from a directory](#serving-skills-from-a-directory).
+
 ## Serving a skill
 
 Here's a server that serves one skill:
@@ -116,6 +120,124 @@ capabilities. Omitting it advertises neither the setting nor the method — a cl
 `read_directory` raises before it sends anything if the connected server hasn't advertised the
 setting.
 
+## Serving skills from a directory
+
+`SkillCatalog` is a `Skills` extension that discovers skills in a `SkillProvider` and answers
+`skills/list`, `skills/get`, and optionally `resources/directory/read` from what it finds. It
+removes the need to write handlers or to register each file as a resource.
+
+```python title="server.py" hl_lines="11-15"
+--8<-- "docs_src/skills/tutorial002.py"
+```
+
+`SkillCatalog.load()` is a coroutine, so the server is constructed inside a running event loop.
+`FilesystemSkillProvider` reads skills from a local directory. `parse_frontmatter` supplies the
+YAML parser; the SDK does not depend on one.
+
+### How skills are discovered
+
+A skill is a directory that contains a `SKILL.md` file. The skill's files are all files beneath
+that directory, including the files of any skill nested inside it. A nested skill is also listed
+as a skill in its own right.
+
+Each file is served as a `skill://` resource. Its URI is `skill://` followed by its path, with
+each path segment percent-encoded. A file has the same URI regardless of which skill lists it.
+
+Files and directories whose names begin with `.` are excluded. They are never read, listed, or
+served. Files outside any skill directory are not served.
+
+The catalog reads and hashes every file once, when `load()` runs, and serves that snapshot. The
+`resources` manifest of each skill therefore describes the files exactly as they were read.
+The catalog is fixed for the lifetime of the server; to publish changes, create a new catalog.
+
+### Options
+
+`SkillCatalog.load(provider, *, parse_frontmatter, ...)` accepts the following arguments.
+
+| Argument | Default | Description |
+|---|---|---|
+| `provider` | required | The `SkillProvider` that lists and reads the files. |
+| `parse_frontmatter` | required | Receives the text between the `---` lines of a `SKILL.md` and returns a mapping with `str` keys, for example `yaml.safe_load`. |
+| `strict` | `False` | Controls the handling of invalid skills. See [Invalid skills](#invalid-skills). |
+| `directory_read` | `False` | Serves `resources/directory/read` and advertises the `directoryRead` setting. |
+| `ttl_ms` | `0` | The `ttlMs` value set on `skills/list`, `skills/get` and directory read results. |
+| `cache_scope` | `"private"` | The `cacheScope` value set on the same results. |
+| `page_size` | `None` | The maximum number of entries in one `skills/list` or directory read response. See [Pagination](#pagination). |
+
+`ttl_ms` and `cache_scope` follow the rules described in
+[Protocol version and caching](#protocol-version-and-caching). A negative `ttl_ms` raises
+`ValueError`.
+
+The frontmatter mapping is returned in `skills/list` and `skills/get` without modification,
+including keys the SDK does not interpret. Values are converted to JSON; for example, YAML dates
+are returned as ISO 8601 strings. A value with no JSON representation, such as NaN, makes the
+skill invalid.
+
+With `directory_read=True`, every directory that contains a served file can be read, including
+directories above the skill root such as `skill://acme`. A directory lists its direct children;
+subdirectories are returned with the MIME type `inode/directory`. Empty directories are not served.
+
+### Pagination
+
+By default, `skills/list` and `resources/directory/read` return every entry in a single response.
+When `page_size` is set, each response contains at most that many entries, and a response that is
+followed by another page carries a `nextCursor`. The client passes it back as `cursor`, as for any
+other paginated list in the protocol. `SkillsClient.list_skills()` and `read_directory()` do this
+automatically.
+
+A skill entry is never split across pages. The cursor is opaque to clients. A cursor that the
+catalog did not issue is rejected with Invalid params (`-32602`), and so is any cursor when
+`page_size` is not set. A `page_size` below 1 raises `ValueError`.
+
+### Invalid skills
+
+A skill is invalid when its `SKILL.md` has no frontmatter block, has an unterminated block, cannot
+be parsed, or fails the SEP-2640 requirements for `name` and `description`. A `SKILL.md` placed
+directly in the provider root is also invalid, because the skill has no directory name.
+
+* With `strict=False`, an invalid skill is omitted and a warning is logged.
+* With `strict=True`, `load()` raises a single `ValueError` that lists every invalid skill.
+
+A skill whose manifest exceeds the 512 files or 16 MiB recommended by SEP-2640 is still served,
+and a warning is logged.
+
+### File content
+
+`SKILL.md` and other Markdown files are served as `text/markdown`, and YAML files as
+`application/yaml`. The MIME type of any other file is determined with `mimetypes`, with
+`application/octet-stream` as the fallback.
+
+File content is returned unchanged. A file whose bytes are valid UTF-8 is returned as text,
+including any byte order mark and line endings; any other file is returned as a base64 blob. In
+both cases the content matches the `digest` and `size` in the skill's manifest. Each read is
+verified against the values recorded at load time, and a file that has changed is reported as an
+internal error (`-32603`).
+
+### Providers
+
+A `SkillProvider` supplies the files to the catalog. It is a `typing.Protocol`, so an
+implementation does not need to subclass it.
+
+```python
+class SkillProvider(Protocol):
+    async def list_files(self) -> Sequence[str]: ...
+    async def read_file(self, path: str) -> bytes: ...
+```
+
+`list_files()` returns the path of every file, recursively and without directories. `read_file()`
+returns the raw bytes of one file. Paths use `/` as the separator and are relative to the root of
+the provider. A provider can therefore be backed by any storage, such as an archive, a database,
+or object storage.
+
+`load()` raises `ValueError` if the provider lists a path that is empty, absolute, contains a `.`
+or `..` segment, is listed more than once, or lies beneath another listed file. This applies
+regardless of `strict`, because it indicates an error in the provider rather than in a skill.
+
+`FilesystemSkillProvider(root)` is the provider for a local directory. It serves regular files
+only. Symbolic links and Windows junctions are never followed: they are omitted, with a warning,
+when listing, and refused when read. A skill directory therefore cannot expose files outside
+itself. Blocking file system calls run in a worker thread.
+
 ## Protocol version and caching
 
 In protocol version `2026-07-28` and later, `skills/list`, `skills/get`, and
@@ -134,3 +256,12 @@ your own handler, to decide.
 
 If you're looking for "scan this directory and serve whatever's in it," you're looking for a
 provider built on top of `Skills`, not `Skills` itself.
+
+[`SkillCatalog`](#serving-skills-from-a-directory) is such a provider. It has the following
+limitations:
+
+* It does not include a YAML parser. The `parse_frontmatter` argument supplies one.
+* The catalog is not reloaded. To publish changes, create a new catalog.
+* Empty directories are not served by directory reads.
+* Pagination is opt-in through `page_size`. Without it, `skills/list` and directory reads return
+  all entries in a single response.

docs_src/skills/skills/git-workflow/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: git-workflow
+description: Follow this team's Git conventions for branching and commits
+---
+
+Branch from `main` using `type/short-description`. Write commit subjects in the
+imperative mood, under 72 characters.
+
+See [references/conventions.md](references/conventions.md) for the full list.

docs_src/skills/skills/git-workflow/references/conventions.md

@@ -0,0 +1,5 @@
+# Conventions
+
+- Branch names: `feat/`, `fix/` or `docs/` followed by a short description.
+- One logical change per commit.
+- Reference the issue number in the commit body, never in the subject.

docs_src/skills/tutorial002.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+import anyio
+import yaml
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.skills import FilesystemSkillProvider, SkillCatalog
+
+
+async def build_server(root: Path) -> MCPServer:
+    catalog = await SkillCatalog.load(
+        FilesystemSkillProvider(root),
+        parse_frontmatter=yaml.safe_load,
+        directory_read=True,
+    )
+    return MCPServer("skills", extensions=[catalog])
+
+
+async def main() -> None:
+    server = await build_server(Path(__file__).parent / "skills")
+    await server.run_stdio_async()
+
+
+if __name__ == "__main__":
+    anyio.run(main)

tests/docs_src/test_skills.py

@@ -1,9 +1,11 @@
 """`docs/advanced/skills.md`: every claim the page makes, proved against the real SDK."""
 
+from pathlib import Path
+
 import pytest
 from mcp_types import INVALID_PARAMS, TextResourceContents
 
-from docs_src.skills import tutorial001
+from docs_src.skills import tutorial001, tutorial002
 from mcp import Client
 from mcp.client.extensions.skills import Skills
 from mcp.shared.exceptions import MCPError
@@ -45,3 +47,24 @@ async def test_the_skill_file_is_served_as_an_ordinary_resource() -> None:
     assert isinstance(contents, TextResourceContents)
     assert contents.mime_type == "text/markdown"
     assert contents.text == tutorial001.SKILL_MD
+
+
+async def test_a_directory_of_skills_is_served_with_no_handlers() -> None:
+    """tutorial002: `SkillCatalog` over `FilesystemSkillProvider` lists the sample skill and its files."""
+    server = await tutorial002.build_server(Path(tutorial002.__file__).parent / "skills")
+    skills = Skills()
+    async with Client(server, extensions=[skills]) as client:
+        skill = (await client.extension(Skills).list_skills())[0]
+        children = await client.extension(Skills).read_directory("skill://git-workflow/references")
+        contents = (await client.read_resource("skill://git-workflow/references/conventions.md")).contents[0]
+
+    assert skill.uri == "skill://git-workflow/SKILL.md"
+    assert skill.frontmatter["name"] == "git-workflow"
+    assert isinstance(skill.resources, list)
+    assert [r.uri for r in skill.resources] == [
+        "skill://git-workflow/SKILL.md",
+        "skill://git-workflow/references/conventions.md",
+    ]
+    assert [r.uri for r in children] == ["skill://git-workflow/references/conventions.md"]
+    assert isinstance(contents, TextResourceContents)
+    assert contents.text.startswith("# Conventions")