pi-mcp-skills

pi extension that discovers and loads MCP skills from the servers pi is already connected to.

SEP-2640 (Final, merged 2026-09-13) added the Skills extension to MCP. The SEP page is a historical record. This package implements the client and lookup side of the stable specification that replaced it (modelcontextprotocol/ext-skills specification/stable/skills.mdx, base protocol 2026-07-28). The extension id is io.modelcontextprotocol/skills.

A skills server lists skill entries with skills/list. Each entry names a SKILL.md resource, the Agent Skills frontmatter, and either a complete file manifest (URI, sha256 digest, and size) or the string dynamic. The client fetches file bytes with resources/read only when a skill is inspected, loaded, or a supporting file is read, then checks the digest, the size, and the frontmatter. skills/get loads one skill by URI when a page of the list omitted it, and it is how a stale manifest is refreshed.

Install

Node 22. The peer dependency is @earendil-works/pi-coding-agent 1.0.1. The same hook also patches the bundled connection class current pi builds load from dist/bundle/chunks/runtime-*.js, which is what pi 1.1 uses.

pi install npm:pi-mcp-skills

The package contributes ./index.ts through the pi.extensions field. It uses the MCP servers already configured in mcp.json and the servers other extensions register with pi.registerMcpServer. It does not open a second MCP connection, and it does not replace /mcp. There is no slash command.

Tools

mcp_skills_search prints the catalog: collisions, unconfirmed instruction URIs, and rejected entries. Loading asks for confirmation that names the server, URI, name, and description. The SKILL.md body is fetched after that approval, not before. Print mode has no confirmation UI, so a load there is refused.

Loading asks for confirmation when approval mode is ui (the default). The approval is remembered for the session and is bound to the resource set (URI, digest, and size).

Set approvals to tool when there is no UI, or when a tool call should grant the approval. Pass --mcp-skills-approvals tool, or set PI_MCP_SKILLS_APPROVALS=tool. The environment variable wins. In that mode the dialogs are not opened. mcp_skills_load, mcp_skills_read, and mcp_skills_directory proceed only when their approve argument is true. bash, shell, and exec stay blocked until mcp_skills_allow_exec is called with approve: true. ui mode ignores approve and still uses the confirm dialog. A dynamic skill asks every time, and that approval does not cover later bytes. While any skill is loaded, bash, shell, and exec ask again. A read of a different server names both servers in its own confirmation. allowed-tools in frontmatter is ignored. Skill files are not executed.

The cache is in memory, keyed by server, URI, and digest. A cache hit is hashed again before use. Disconnecting the server drops its cache, its approvals, and its acting skills.

How lookup runs

1. On startup the extension patches McpClient.connect and McpServerConnection.connectOnce / getClient. It patches both copies pi might construct: dist/extensions/mcp/runtime.js, and the class re-exported by dist/bundle/chunks/runtime-*.js. initialize gains capabilities.extensions["io.modelcontextprotocol/skills"] = {}. A connection that is already open is adopted on the next getClient. Each connection is handed to the skills host under entry.name, the host-assigned label.
2. If that server's initialize result does not declare the extension, the host stops. If it declares the extension and omits resources, the host records an error and does not call skills/list.
3. Otherwise the host pages through skills/list, keeps valid entries, and records why the others were rejected. It subscribes to notifications/resources/list_changed and notifications/skills/list_changed and lists again when either arrives. session_start and mcp_servers_change forget extension-registered servers that disappeared. Servers that exist only in mcp.json stay until their connection closes, because getMcpServers() does not include them.
4. skills/get is used when a URI was not on the fresh list, when the list's ttlMs has elapsed, and when fetched bytes do not match the manifest. A resources set that changed revokes the approval.
5. File bytes are checked against the listed digest and size. SKILL.md frontmatter is parsed as YAML (core schema; timestamps become ISO strings) and compared field by field with the entry. A mismatch is a failed load, and the bytes are not treated as the skill.

Compliance

Source of truth: stable Skills extension, base protocol 2026-07-28. SEP-2640 Final (2026-09-13) is the historical record. Where they disagree, the stable spec wins and the note says so.

Readings and notes

• C03. pi-mcp 1.0.1 ClientCapabilities omits extensions, and the built-in MCP extension does not pass any. The attach hook adds the field on the existing McpClient before initialize.

• C09. The Final SEP left caching attributes on skills/get open and required them on skills/list only for protocol 2026-07-28+. The stable spec requires them on both results. Older negotiated protocols may omit them; this client accepts that omission and still caches until a list-changed notification or until ttlMs elapses.

• C16. Hosts MAY accept larger skills. This client stops at the published limits so every conforming server is loadable and anything beyond them is explained instead of failing on a later read.

• C23. Rules read from the Agent Skills specification (1–64 lowercase unicode letters or digits, hyphens not leading, trailing, or doubled). If that specification changes incompatibly, this client still accepts the previous naming rules.

• C42. pi 1.0.1 has no per-skill permission grant. This client never applies allowed-tools, so the field cannot widen access.

• C50. There is no on-disk skill cache, so the disk-cache integrity and durable-origin rules are met by not writing one. Restarting pi drops the cache and the remembered approvals.

• C51. The Final SEP and the stable spec do not define notifications/skills/list_changed. The working group previously pointed at resources/list_changed, and that is what pi's client already delivers. This client refreshes on that notification.

• C54. ExtensionAPI has no request or notification method. The workaround patches McpServerConnection.connectOnce, getClient, and McpClient.connect on the unbundled runtime and on the bundled runtime-*.js re-export.

• The stable spec mentions server/discover as the long-term way to negotiate extensions. pi 1.0.1 speaks initialize and stops at protocol 2025-11-25, so this client reads the extension from the initialize capabilities and does not call server/discover.

• pi's negotiated protocol is older than 2026-07-28, so a live server may omit resultType, ttlMs, and cacheScope. Those fields are required only when the negotiated version is 2026-07-28 or later. When they are present they are still checked.

• nextCursor of null or "" ends a page, matching pi's own client.

• An approval fingerprint includes size as well as URI and digest, which is the resources set the spec binds the approval to.

• Hosts may accept skills larger than 512 resources or 16 MiB. This client declines them and explains why.

• There is no on-disk skill cache, so the rules for a durable cache are met by not writing one.

• pi has no per-skill permission grant, so allowed-tools cannot be applied.

Development

npm test
npm run typecheck

Tests run on Node's built-in runner. Integration tests spawn tests/fixture-server.ts, a stdio server built with @modelcontextprotocol/sdk, through McpServerConnection.

License

MIT. Copyright (c) 2026 Richard Anaya.