Skip to content

Add Skills Extension SEP reference implementation#71

Draft
olaservo wants to merge 8 commits intomainfrom
add-sep-example
Draft

Add Skills Extension SEP reference implementation#71
olaservo wants to merge 8 commits intomainfrom
add-sep-example

Conversation

@olaservo
Copy link
Copy Markdown
Member

@olaservo olaservo commented Mar 22, 2026 •
edited
Loading

Summary

Reference implementation of the Skills Extension SEP — a TypeScript SDK with working client and server examples. Zero protocol dependencies beyond resources/read.

What it demonstrates

  • skill:// resource convention — multi-segment paths with organizational prefixes (skill://acme/billing/refunds/SKILL.md)
  • skill://index.json — well-known discovery index following the Agent Skills format
  • Extension declaration — io.modelcontextprotocol/skills via native SDK registerCapabilities (v1.29.0)
  • Final-segment = name constraint — enforced at discovery time
  • No-nesting constraint — enforced at discovery time
  • SDK wrappers matching the SEP spec — listSkills(), listSkillsFromIndex(), readSkillUri(), readSkillContent(), readSkillManifest(), READ_RESOURCE_TOOL

What's included

Component Path Purpose
SDK typescript/sdk/ Server + client libraries (@modelcontextprotocol/ext-skills)
Server example examples/skills-server/ Discovers skills from disk, registers skill:// resources
Client example examples/skills-client/ 6-step demo exercising discovery, reading, and manifests
Sample skills examples/sample-skills/ 4 skills — 2 single-segment, 2 multi-segment under acme/
Docs examples/README.md Architecture diagrams, URI anatomy, SDK-to-protocol mapping

SEP compliance

Verified point-by-point against PR #69:

  • Extension identifier: io.modelcontextprotocol/skills in capabilities.extensions
  • skill:// URI scheme with SKILL.md explicit in all URIs
  • Final path segment = frontmatter name
  • No-nesting constraint enforced
  • skill://index.json with $schema, type: "skill-md", name, description, url
  • read_resource tool schema matches SEP (server + uri params)
  • Resource template skill://{+skillFilePath} for supporting files
  • size field on SKILL.md resources (SDK v1.29.0)

SDK status

Uses @modelcontextprotocol/sdk v1.29.0. Prior workarounds for extensions capability (_capabilities patching) have been replaced with the native registerCapabilities API. Remaining shims are tracked in the README table.

Test plan

  • cd typescript/sdk && npm install && npm run build && npm test — SDK compiles, 53 tests pass
  • cd examples/skills-server/typescript && npm install && npm run build — Server compiles
  • cd examples/skills-client/typescript && npm install && npm run build — Client compiles
  • node examples/skills-client/typescript/dist/index.js — 6-step demo runs end-to-end
  • Verify 4 skills discovered (code-review, git-commit-review, acme/billing/refunds, acme/onboarding)
  • Verify skill://index.json returns all 4 skills in Agent Skills discovery format

🤖 Generated with Claude Code

olaservo and others added 4 commits March 21, 2026 19:25
@olaservo @claude
Add Skills Extension SEP reference implementation
c2afcfc 
Reference implementation demonstrating the Skills Extension SEP with:
- skill:// resource convention with multi-segment paths
- Extension declaration (io.modelcontextprotocol/skills) via SEP-2133
- SEP-2093 shims: resources/metadata, URI-scoped resources/list,
  per-resource capabilities via _meta
- SDK with server-side discovery/registration and client-side wrappers
  (listSkills, readSkillUri, fetchSkillMetadata, READ_RESOURCE_TOOL)
- 4 sample skills: 2 single-segment, 2 multi-segment under acme/
- End-to-end client demo exercising all 7 features

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@olaservo @claude
Add TODO tracking links to all SDK shim workarounds
8028e6b 
Each shim function now has a TODO with the specific PR link for
when/if it can be removed. Uses "if" not "when" since the
upstream PRs are drafts not guaranteed to merge.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@olaservo @claude
Add architecture diagram for SEP reference implementation
353059f 
ASCII diagrams showing: overall system structure, URI anatomy,
discovery flow, SDK-to-protocol mapping, and what's permanent
SEP design vs temporary SDK shims.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@olaservo @claude
Rename ARCHITECTURE.md to README.md
a0db637 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@olaservo olaservo requested a review from a team as a code owner March 22, 2026 04:14
@olaservo @claude
Add skill://index.json discovery and remove SEP-2093 dependencies
762fb50 
Align the reference implementation with PR #69's SEP spec, which defines
skill://index.json as the primary enumeration mechanism and requires zero
protocol dependencies beyond resources/read.

Added:
- skill://index.json well-known discovery index (Agent Skills format)
- generateSkillIndex() server-side, listSkillsFromIndex() client-side
- SkillIndex/SkillIndexEntry types and INDEX_JSON_URI constant
- 53 tests across URI utilities, index round-trip, and client parsing

Removed (SEP-2093 features not in the SEP):
- resources/metadata handler and fetchSkillMetadata()
- Scoped resources/list(uri=...) and listSkillsScoped()
- Per-resource _meta capabilities on all resource registrations
- ResourceCapabilities/ResourceMetadataResult types
- Zod schemas and RequestHandlerRegistrar interface

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This was referenced Apr 13, 2026
Open
Open
@olaservo olaservo marked this pull request as draft April 13, 2026 03:47
This was referenced Apr 13, 2026
Closed
Open
olaservo and others added 3 commits April 13, 2026 05:54
@olaservo @claude
Define _meta scoping guidelines for skill resources (#60)
5ff0e56 
* Update skill-meta-keys.md to reference merged URI scheme doc

Replace PR #53 links with relative references to the now-merged
skill-uri-scheme.md document.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Refactor skilljack-mcp section and update notes on `_meta` keys for clarity

* Refocus _meta doc as scoping framework, not key recommendations

Address PR feedback: remove recommended keys that duplicate
frontmatter or belong at the plugin/distribution layer. Change
namespace to io.modelcontextprotocol.skills/. Establish scoping
principles for when _meta is appropriate vs frontmatter, annotations,
or distribution-layer mechanisms.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add decision record: _meta reserved for MCP-transport concerns

Records the decision from PR #60 review that skill-level semantics
stay in frontmatter, _meta is for MCP-transport-specific metadata,
and no specific keys are recommended yet.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
@olaservo @claude
Upgrade MCP SDK to v1.29.0: native extensions support, add resource size
103f66e 
Bump @modelcontextprotocol/sdk from 1.27.1 to 1.29.0, which includes
native extensions capability support (typescript-sdk#1811, backport of
#1630) and the missing size field on ResourceSchema (#1575).

- Replace private _capabilities hack in declareSkillsExtension with
  the SDK's native registerCapabilities API
- Add size field to SKILL.md resource metadata in registerSkillResources
- Keep ServerInternals as a deprecated alias for backward compatibility
- Update README shims table to reflect resolved workarounds

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@olaservo @claude
Fix comment to match actual resource template pattern
975e8d1 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@olaservo