Skip to content

feat(skills): publish skill://index.json + advertise skills extension (SEP-2640)#2762

Draft
SamMorrowDrums wants to merge 1 commit into
sammorrowdrums/skills-over-mcp-refactorfrom
sammorrowdrums/skill-discovery-index-extension
Draft

feat(skills): publish skill://index.json + advertise skills extension (SEP-2640)#2762
SamMorrowDrums wants to merge 1 commit into
sammorrowdrums/skills-over-mcp-refactorfrom
sammorrowdrums/skill-discovery-index-extension

Conversation

@SamMorrowDrums

Copy link
Copy Markdown
Collaborator

What

Makes the skill-discovery image emit the two pieces a SEP-2640-aware MCP client needs to enumerate skills without fetching every SKILL.md:

  1. skill://index.json resource — an Agent Skills discovery index built from the in-memory skill set. Each entry: { "type": "skill-md", "name", "description", "url": "skill://github/<name>/SKILL.md", "allowedTools": [...] }. $schema = https://schemas.agentskills.io/discovery/0.2.0/index.json.
  2. io.modelcontextprotocol/skills capability extension — advertised in the initialize result so clients opt into skill:// discovery.

Stacked on sammorrowdrums/skills-over-mcp-refactor (#2374). The branch already registers per-skill skill://github/<name>/SKILL.md resources and parses allowed-tools frontmatter; this PR exposes that same data through the well-known index + the capability flag.

Why

The skills-over-mcp-refactor branch lists skills only as individual resources/list entries, with allowed-tools buried inside each SKILL.md, and advertises no skills extension. A SEP-2640 client that gates on the extension + reads skill://index.json therefore discovers zero skills from the image. This PR closes that gap so the discovery index and the per-skill allow-lists are available up front, enabling clients to defer a skill's tools until the skill is loaded.

Implementation notes

  • Only the Extensions field is set on ServerOptions.Capabilities; the Go SDK still infers tools/resources/prompts from registered handlers (Server.capabilities() only fills nil fields), so advertising the extension does not clobber the existing capabilities.
  • The index reuses allSkills() / each skill's allowedTools — no new source of truth.

Tests

  • TestBuildSkillIndex / TestBuildSkillIndexJSON_IsValid — index shape: one skill-md entry per skill, correct url, non-empty allowedTools, valid JSON.
  • TestSkillsExtensionAndIndexAdvertised — end-to-end in-memory initialize: the skills extension is advertised (and tools/resources are still present), and skill://index.json serves the discovery shape.
  • gofmt, go vet, and the full pkg/github suite pass.

Verified against a SEP-2640 consumer

Built the binary from this branch and ran a real client discovery loop:

extensions advertised: {"io.modelcontextprotocol/skills":{}}
Discovered 27 skill(s) over MCP from server "github": get-context, explore-repo, ...
skills carrying allowedTools (deferral-ready): 27 / 27

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

Adds SEP-2640 skill discovery so skill-aware MCP clients can enumerate the
server's skills (and the tools each governs) from a single resource read,
without first fetching every SKILL.md.

- Register a `skill://index.json` resource whose handler emits the Agent Skills
  discovery index built from the in-memory skill set. Each entry carries
  `type: skill-md`, `name`, `description`, `url` (the skill's SKILL.md), and the
  skill's `allowedTools`, so clients can gate/defer those tools before loading
  the skill.
- Advertise the `io.modelcontextprotocol/skills` capability extension in the
  server's initialize result. Only the extension is set on ServerOptions, so the
  SDK still infers tools/resources/prompts capabilities from registered handlers.
- Tests: index builder shape + an end-to-end in-memory initialize asserting the
  extension is advertised (without clobbering tools/resources) and index.json
  serves the discovery shape.

Verified against the runtime SEP-2640 consumer: all 27 skills are discovered
with their allowed-tools lists.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant