Studio MCP: serve Studio's instructions and skills to external agents on demand

[youknowriad]

Related issues

• Fixes STU-2499
• Follows Studio Code: generate the tool list for live WordPress.com site sessions too #5004
• Part of the WordPress Studio plugin for Codex project; extracted from the proof of concept in Studio plugin for ChatGPT (Codex) and Claude Code (Proof of Concept) #4993

How AI was used in this PR

Written with Claude Code, extracted from the proof of concept in #4993 and cut down to what's used today. I reviewed the diff; Claude ran lint, typecheck and the CLI AI tests, compared Studio Code's prompts and tool lists before and after the change, checked studio mcp over stdio with an MCP client, and ran a full Codex build against it (codex exec, with the plugin's routing skill): Codex called studio_instructions first, loaded the site-spec, visual-design, imagery, block-content and visual-polish runbooks through it, and built and polished the site with no tool errors. Codex doesn't show MCP server instructions to the model, so in Codex the route to studio_instructions comes from the plugin's skill (STU-2506).

Proposed Changes

studio mcp lets other agents (Codex, Claude Code, …) use Studio's tools, but it gives them none of the instructions Studio Code works from: which skill to load when, how to validate blocks, how to polish the result. Those agents improvise the site workflow.

• A new studio_instructions tool returns Studio's instructions, in a version written for an agent that brings its own file tools and conversation: no Studio Code identity, and none of the Studio Code CLI's one-file-per-turn cadence. With skill, it returns that skill's runbook, rendered the same way Studio Code's Skill tool renders it.
• The server's own instructions are one line pointing at that tool. Hosts keep server instructions in context for every conversation and some truncate long ones, so the full text (about 22 KB) is only fetched when the agent starts site work. The WordPress Studio plugin's own skill will point there too (STU-2506).
• The runbooks are served by the installed CLI rather than copied into the plugin, so they always match the tools they describe. There's no separate Skill tool, so nothing clashes with a host's own Skill tool.
• Studio Code is unchanged: its prompts and tool lists are byte-for-byte the same in the app, the terminal, Playground sites and live WordPress.com sites, and its Skill tool returns the same runbooks. The evals run Studio Code's terminal prompt, which didn't change, so they weren't re-run.

Smaller than the issue's original plan: the tool registry already takes a description of the host (CreateStudioToolsOptions), so this PR doesn't rename it or add fields nothing reads yet. Design previews, host image tools and the preview reload add theirs with their own issues (STU-2500, STU-2501, STU-2503). The proposed lint rule keeping the tools free of pi imports is dropped too.

Testing Instructions

• npm test -- apps/cli/ai/tests/system-prompt.test.ts
• npm run cli:build, then connect any MCP client to node apps/cli/dist/cli/main.mjs mcp (e.g. npx @modelcontextprotocol/inspector node apps/cli/dist/cli/main.mjs mcp):
  • The server's instructions are one line asking to call studio_instructions first.
  • studio_instructions with no arguments returns the full instructions, starting with "These are the instructions for building and managing local WordPress sites with the WordPress Studio tools."
  • With { "skill": "visual-design" } it returns that runbook, with its catalog of directions and layouts filled in; an unknown skill is an error.

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

🤖 Generated with Claude Code

[wpmobilebot]

📊 Performance Test Results

Comparing e577921 vs trunk

app-size

Metric	trunk	e577921	Diff	Change
App Size (Mac)	1456.80 MB	1456.80 MB	+0.00 MB	⚪ 0.0%

site-editor

Metric	trunk	e577921	Diff	Change
load	1201 ms	1190 ms	11 ms	⚪ 0.0%

site-startup

Metric	trunk	e577921	Diff	Change
siteCreation	7058 ms	7058 ms	0 ms	⚪ 0.0%
siteStartup	3381 ms	3368 ms	13 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)