Serve Agent Skills over resources per SEP-2640

[anirudhmungre]

Implements the server side of SEP-2640 (Skills Extension, Extensions Track, Final): Agent Skills served over the existing Resources primitive. Opened as a draft — I'd rather agree the shape before filling in the remaining pieces listed at the bottom.

Closes #568.

What a server gets

capabilities = MCP::Server::Capabilities.new
capabilities.support_resources
capabilities.support_extensions(MCP::Skills.capability(directory_read: true))

server = MCP::Server.new(
  name: "billing_server",
  capabilities: capabilities,
  skills: [
    MCP::Skill.new(
      uri: MCP::Skills.uri_for("acme/billing/refunds"),
      frontmatter: { "name" => "refunds", "description" => "Process customer refund requests" },
      resources: [{ uri: MCP::Skills.uri_for("acme/billing/refunds"), digest: MCP::Skills.digest(skill_md), size: skill_md.bytesize }],
    ),
  ],
)

That answers skills/list, skills/get and resources/directory/read with no further wiring; skill content is read through the ordinary resources_read_handler.

• MCP::Skill is the entry shape both methods share, and enforces the extension's structural rules at construction: the URI addresses the skill's SKILL.md, the frontmatter carries name and description, that name equals the final skill-path segment, and the manifest is complete, duplicate-free and confined to the skill's root. resources: MCP::Skill::DYNAMIC covers generated skills. The per-skill limits (512 files, 16 MiB) are reported through #limit_violations and warned about at registration rather than enforced, since SEP-2640 leaves loading an oversized skill to the host.
• MCP::Skills carries the wire vocabulary and negotiation helpers, mirroring MCP::Apps.
• skills_list_handler / skills_get_handler / resources_directory_read_handler replace the defaults for catalogs a server cannot enumerate, and take server_context: on the same opt-in basis as resources_list_handler.

Decisions worth a look

• skills/list joins CACHEABLE_RESULT_METHODS; skills/get does not. The SEP requires the SEP-2549 hints on the listing at 2026-07-28 and explicitly leaves them open for skills/get, so that result stays hint-free rather than guessing.
• Declaring the extension without the resources capability raises at construction. The pairing is a MUST, and skill files are read through resources/read — the alternative is a server that lists skills nobody can read. It's the one place I've added a hard failure; happy to downgrade it to a warning.
• require_extension! tolerates either key form. An extension identifier is a String on the wire and often a Symbol when written in Ruby, so dig alone isn't enough. Same tolerance MCP::Apps.client_supports? already applies.
• Gating is consistent with every other capability-gated method, which means skills/list on a server that has not declared the extension now answers the capability error rather than -32601. This matches how prompts/list behaves without the prompts capability. A conforming client only calls these after seeing the declaration, so I don't think it's observable in practice — but it is a behavior change on an existing surface and worth flagging.
• resources/directory/read derives children from the registered manifests, which is exact for non-dynamic skills and saves every user reimplementing it. mimeType is inferred from the file extension through a small table and omitted when unknown; the handler block is there for anything the manifests don't describe.

Deliberately not in this PR

Staged the way go-sdk and typescript-sdk split theirs, and happy to fold any of it in here instead:

• Client wrappers (list_skills, get_skill, read_directory) — the SEP recommends them, and each wants the ListXResult struct and auto-paginating accessor the other client list methods have.
• A filesystem provider that builds a MCP::Skill from a directory by reading frontmatter and computing digests — the ergonomic entry point the SEP sketches, and the thing that makes this usable without hand-assembling manifests (go-sdk split this out the same way).
• ROADMAP.md, which names the unimplemented extensions — left alone rather than edited on your behalf.

Verification

• rake test — 1927 runs, 5257 assertions, 0 failures. 40 of those assertions are new, across test/mcp/skill_test.rb, test/mcp/skills_test.rb and test/mcp/server_skills_test.rb.
• rake rubocop — 168 files, no offenses.
• rake conformance:test did not run here: the @modelcontextprotocol/conformance package needs Node >= 22 and this machine has 20 (fs.globSync is missing). Nothing in the diff is reachable without the extension declaration, which no conformance scenario makes, but I haven't confirmed that locally — worth a CI eye.

[anirudhmungre]

@koic saw you picked my ticket up just recently - any thoughts on the shape here?

[koic]

Thank you for the detailed PR, and for writing up the decisions behind it. I read that section closely, and it is useful context.

I am going to close this PR, though, and keep #568 open. I would like to take the Skills extension forward myself and land it as a planned whole: the server side, the filesystem provider the SEP sketches for SDKs, and the client wrappers, together with the release planning around it. I also want to line up the shape with the MCP specification, the other SDKs' implementations (which are still open PRs at this point), and a few other considerations, so that the API does not have to move after it ships. I will do that in due course and track it on the issue.

None of this reflects on the quality of the work. The test suite, the linter, and the conformance suite pass locally on this branch, and the decisions you wrote down are exactly the kind of context that helps. I appreciate you taking the time.