Add TypeScript SDK for the Skills Extension SEP

[olaservo]

Summary

A TypeScript SDK + reference client/server demonstrating SEP-2640 (Skills Extension), serving Agent Skills as skill:// resources over MCP. Tracks the current SEP text on the sep/skills-extension branch, including the latest decision-log ADRs (2026-06-02 / 06-05 / 06-09). No protocol dependency beyond resources/read and the one new extension method below.

Note: this PR has evolved well past its original description. The latest commit (d12cc55) realigns the SDK to the current index schema and adds resources/directory/read; the summary below reflects the branch as it stands now.

skill:// resource convention

• Multi-segment paths with organizational prefixes (skill://acme/billing/refunds/SKILL.md)
• Final-path-segment = frontmatter name, and the no-nesting constraint — both enforced at discovery time
• Scheme-agnostic discovery: skill:// is SHOULD; index entries may use any scheme (repo://, github://, …)

skill://index.json (current SEP-2640 schema)

The index is the WG's own schema (decoupled from the agentskills.io .well-known format) with type-less entries:

• frontmatter — the skill's SKILL.md frontmatter copied verbatim as JSON (carries name/description and anything else authored)
• url + digest — when served as individual files; digest is sha256:{hex} over the SKILL.md raw bytes
• archives[] — { url, mimeType, digest } per packed form
• Every entry MUST have a url, a non-empty archives, or both. No $schema/version marker.

This replaces the earlier discriminated type: "skill-md" | "archive" | "mcp-resource-template" schema.

resources/directory/read (new extension method)

• Enumerate the files under a skill directory without knowing every URI — an ls-style, metadata-only, paginated, non-recursive listing. Directories are identified by mimeType: "inode/directory"; -32602 on a non-directory/unknown URI.
• Server: buildDirectoryTree() + makeDirectoryReadHandler(), installed on the low-level Server. Client: serverSupportsDirectoryRead(), readDirectory(), walkDirectory().
• Gated by a new capability flag directoryRead (default off).

Digest: integrity + caching

• verifyDigest() / readSkillUriVerified() — tamper/integrity check against the index digest (UTF-8 round-trip is byte-exact for SKILL.md, so a faithful read always matches).
• Caching pattern (the digest's headline purpose) documented: compare a stored index digest against the freshly-read one to skip refetching unchanged skills — no content hashing.

Extension declaration

• io.modelcontextprotocol/skills via native SDK registerCapabilities (v1.29+)
• declareSkillsExtension(server, { directoryRead: true }) to advertise the directory-read capability (paired with registerSkillResources(..., { directoryRead: true }))

Subpath exports

Import path	Purpose
root	Shared types, URI utilities, directory constants/schema
/server	Discover skills, register resources, generate the index, directory-read handler
/client	Discovery, reads, archive unpack, digest verify, directory read, catalog building

Removed since the original PR

• The mcp-resource-template index entry type and the parameterized-template serving feature (SkillTemplateDeclaration, listSkillTemplatesFromIndex) — it only existed to back the dropped index type. The catch-all supporting-files template stays.
• $schema field + validation and the SKILL_INDEX_SCHEMA constants.
• The well-known HTTP bridge (removed earlier in the branch).

Breaking changes

Yes — this is a clean rewrite of the index schema and removes the template surface. Package version bumped to 0.10.0 (pre-1.0).

Verification / test plan

• cd typescript/sdk && npm run build && npm test — clean tsc, 163 tests pass (new directory.test.ts; rewritten index-json.test.ts / register.test.ts)
• Reference client + server run end-to-end over stdio — index discovery, resources/directory/read enumeration + walkDirectory, archive fetch+unpack, digest verification (matches ✓), supporting-file flow
• Examples type-check against the built SDK

🦉 Generated with Claude Code

[olaservo]

Disclaimer: have been iterating through a few versions of this while clarifying the implementation guidance we'd want to add to the SEP or other docs. Mostly opened this for extra 👀 in case any of this was way off track. I'm not sure if we actually plan to publish a dedicated SDK around this extension, or just refer to code examples and link to implemenations.

[olaservo]

Closing since we will add this to the typescript SDK instead.