@@ -132,7 +132,8 @@ removes the need to write handlers or to register each file as a resource.
 
 `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.
+YAML parser. The SDK does not install one, so this example uses [PyYAML](https://pypi.org/project/PyYAML/),
+which you add to your own project (`uv add pyyaml`).
 
 ### How skills are discovered
 
@@ -211,7 +212,10 @@ File content is returned unchanged. A file whose bytes are valid UTF-8 is return
 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`).
+internal error (`-32603`) until you restart the server or create a new catalog.
+
+`load()` reads and hashes every file of every valid skill once, so a large asset directory makes
+startup slower and temporarily uses memory for the largest file.
 
 ### Providers
 
 
@@ -10,7 +10,7 @@
 import re
 from collections.abc import Callable, Mapping, Sequence
 from pathlib import PurePosixPath
-from typing import Any, Literal, TypeVar
+from typing import Any, Literal, Self, TypeVar
 from urllib.parse import quote
 
 import anyio.to_thread
@@ -143,7 +143,7 @@ async def load(
         ttl_ms: int = 0,
         cache_scope: Literal["public", "private"] = "private",
         page_size: int | None = None,
-    ) -> SkillCatalog:
+    ) -> Self:
         """Scan `provider` and build a catalog of the skills it holds.
 
         A skill is a directory containing a `SKILL.md`; the skill's files are everything
@@ -176,6 +176,8 @@ async def load(
         """
         if page_size is not None and page_size < 1:
             raise ValueError("page_size must be at least 1")
+        if ttl_ms < 0:
+            raise ValueError("ttl_ms must not be negative")
         paths = _check_paths(list(await provider.list_files()))
         visible = [path for path in paths if not any(segment.startswith(".") for segment in path.split("/"))]
         skill_paths = sorted(path for path in visible if path.split("/")[-1] == _SKILL_FILE)
 
@@ -26,10 +26,13 @@
 class FilesystemSkillProvider:
     """A `SkillProvider` that reads skill files from a local directory.
 
-    Only regular files are served. Symlinks (and Windows junctions) are never
-    followed, so a skill directory can't expose files that live outside it; they
-    are skipped with a warning when listing and refused when read. The blocking
-    file system calls run in a worker thread.
+    Only regular files are served. Symlinks (and Windows junctions) found while
+    listing or reading are skipped with a warning or refused, so a skill directory
+    doesn't expose files that live outside it. The root is trusted: this is a
+    best-effort check, not a defence against someone who can modify the directory
+    while the server runs. `SkillCatalog` additionally refuses any file whose bytes
+    no longer match the digest taken when it was loaded. The blocking file system
+    calls run in a worker thread.
     """
 
     def __init__(self, root: str | os.PathLike[str]) -> None:
@@ -78,7 +81,7 @@ def _walk(self, directory: Path, prefix: list[str], files: list[str]) -> None:
                 self._walk(Path(entry.path), segments, files)
             elif stat.S_ISREG(result.st_mode):
                 files.append("/".join(segments))
-            else:  # pragma: lax no cover
+            else:  # pragma: lax no cover  # FIFO/device: no test on Windows
                 logger.warning("Skipping %s: not a regular file", entry.path)
 
     def _read_file(self, segments: list[str]) -> bytes:
@@ -94,7 +97,7 @@ def _read_file(self, segments: list[str]) -> bytes:
         fd = os.open(current, _READ_FLAGS)
         with os.fdopen(fd, "rb") as file:
             if not stat.S_ISREG(os.fstat(file.fileno()).st_mode):
-                raise OSError(f"{current} is not a regular file")  # pragma: lax no cover
+                raise OSError(f"{current} is not a regular file")  # pragma: lax no cover  # only if swapped after lstat
             return file.read()
 
 
 
@@ -657,6 +657,32 @@ async def test_a_negative_ttl_is_rejected_when_the_catalog_loads() -> None:
         await SkillCatalog.load(provider, parse_frontmatter=_parse, ttl_ms=-1)
 
 
+async def test_invalid_options_are_rejected_before_the_provider_is_touched() -> None:
+    """SDK-defined: option errors surface before any provider call; a call would raise `NotImplementedError`."""
+
+    class _UntouchableProvider:
+        async def list_files(self) -> Sequence[str]:  # pragma: no cover
+            raise NotImplementedError
+
+        async def read_file(self, path: str) -> bytes:  # pragma: no cover
+            raise NotImplementedError
+
+    with pytest.raises(ValueError):
+        await SkillCatalog.load(_UntouchableProvider(), parse_frontmatter=_parse, ttl_ms=-1)
+
+
+async def test_load_returns_an_instance_of_the_subclass_it_is_called_on() -> None:
+    """SDK-defined: `load()` is a classmethod constructor, so a subclass gets its own type back."""
+
+    class _CustomCatalog(SkillCatalog):
+        pass
+
+    provider = _MemoryProvider({"git-workflow/SKILL.md": _skill_md("git-workflow")})
+    catalog = await _CustomCatalog.load(provider, parse_frontmatter=_parse)
+
+    assert isinstance(catalog, _CustomCatalog)
+
+
 async def test_the_handler_aliases_stay_importable_from_the_package() -> None:
     """Compatibility: `mcp.server.skills` was a module before it became a package; its public names survive."""
     assert (GetSkillHandler, ListSkillsHandler, ReadDirectoryHandler) == (