Repository navigation
add first-class support for skills extension in McpServer #10016
Description
What is the problem this feature would solve?
Effect McpServers can publish tools, prompts, and resources, but authors have no dedicated API for publishing Agent Skills. Registering a SKILL.md resource alone does not provide skill discovery, metadata lookup, or a complete file manifest.
Mcp spec already has an extension for this: SEP-2640 which is Final. Implementation should target the maintained Skills extension specification.
What is the feature you are proposing to solve the problem?
Add a skill definition and registration API alongside McpServer.resource. Skills would have dedicated discovery through skills/list and skills/get, while their instructions and supporting files continue to use resources/read.
The API should derive frontmatter, file sizes, and SHA-256 digests from the same immutable content served to clients. Server authors should not need to calculate manifests or register discovery handlers themselves.
Proposed API:
const RefundsSkill = McpServer.skill({
uri: "skill://billing/refunds/SKILL.md",
frontmatter: {
name: "refunds",
description: "Process refunds using the billing tools"
},
instructions: String.stripMargin(`
|Read references/policy.md before issuing a refund.
|Use the billing tools to inspect the payment and submit the refund.
`),
files: {
"references/policy.md": {
mimeType: "text/markdown",
content: "Refunds above CHF 500 require manager approval.\n"
}
}
})
const McpLive = Layer.mergeAll(
RefundsSkill,
// PolicyResource
).pipe(
Layer.provide(
McpServer.layerHttp({
name: "billing",
version: "1.0.0",
path: "/mcp",
protocols: [McpProtocol.v2026_07_28]
})
)
)McpServer.skill would return a composable registration Layer, suitable for combining with existing tool, prompt, and resource registrations. There can then be sensible fallbacks to use this as a resource when capability of the client is missing or the protocol version is mismatched for extensions
What alternatives have you considered?
with a lot of the extensions (like Task) there are new rpc routes to handle so the only other way would be to allow some sort of hook into what routes can be defined so the author of the server can define the extension spec themselves.
This build on learnings and experiments from #8631
Activity
lloydrichards commentedon Oct 27, 2026
Added external conformance coverage for this in lloydrichards/proj_effect-mcp-conformance#8, using published Effect
4.0.6and the official conformance runner0.2.0-alpha.12.The three SEP-2640 scenarios show where resource registration is sufficient and where dedicated Skills support is needed:
sep-2640-skills-manifestresources/listandresources/readcan expose a discoverableSKILL.mdwith matching frontmatter and resource metadata.sep-2640-skills-enumerationskills/listreturns-32601 Method not found. A separate direct request confirms thatskills/getis also unavailable.sep-2640-skills-directoryresources/directory/readreturns-32601. This optional method is required whendirectoryRead: trueis declared.The fixtures explicitly declare the Skills extension to exercise its contract. Effect does not advertise this unsupported extension by default, and the fixtures do not supply replacement protocol handlers.
This is why registering a
SKILL.mdresource alone cannot implement the extension: the catalog and lookup methods are still missing, and a directory resource does not provide directory traversal. The official enumeration scenario stops afterskills/listfails, so entry manifests, digests, sizes, cache fields, and successful retrieval remain unverified.The conformance PR remains a draft with those failures visible. Contracts, raw results, and limitations.
typedrat commentedon Oct 27, 2026
We have an internal implementation of this at Synapdeck I can look into making upstreamable -- it's got some ugly hacks to get custom methods without modifying Effect itself that I'd love to rip out, and the actual protocol implementation is solid.
Add MCP Skills extension support to McpServer, closes Effect-TS#10016
Add MCP Skills extension support to McpServer, closes Effect-TS#10016
Add MCP Skills extension support to McpServer, closes Effect-TS#10016
Add MCP Skills extension support to McpServer, closes Effect-TS#10016
Add MCP Skills extension support to McpServer, closes Effect-TS#10016
Add MCP Skills extension support to McpServer, closes Effect-TS#10016