Skills over MCP

ToolRouter implements the draft SEP-2640 Skills Extension under the extension identifier io.modelcontextprotocol/skills. This page was verified against that 27 August 2026 draft snapshot and the working-group charter; the proposal remains in review, so its wire contract may change before it becomes final. ToolRouter tracks the current Resources-based design rather than the superseded skill://index.json experiment.

Every approved ToolRouter operation is published as an Agent Skill. The skill provides workflow instructions for calling ToolRouter's existing discover and use_tool tools; it does not bypass authentication, billing, approval, connector, policy, or human-review safeguards.

Capability negotiation

Skills-aware MCP clients request the extension during initialization:

json
{
  "capabilities": {
    "extensions": {
      "io.modelcontextprotocol/skills": {}
    }
  }
}

ToolRouter advertises:

json
{
  "capabilities": {
    "extensions": {
      "io.modelcontextprotocol/skills": {
        "directoryRead": true
      }
    }
  }
}

Clients that do not support the extension continue through ToolRouter's ordinary text tool flow. Both stdio and hosted HTTP retain initialization capabilities and omit Skills-specific resources for clients that did not negotiate the extension.

The legacy Streamable HTTP adapter keeps bounded, expiring sessions in one gateway process. Deploy it as a single replica or with session affinity; the planned MCP 2026-07-28 adapter removes this constraint with request-scoped capabilities.

Discovery and retrieval

  • skills/list returns stable, URI-sorted pages of up to 100 skill entries and an opaque nextCursor when another page exists.
  • skills/get returns one entry by its exact SKILL.md URI, whether or not the client saw it in a listing.
  • resources/read returns the SKILL.md or one of its referenced schema/example files.
  • resources/directory/read lists direct children of every directory in ToolRouter's skill:// namespace.

Each operation uses this URI shape:

text
skill://toolrouter/<tool-name>/<tool-name>-<operation-name>/SKILL.md

The directory segment immediately above SKILL.md matches the Agent Skills frontmatter name. Tool-qualified names avoid collisions across the catalogue. The entry's resources array is complete and includes the raw byte size and lowercase sha256:<hex> digest of every file. ToolRouter currently publishes SKILL.md, references/input-schema.json, references/examples.json, and references/output-schema.json when an output schema exists, and excludes any generated skill above SEP-2640's 512-resource or 16 MiB limit.

Progressive disclosure

Use skills/list metadata to decide whether a skill applies, then load only that skill's SKILL.md. Read its referenced schema or examples only when needed. Do not prefetch every file in the catalogue: SEP-2640 requires on-demand retrieval so connection cost scales with actual use rather than catalogue size.

The skill catalogue is public metadata and returns cacheScope: "public" with a five-minute freshness hint. File digests verify that a read matches the selected entry; they do not make server-supplied instructions inherently trusted. Hosts remain responsible for origin-aware identity, digest verification, user approval, collision handling, and treating a generic resources/read as transport rather than automatic skill activation.