Deliver tool-bound skills via a remote-skill MCP instead of a skill plugin + separate MCP

[Castrozan]

Idea

Collapse the two delivery surfaces for a tool-plus-manual capability into one. Instead of shipping an agent skill (deployed to disk) and a separate MCP server, ship a single MCP that serves its own skill instructions as MCP resources and fetches them on demand, the way the official Figma MCP does.

How Figma does it

The Figma MCP carries both the capability and its operating manual in one artifact:

• Tools (use_figma, create_new_file, get_metadata, ...) and the skills that govern them (figma-use, figma-generate-design, ...) ship together, versioned together.
• Skills are exposed as MCP resources, e.g. skill://figma/figma-use/SKILL.md, with disable-model-invocation: false frontmatter so the client can auto-load them.
• The server's own instructions gate tool use on the skill: "/figma-use MANDATORY before every use_figma call; fallback: skill://figma/figma-use/SKILL.md". When a skill is loaded via the resource fallback rather than as a registered slash-skill, the name is prefixed resource: for logging.
• Result: the agent pulls the manual only when it is about to use the tool, and never needs the skill deployed to disk.

Current state in this repo

A capability that needs both a tool and an operating manual ships as two-plus surfaces:

• Skills live under agents/skills/ and are deployed to ~/.claude/skills through the home/base/claude/skill-injection/ machinery (set builders, the claude-workspace launcher, per-session global vs interactive vs curated sets).
• MCP servers are wired separately under home/base/claude/mcps/ (stdio injection into .claude.json, the figma read/write split, etc.).
• The same skills are then re-ported into codex at activation (snapshot copy into .agents/plugins/, manifest at marketplace.json), so each provider gets its own deployed copy.

So a single tool that wants a mandatory operating manual touches: the skill source, the skill-injection wiring, the MCP registration, and the per-provider plugin port.

Proposal

For skills that exist to gate or operate an MCP tool, model the Figma pattern: have the MCP server expose those skills as skill://<server>/<skill>/SKILL.md resources with disable-model-invocation: false, gate the relevant tools on a mandatory skill, and let the client fetch the manual on demand instead of deploying it to disk per host and re-porting it per provider.

Benefits

• One delivery surface, one version bump; the tool and its manual can never drift out of lockstep.
• Provider-agnostic for free: any MCP client (Claude, codex, opencode, hermes) gets the skills via resources, eliminating the per-provider plugin port for these skills.
• No skill-injection wiring or on-disk deploy for MCP-bound skills.
• Leaner context: the manual loads only when the tool is about to be used, not eagerly at session start.

Scope / tradeoffs / open questions

• This fits tool-bound skills only (a skill that is the operating manual for an MCP tool). Standalone skills with no MCP behind them (git, obsidian, nix, humanize, ...) stay as deployed skill files; this is not a wholesale replacement.
• Confirm how Claude Code surfaces MCP-resource skills: as model-invocable /figma-use-style entries, or only via explicit ReadMcpResource. In this session the figma plugin loaded mid-session and never registered as a real /figma-use Skill tool, so it had to fall back to reading the resource by URI. Auto-invocation reliability is the load-bearing question.
• Network/availability: a remote HTTP MCP that is down takes its skills with it. A locally-run stdio MCP serving resources avoids that but reintroduces a local artifact.
• Authoring/hosting: who builds and hosts such an MCP for our own skills, and how skills get bundled as resources, is unspecified, this is a direction, not a design.

Acceptance / next step

Spike: pick one existing tool-bound skill, stand up (or extend) an MCP that serves it as a skill:// resource with disable-model-invocation: false, and verify the agent auto-loads and obeys it across Claude and codex without any on-disk skill deploy or per-provider port.