skills: add filesystem provider helper

[sambhav]

Summary

Add an optional filesystem provider for SEP-2640: discovery, metadata, complete manifests, lazy resource reads, directory browsing, pagination, and configurable catalog refresh.

This remains PR 2 of 2, stacked on #1238 and in draft. The branch includes the reviewed protocol revision at 21ad3c2. The helper-only comparison now contains only seven filesystem code/test/documentation files. After #1238 merges, this PR can be rebased onto main.

Usage

server := mcp.NewServer(&mcp.Implementation{Name: "skill-server", Version: "v1"}, nil)
if err := skills.AddDirectory(server, "./skills", nil); err != nil {
    log.Fatal(err)
}

Use AddFS with embed.FS, fstest.MapFS, or another fs.FS. Construct a DirectoryProvider directly when explicit Refresh is needed.

Behavior preserved

• Request-time skills/list, skills/get, resources/list, resources/read, and resources/directory/read discover additions, edits, removals, nested skills, supporting files, and empty directories.
• SKILL.md resource and directory metadata carries frontmatter name/description and text/markdown.
• Resource-list middleware merges all underlying pages with live filesystem metadata. Explicit resource registrations win URI collisions. It preserves parameters/results, propagates errors, rejects repeated cursors, and uses zero TTL/private scope.
• Cache nil rebuilds on each request. A supplied cache can preload, retain indefinitely, expire by MaxAge, accept Invalidate signals, or refresh explicitly. Failed rebuilds keep the old catalog stale and retry.
• File bytes are read on demand. Complete manifests remain static even when the catalog changes. Symlinks/non-regular files remain rejected; applications own watchers, mutable-filesystem synchronization, approvals, and shutdown.

Adaptation to #1238

Register the resource template before AddHandlers, satisfying its resources-capability check. Clients use the package-level session functions without AddClient/AddMethods or a wrapper.

Filesystem publication keeps the 512-file/16-MiB baseline by default. Explicit DirectoryOptions.ServerOptions.Limits can override publication caps; zero fields are unlimited. Limits/options are copied at construction, negative limits are rejected, and structural validation always runs. CatalogValidators adds application checks.

The stack update preserves both previous branch heads as ancestors; neither branch was force-pushed. No helper functionality moved into #1238.

Validation

Full Go tests, Skills race tests, and documentation generation passed. Vet/build passed with VCS stamping disabled for the linked worktree.

Reran conformance #330 at c4d79493f8013f18a7eb0bbe8aef584cff7b31aa using a temporary filesystem fixture with nested skills, supporting files, an empty directory, an ordinary registered resource, and page size 1:

Protocol / HTTP mode	Enumeration	Manifest	Directory	Total
2025-11-25 / stateful	30	6	7	43
2026-07-28 / stateless	32	6	7	45

Zero failures or warnings; two legacy version-conditioned skips. The underlying protocol also passed standard server/client conformance (40/239 checks).