Add respira-mcp skill: read/edit live WordPress sites via Respira MCP

[webmyc]

Summary

Adds a new skill (respira-mcp) for agents that have the Respira MCP server connected to a live WordPress site. Respira ships builder-aware tools (Gutenberg, Elementor, Divi 4 + 5, Bricks, Beaver, Oxygen, Breakdance, WPBakery, Brizy, Thrive Architect, Visual Composer, Flatsome) plus snapshots and audit, and this skill routes agents to the right tool subset for the user's intent and enforces the duplicate-before-edit + snapshot guarantees.

Without this skill, agents commonly:

• read entire pages with extract_builder_content for one-line edits,
• skip the duplicate-before-edit safety pattern,
• guess module slugs that drifted between Divi 4 and Divi 5,
• forget to surface the snapshot_id so the user has an undo handle.

Why this fits here

wordpress-router already classifies the repo and delegates. When the agent's host also has live-site tools available (Respira MCP), the next decision is "what tools cover what change". This skill answers that decision in a procedure-style document with frontmatter that matches the repo's authoring contract.

Files

• skills/respira-mcp/SKILL.md — procedure + verification + failure modes
• skills/respira-mcp/references/tools-by-category.md — full tool inventory grouped by find / read / write / structural / snapshot / audit / WooCommerce
• skills/respira-mcp/references/builder-routing.md — builder-to-tool matrix with first-class vs partial support per builder
• skills/respira-mcp/references/safety-and-snapshots.md — duplicate-before-edit, snapshot/restore, dry-run, permission scoping
• skills/respira-mcp/references/common-workflows.md — extract → modify → inject recipes, batch updates, HTML-to-builder, audit-then-fix
• eval/scenarios/respira-mcp-targeted-edit.json — single-element edit scenario
• eval/scenarios/respira-mcp-builder-detection.json — detect-then-edit scenario for bulk builder-aware changes

Compatibility

compatibility: frontmatter targets WordPress 6.9+ / PHP 7.4+ to match the repo policy, and lists the builders Respira supports today as the practical compatibility surface.

Maintenance

The skill is maintained alongside the broader Respira skill set at https://github.com/respira-press/claude-skills-wordpress (migration skills, audit skills, etc.). The live tool catalog and version compatibility matrix are kept in sync at https://www.respira.press/dashboard/skills. Happy to keep this synced from upstream — let me know the cadence you'd prefer.

Test plan

• node eval/harness/run.mjs runs the new scenarios (added scenarios match the existing JSON shape and reference both wordpress-router and respira-mcp to verify the routing flow)
• Manual smoke: with Respira MCP connected, a "shorten the H1 on the homepage" prompt should produce the steps listed in respira-mcp-targeted-edit.json's expected_behavior

Disclosure

Respira for WordPress is a paid commercial product. The MCP server itself is closed-source. The skill bundle, the Lite plugin (about to be submitted to the WordPress.org plugin directory), and the CLI are open-source under https://github.com/respira-press. The skill in this PR is permissively documented and works against the Respira MCP server. Happy to adjust framing if a more neutral tone is preferred.

Reviewed by Mihai.

🤖 Generated with Claude Code

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: webmyc <urbankidro@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[webmyc]

any tips to move this?

[webmyc]

Quick status update from the Respira side, in case it helps move this along:

Over the last week I went through wp-rest-api, wp-plugin-development, and wp-plugin-directory-guidelines and aligned the Respira for WordPress plugin to the patterns those three skills prescribe. The relevant changes:

• WP_REST_Server::READABLE/CREATABLE/EDITABLE/DELETABLE constants instead of 'methods' => 'GET' string literals (219 sites, 10 files).
• validate_callback => rest_validate_request_arg on every typed args entry so the schema's 'type' is actually enforced — sanitize was overriding it before (67 sites).
• sanitize_callback on every 'required' => true arg, type-aware: sanitize_text_field / esc_url_raw / wp_kses_post for strings, absint for integers, rest_sanitize_request_arg for arrays/objects (21 sites).
• Public-route hardening: /auth/validate-key gained an args schema; webmcp/v1/nonce flipped from __return_true to is_user_logged_in().
• wp-plugin-directory-guidelines: License: GPLv2 or later header normalised, added .distignore, removed local probe files from the plugin slug dir.

The next plugin release will roll the alignment up; the Lite-plugin wp.org submission goes through wp-plugin-directory-guidelines first.

Also renamed the public skill catalog from respira-press/claude-skills-wordpress to respira-press/agent-skills-wordpress to reflect that these skills target Claude Code, Codex, Antigravity, Cursor — not just Claude. The respira-mcp skill in this PR has the right framing for that already.

Anything else I can adjust on the PR to make it easier to land? Happy to split it, trim the references/, or rework framing if a piece feels off.

[webmyc]

Quick ping with two ecosystem signals that may help frame this PR for review:

• A companion open-source WordPress plugin from Respira, Inhale: MCP Abilities, is now live on the WordPress.org Plugin Directory at https://wordpress.org/plugins/inhale-mcp-abilities/. It exposes registered abilities to the default MCP server through an admin UI, which is the exact surface this skill teaches agents to assume exists.
• I have a parallel upstream PR at feat(admin): add Settings > MCP Adapter page to opt registered abilities into the default server (fixes #183) mcp-adapter#184 that adds the same admin pattern to the canonical adapter (Settings → MCP Adapter). It's CI-green now and uses the same option key, so Respira / Inhale / mcp-adapter all interoperate.

The skill in this PR is unchanged from the last revision; happy to trim references/, rework framing, or split it if anything still feels off. No rush.