Add Skills-over-MCP SEP support to host

[olaservo]

Staging PR against the fork main for iteration and demo — not yet ready to forward upstream. Implements the host side of the Skills-over-MCP SEP (extension ID io.modelcontextprotocol/skills). Single squashed commit; this description is the implementation narrative.

What this does

Skills served by connected MCP servers are discovered at agent init via skill://index.json, surfaced into the model's context alongside filesystem-based skills, and loaded on demand through the existing read_skill tool (extended to accept resource URIs). One <available_skills> block in the system prompt unifies both sources — same XML shape, same loading tool, same relative-path resolution. The model never types a server name; the URI alone is enough for the host to route the read.

<available_skills>
  <skill>
    <name>pull-requests</name>
    <description>Workflows for creating, reviewing, and templating GitHub pull requests</description>
    <location>skill://pull-requests/SKILL.md</location>
    <directory>skill://pull-requests</directory>
  </skill>
</available_skills>

This is the lazy in-memory cell of the host-guide 2×2: fetch the index + each SKILL.md frontmatter at startup; defer body / supporting-file reads to the model.

How it's organized

Discovery lives in a new mcp/mcp_skills_loader.py. load_mcp_skill_manifests walks each connected server, reads skill://index.json (size-bounded, missing-index is silent), then fetches each skill-md entry's SKILL.md and parses frontmatter via the existing SkillRegistry.parse_manifest_text. merge_filesystem_and_mcp_manifests folds the discovered manifests into the filesystem set; filesystem wins on name collision.

Trust boundary. The reader (tools/skill_reader.py) admits a URI only if it descends from a discovered skill root, with raw and percent-encoded ../. rejected and query/fragment suffixes refused. file:// is rejected at both the loader and the reader as defense in depth — the SEP trust model treats the MCP server as the authority for content under its published roots, and admitting file:// collapses that to "whatever the server's process can read from disk." Each URI-backed manifest must name the server that published it (enforced as a SkillManifest invariant); without that, the aggregator would fall through every connected server until one answered, collapsing the per-server boundary.

Agent wiring. McpAgent.initialize() calls the loader after server connect and before _apply_instruction_templates() so the merged manifest set populates {{agentSkills}}. format_skills_for_prompt branches on uri vs path: URI-backed skills render <location>/<directory> as URIs and emit a one-paragraph preamble note; the <scripts>/<references>/<assets> subdirectory tags are suppressed (the host can't stat an MCP resource tree up front). skill_read_tool_name is forced to read_skill whenever any manifest is URI-backed — read_text_file would mangle a URI by treating it as a relative path under cwd. (Caught by the first live e2e run.)

Config. MCPServerSettings.mcp_skills: bool = True opts a server out of skill discovery while leaving its tools available. Independent of include_instructions.

Helpers. mcp/skill_uri.py holds two shared functions (strip_skill_md, skill_name_from_uri) used by the loader, registry, and reader. Both tolerate trailing slashes and reject degenerate shapes (e.g. skill://SKILL.md returns None) so a malformed entry can't seed skill:/ into the reader's allow-list.

Scheme-agnostic. Per the SEP, skill:// is SHOULD not MUST: the reader detects URIs by <scheme>:// shape and routes any URI through the aggregator if it descends from a discovered manifest root.

Out of scope

• type: "mcp-resource-template" index entries + completion-API discovery UI
• resources/subscribe for skill://index.json change notifications
• Eager-to-filesystem materialization (other cell of the host-guide 2×2)

Verification

• Skills unit suite: 95 passing (uv run pytest tests/unit/fast_agent/skills/)
• E2e validation against olaservo/github-mcp-server @ add-agent-skills lives in a sibling harness repo (kept outside this fork to keep it pure reference-host material)
• WG notes (fast-agent skills-over-mcp host - implementation recap.md) carry the activation-contamination audit and the conformance checklist against SEP host requirements

Related

• SEP draft: Add draft SEP for Skills Extension modelcontextprotocol/experimental-ext-skills#69
• Server side: olaservo/github-mcp-server add-agent-skills branch