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

1 participant