@respira/wordpress-mcp-server 7.3.0 → 7.4.1

package/skills/conversion-audit/README.md

@@ -0,0 +1,37 @@
+# Conversion Audit
+
+> A CRO check, not a redesign. Get a prioritized list of fixes — each with what to change, why, and expected impact.
+
+Audits your homepage, pricing page, contact page, and any landing pages across six dimensions known to drive conversion. Outputs a prioritized list of fixes you can apply (or have the agent apply via SafeEdit).
+
+## The six dimensions
+
+1. **Above-the-fold clarity** — does the hero answer "what is this and why does it matter to me" in 5 seconds?
+2. **CTA hierarchy** — one primary CTA per screen, or are 4 buttons competing?
+3. **Form length** — every required field beyond 3 drops completion ~7%
+4. **Social proof placement** — testimonial above the fold beats one in the footer
+5. **Page speed** — pulls from SpeedScan; slow pages don't convert
+6. **Trust signals** — named company, contact info, privacy link, real photos, named team
+
+Each page gets a 0–18 score per dimension. The output prioritizes fixes by expected impact, not by score.
+
+## What you get back
+
+- A summary table — page-by-page score
+- A prioritized fixes list (top 5–8) — current state, suggested change, why
+- A "what's working" section so you know what NOT to change
+- Speed signals from SpeedScan
+- An offer to apply one of the fixes via SafeEdit (duplicate-before-edit)
+
+## Triggers
+
+- *"audit my conversion rate"*
+- *"cro check"*
+- *"find conversion leaks"*
+- *"review my landing pages"*
+
+## Requires
+
+- Respira for WordPress plugin
+- MCP server connected
+- Recommended: a recent SpeedScan run so speed signals are current

package/skills/conversion-audit/SKILL.md

@@ -0,0 +1,185 @@
+# Conversion Audit
+
+**Version:** 1.0.0
+**Updated:** 2026-05-24
+**Category:** audit
+**Status:** stable
+**Requires:** Respira for WordPress plugin 7.1+ + MCP server
+
+---
+
+## Description
+
+Audit a WordPress site for conversion-rate friction. Reads the landing pages, the homepage, the pricing page (if any), the contact page, and any pages that are linked from the main navigation. Identifies friction points across six dimensions: above-the-fold clarity, CTA hierarchy, form length, social proof placement, page speed (using existing Respira SpeedScan), and trust signals.
+
+This is a CRO check, not a redesign. The output is a prioritized list of fixes the user can apply — each with a one-line "what to change" + "why" + "expected impact." No rewriting; recommendations only.
+
+---
+
+## What it audits (the six dimensions)
+
+1. **Above-the-fold clarity.** Does the hero answer "what is this and why does it matter to me"? Within ~5 seconds, can a first-time visitor articulate the offer back? Common failures: jargon-heavy headline, image-first instead of message-first, no concrete value proposition.
+
+2. **CTA hierarchy.** Is there one primary CTA per screen, or are there 4 competing buttons? Are CTAs visually distinguished from the secondary navigation? Is the CTA action clear ("Get a quote" vs "Submit")?
+
+3. **Form length.** For forms found on the page: how many required fields? Common failures: asking for phone number when email would do, asking for company size for an MVP landing page, address before there's any commitment, 8+ fields when 3 would convert.
+
+4. **Social proof placement.** Where are testimonials / customer logos / case-study links relative to the CTA? Common failure: social proof in the footer where nobody scrolls. Strong pattern: one testimonial above the fold, customer logos below the hero, full case study links by the pricing section.
+
+5. **Page speed.** Pulls existing SpeedScan or runs `respira_analyze_pagespeed` if available. Slow pages don't convert. LCP > 2.5s, CLS > 0.1, FID > 100ms are conversion drags.
+
+6. **Trust signals.** Does the page show: company name / logo, contact information, privacy policy link, secure checkout indicators (if commerce), real photos vs stock, named team / founder (vs faceless)?
+
+---
+
+## When to Use
+
+- Quarterly CRO review
+- Before launching a paid traffic campaign — don't drive paid clicks to a leaky page
+- After a redesign — verify nothing important got dropped
+- When conversion drops without an obvious cause
+- For a new landing page review before publish
+
+---
+
+## Trigger Phrases
+
+- "audit my conversion rate"
+- "cro check"
+- "find conversion leaks"
+- "review my landing pages"
+- "audit for conversion"
+- "what's hurting my conversion"
+- "conversion audit"
+
+---
+
+## Execution Workflow
+
+### Step 1 — Confirm site + scope
+
+Call `respira_get_active_site`. Ask the user: *"Audit a single page, the main flow (home + pricing + contact), or all top-nav pages?"* Default to "the main flow" if unclear.
+
+### Step 2 — Identify pages to audit
+
+- **Single page mode:** the user names the page.
+- **Main flow mode:** homepage, `/pricing/` or `/plans/` if present, `/contact/` or `/get-in-touch/` if present, plus any page marked as a landing page (`page_template == 'landing'`).
+- **Top-nav mode:** call `respira_list_menus` then `respira_list_menu_items` for the primary menu; audit each linked page.
+
+For each page, call `respira_extract_builder_content(page_id)`.
+
+### Step 3 — Run each audit dimension
+
+For each page, walk the builder content and score each dimension. The scoring rubric:
+
+**Above-the-fold clarity (0–3):**
+- 3: clear value prop in headline, supporting sub-headline, primary CTA, visual that supports the message
+- 2: headline + CTA but value prop unclear or visual fights the message
+- 1: jargon-heavy or image-first, no concrete benefit
+- 0: empty hero or missing CTA entirely
+
+**CTA hierarchy (0–3):**
+- 3: one primary CTA, visually distinct, action verb, repeated below the fold
+- 2: primary CTA present but competing with 2+ other equally-prominent buttons
+- 1: 3+ competing CTAs or generic verbs ("Submit", "Click here")
+- 0: no clear CTA
+
+**Form length (0–3, skip if no forms):**
+- 3: 1–3 required fields, no asks beyond the minimum
+- 2: 4–5 required fields with one optional
+- 1: 6+ required fields OR asks for phone before commitment
+- 0: 8+ fields or asks for sensitive data (DOB, SSN, address) without commitment
+
+**Social proof placement (0–3):**
+- 3: one testimonial / logo bar above the fold, more below the hero, named with photo + company
+- 2: testimonials present but only below the fold or unnamed
+- 1: footer-only social proof
+- 0: none visible
+
+**Page speed (0–3, from SpeedScan):**
+- 3: LCP < 2.5s, CLS < 0.1, page weight < 2MB
+- 2: one metric mildly off
+- 1: two metrics off
+- 0: LCP > 4s or CLS > 0.25 (conversion killer)
+
+**Trust signals (0–3):**
+- 3: named company, contact info visible, privacy link, real photos, named team
+- 2: most present, one or two missing
+- 1: faceless brand, stock photos, only generic contact
+- 0: anonymous, no company info, no contact, no privacy
+
+Page total: 0–18.
+
+### Step 4 — Output the report
+
+```markdown
+## Conversion audit for {site_url}
+
+Pages audited: {n_pages}
+
+### Summary
+
+| Page | Score | Top issue |
+|---|---|---|
+| / | 14 / 18 | CTA hierarchy: 3 competing primary CTAs in hero |
+| /pricing/ | 11 / 18 | Form length: pricing form asks for 7 fields |
+| /contact/ | 10 / 18 | Above-the-fold: no value prop, only "Get in touch" |
+| ... | | |
+
+### Prioritized fixes (highest impact first)
+
+**1. {page_url} · CTA hierarchy**
+- Current: 3 competing primary buttons in hero ("Get started", "See pricing", "Book a demo")
+- Change to: one primary ("Get started"), demote others to secondary text links
+- Why: competing CTAs split attention and drop CTR by ~30% in typical landing page tests
+
+**2. {page_url} · Form length**
+- Current: 7 required fields including phone + company size
+- Change to: 3 required (name, email, what brings you here) + optional phone
+- Why: every required field beyond 3 drops form completion by ~7%
+
+**3. {page_url} · Above-the-fold clarity**
+- Current: headline "Solutions for modern teams" — generic, no concrete offer
+- Change to: headline that names what the user gets ("X for Y, in Z minutes" pattern)
+- Why: visitors decide within ~5 seconds whether the page is for them; vague heroes lose them
+
+(... continue for top 5–8 fixes ...)
+
+### What's working
+
+(Quick callouts of strong patterns the audit found, so the user knows what NOT to change.)
+
+- {page}: above-the-fold clarity is strong — headline + sub + supporting visual all reinforce the offer.
+- {page}: social proof placement is exemplary — named testimonial above the fold with photo and company.
+
+### Speed signals (from SpeedScan)
+
+| Page | LCP | CLS | Total weight |
+|---|---|---|---|
+| / | 2.1s ✓ | 0.08 ✓ | 1.8MB ✓ |
+| /pricing/ | 3.4s ✗ | 0.15 ✗ | 3.2MB ✗ |
+```
+
+### Step 5 — Offer to act on a chosen fix
+
+Ask: *"Want me to apply one of these now? I can duplicate the page (SafeEdit) and make the change for review."*
+
+If yes, route to the appropriate edit flow (usually `respira_create_page_duplicate` + targeted `respira_update_element`).
+
+---
+
+## Hard rules
+
+- **Recommendations, not redesigns.** This skill suggests changes; it does not apply them autonomously. Every applied change is a SafeEdit-protected duplicate, reviewed before promotion.
+- **Score is directional, not gospel.** Use the score to prioritize, not as a verdict. A 14/18 page with a critical CTA bug is more urgent than a 10/18 page with diffuse issues.
+- **Form audits use builder-native parsing.** If the form is a Gravity Forms shortcode, parse the GF form definition (not the rendered HTML). If WPForms, ditto. If Contact Form 7, ditto. Raw HTML parsing of form fields produces wrong field counts.
+- **Speed signals come from SpeedScan if present, not from re-running a fresh audit.** Re-running is slow and costly. If the SpeedScan is more than 30 days old, note that and offer to refresh.
+- **Trust signal checks include checking for the privacy / terms / contact pages existing.** Use `respira_list_pages` to verify, not just visually scan the page.
+
+---
+
+## Telemetry
+
+Records: site URL hash, n_pages audited, score distribution, top issue categories detected, success/failure, total duration. No page content, no recommendations, no scores per page sent.
+
+Endpoint: `POST https://www.respira.press/api/skills/track-usage`

package/skills/conversion-audit/metadata.json

@@ -0,0 +1,46 @@
+{
+  "name": "Conversion Audit",
+  "slug": "conversion-audit",
+  "icon": "📈",
+  "category": "audit",
+  "description": "Audit a WordPress site for conversion-rate friction across six dimensions: above-the-fold clarity, CTA hierarchy, form length, social proof placement, page speed, and trust signals. Prioritized fixes with expected impact — recommendations, not redesigns.",
+  "author": "Respira Team",
+  "author_url": "https://respira.press",
+  "trigger": "audit my conversion rate",
+  "requires_respira": true,
+  "requires_woocommerce_addon": false,
+  "requires_accessibility_addon": false,
+  "is_read_only": true,
+  "is_duplicate_first": false,
+  "version": "1.0.0",
+  "last_updated": "2026-05-24",
+  "tools_used": [
+    "respira_get_active_site",
+    "respira_list_pages",
+    "respira_list_menus",
+    "respira_list_menu_items",
+    "respira_extract_builder_content",
+    "respira_get_core_web_vitals",
+    "respira_analyze_pagespeed",
+    "respira_find_element"
+  ],
+  "detects": [
+    "above_fold_clarity_score",
+    "cta_hierarchy_score",
+    "form_length_score",
+    "social_proof_placement_score",
+    "page_speed_score",
+    "trust_signals_score",
+    "competing_ctas",
+    "form_field_count",
+    "missing_value_prop",
+    "absent_trust_signals"
+  ],
+  "generates": [
+    "conversion_audit_report",
+    "prioritized_fixes_list",
+    "per_page_scoring_table",
+    "speed_signals_table",
+    "what_is_working_callouts"
+  ]
+}

package/skills/custom-post-type-architect/README.md

@@ -0,0 +1,34 @@
+# Custom Post Type Architect
+
+> Design and create WordPress custom post types end to end — from brief to working CPT in one conversation.
+
+Give the agent a brief — "I need a portfolio with case studies" — and it designs the post type, picks the right taxonomies, defines the ACF field group, creates two sample entries, and suggests a single template for your active page builder.
+
+## What it does
+
+1. Designs the CPT shape (labels, supports, public/private, has_archive, REST exposure)
+2. Designs supporting taxonomies (e.g. industries + service-types for case studies)
+3. Designs the ACF field group with the right fields for your content type
+4. Reviews the shape with you before creating anything
+5. Creates the CPT + taxonomies + ACF group via the new v7.1 MCP tools
+6. Generates 1–2 sample entries so you can verify the rendering
+7. Suggests a single template for your active builder (Bricks / Elementor / Divi / Gutenberg / Oxygen / Breakdance)
+
+## Default templates by content type
+
+The skill knows sensible defaults for: case studies, team members, events, podcast episodes, properties (real estate), recipes, FAQs, testimonials, courses, lessons.
+
+You can override every field at the review step.
+
+## Triggers
+
+- *"create a custom post type"*
+- *"build a portfolio"*
+- *"set up a case study type"*
+- *"add a team members section"*
+- *"scaffold a CPT"*
+
+## Requires
+
+- Respira for WordPress plugin **7.1+** (the underlying MCP tools are new in 7.1)
+- ACF Pro installed for the field group creation (the skill checks and warns if not)

package/skills/custom-post-type-architect/SKILL.md

@@ -0,0 +1,158 @@
+# Custom Post Type Architect
+
+**Version:** 1.0.0
+**Updated:** 2026-05-24
+**Category:** content-creation
+**Status:** stable
+**Requires:** Respira for WordPress plugin 7.1+ + MCP server
+
+---
+
+## Description
+
+Given a brief — "I need a portfolio with case studies" or "we run a podcast and want each episode to be its own page" — design and create the WordPress custom post type, supporting taxonomies, and ACF field group end to end. Uses the new v7.1 MCP tools: `respira_create_post_type`, `respira_create_taxonomy`, `respira_create_acf_field_group`.
+
+The output is a fully wired content architecture, ready to use:
+
+1. The CPT itself (labels, supports, public-vs-private, has_archive, REST exposure)
+2. Supporting taxonomies (e.g. industries for case studies, seasons for podcast episodes)
+3. ACF field group bound to the CPT (custom fields the editor sees)
+4. 1–2 sample entries so the agent can verify the rendering
+5. Builder-aware single-template suggestion for the active builder
+
+---
+
+## When to Use
+
+- Setting up a portfolio, case studies, team members, events, podcast episodes, recipes, properties, locations, products-but-not-WooCommerce, FAQs, testimonials, courses, lessons, or any structured content type
+- Migrating away from custom-fields-in-posts to a proper content type
+- Auditing an existing site that's overloaded the default "post" type with non-blog content
+
+---
+
+## Trigger Phrases
+
+- "create a custom post type"
+- "build a portfolio"
+- "set up a case study type"
+- "add a team members section"
+- "scaffold a CPT"
+- "create a podcast post type"
+- "build an events section"
+- "we need a new content type"
+
+---
+
+## Execution Workflow
+
+### Step 1 — Confirm site + builder
+
+Call `respira_get_active_site` and `respira_get_builder_info`. The builder choice affects Step 6 (template suggestion).
+
+### Step 2 — Understand the brief
+
+Ask the user three short questions if not already clear from their request:
+
+1. **What is the content?** (case studies, podcast episodes, team, events, ...)
+2. **How is it organized?** (categories, tags, custom taxonomies — e.g. case studies organized by industry + service-type)
+3. **What fields does each entry need?** (e.g. case study: client name, hero image, deliverables, outcomes, before/after metrics, related case studies)
+
+If the user can't articulate the fields, propose a default set based on the content type. Default sets:
+
+- **Case studies:** client name, industry (taxonomy), service-type (taxonomy), hero image, brief, deliverables, outcomes, key metrics (3-5), client logo, related case studies (relationship)
+- **Team members:** name, role, bio, headshot, social links (LinkedIn / X / personal site), department (taxonomy)
+- **Events:** title, date/time, location, address, virtual/in-person, registration URL, capacity, hero image
+- **Podcast episodes:** title, episode number, season (taxonomy), audio file URL, duration, show notes, guest name, guest links
+- **Properties (real estate):** address, price, bedrooms, bathrooms, sqm, status (taxonomy: for-sale / sold / under-offer), gallery, neighborhood (taxonomy)
+- **Recipes:** title, prep time, cook time, servings, ingredients (repeater), steps (repeater), category (taxonomy), cuisine (taxonomy), difficulty, dietary tags
+
+### Step 3 — Design the CPT shape
+
+Output the proposed shape for user review:
+
+```markdown
+## Proposed CPT: `case_study`
+
+- **Singular label:** Case Study
+- **Plural label:** Case Studies
+- **Menu icon:** dashicons-portfolio
+- **Public:** yes
+- **Has archive:** yes (URL: /case-studies/)
+- **Supports:** title, editor, thumbnail, excerpt, revisions
+- **REST API:** exposed (so the builder + Respira can read/write)
+- **Hierarchical:** no
+- **Show in admin menu:** yes, position 25 (under Pages)
+
+## Supporting taxonomies
+
+1. `case_study_industry` — Industries (e.g. SaaS, e-commerce, healthcare)
+2. `case_study_service` — Service types (e.g. branding, website, copywriting)
+
+## ACF field group: `Case Study Fields`
+
+- Hero image (image, required)
+- Client name (text, required)
+- Brief (textarea)
+- Deliverables (repeater — title + description)
+- Outcomes (repeater — metric name + before + after)
+- Client logo (image)
+- Related case studies (relationship → case_study)
+```
+
+Wait for confirmation. The user might want to add or remove fields.
+
+### Step 4 — Create the CPT + taxonomies
+
+After confirmation, run the create calls:
+
+1. `respira_create_post_type` — creates the CPT with the proposed shape
+2. `respira_create_taxonomy` — once per supporting taxonomy, bound to the CPT
+3. `respira_create_acf_field_group` — the ACF field group, bound to the CPT via location rules
+
+Each call should report back: "✓ Created CPT `case_study`" / "✓ Created taxonomy `case_study_industry`" / "✓ Created ACF field group with 8 fields bound to `case_study`."
+
+### Step 5 — Generate sample entries
+
+Create 1–2 sample entries so the user can immediately see the CPT working in the admin and the editor renders correctly. Use `respira_create_custom_post` with realistic but generic content (no real customer names — generic personas like "BrandQ" or "agency-A").
+
+The sample entries should populate every ACF field so the user can see the full shape.
+
+### Step 6 — Suggest a builder-specific single template
+
+Based on the active builder, suggest where to create the single template:
+
+- **Bricks:** "Create a single template at Templates → Add New → Type: Single → Conditions: Post Type = case_study. Suggested elements: ..."
+- **Elementor:** "Create a single template at Templates → Theme Builder → Single → Add Conditions → Posts: case_study. Suggested widgets: ..."
+- **Divi:** "Create a Theme Builder template at Divi → Theme Builder → Add Template → Posts: case_study. Suggested modules: ..."
+- **Gutenberg / FSE theme:** "Create a single-case_study.html template in the theme or via Appearance → Editor → Templates → Add → Single Item: Case Study."
+- **Oxygen / Breakdance:** "Create a Single template targeting case_study."
+
+If the user wants to scaffold the template now, offer to build it: that's a separate skill flow (use `respira_build_page` against the single template surface for the chosen builder).
+
+### Step 7 — Verify
+
+Output a summary with:
+
+- The CPT slug + admin URL (`/wp-admin/edit.php?post_type=case_study`)
+- The archive URL on the front-end (`/case-studies/`)
+- The 2 sample entry URLs
+- A note about whether the single template was scaffolded or left for the user
+
+---
+
+## Hard rules
+
+- Always ask before creating. The CPT shape preview in Step 3 is mandatory. Customers will be writing into this CPT for years — get it right the first time.
+- Use snake_case slugs (`case_study`, `case_study_industry`) — never spaces or hyphens. WordPress CPT slugs have a 20-character hard limit.
+- Always expose `show_in_rest` so the builder + Respira can read/write the CPT. If `show_in_rest` is false, the post type is invisible to the REST API and most modern builders break on it.
+- Never name a CPT `post`, `page`, `attachment`, `revision`, `nav_menu_item`, `custom_css`, `customize_changeset`, `oembed_cache`, `user_request`, `wp_block`, `wp_template`, `wp_template_part`, `wp_global_styles`, `wp_navigation` — these are reserved.
+- ACF field group location rules must bind to the CPT (`post_type == case_study`), not to a category or template. Wrong location rule = fields invisible in the admin.
+- Sample entries use generic personas. Never use real customer names from memory or any other source.
+
+---
+
+## Telemetry
+
+Records: site URL hash, CPT slug created, taxonomy count, ACF field count, builder active, sample entries created, success/failure. No CPT names, no field values, no content sent.
+
+Endpoint: `POST https://www.respira.press/api/skills/track-usage`

package/skills/custom-post-type-architect/metadata.json

@@ -0,0 +1,39 @@
+{
+  "name": "Custom Post Type Architect",
+  "slug": "custom-post-type-architect",
+  "icon": "🏗️",
+  "category": "content-creation",
+  "description": "Design and create WordPress custom post types end to end — CPT + supporting taxonomies + ACF field group + sample entries + builder-specific single template suggestion. Uses the new v7.1 MCP tools: respira_create_post_type, respira_create_taxonomy, respira_create_acf_field_group.",
+  "author": "Respira Team",
+  "author_url": "https://respira.press",
+  "trigger": "create a custom post type",
+  "requires_respira": true,
+  "requires_woocommerce_addon": false,
+  "requires_accessibility_addon": false,
+  "is_read_only": false,
+  "is_duplicate_first": false,
+  "version": "1.0.0",
+  "last_updated": "2026-05-24",
+  "tools_used": [
+    "respira_get_active_site",
+    "respira_get_builder_info",
+    "respira_create_post_type",
+    "respira_create_taxonomy",
+    "respira_create_acf_field_group",
+    "respira_create_custom_post",
+    "respira_list_custom_posts"
+  ],
+  "detects": [
+    "active_builder",
+    "content_type_intent",
+    "field_requirements",
+    "taxonomy_requirements"
+  ],
+  "generates": [
+    "cpt_shape_proposal",
+    "supporting_taxonomies",
+    "acf_field_group",
+    "sample_entries",
+    "single_template_recommendation"
+  ]
+}

package/skills/design-system-synthesizer/README.md

@@ -0,0 +1,46 @@
+# Design System Synthesizer
+
+> Every page you build, automatically on brand.
+
+Tell Respira your site's design system, and every new page Claude generates matches your logo, colors, fonts, and component patterns.
+
+## What it does
+
+Reads 5–10 representative pages of your site (homepage, about, a service page, a typical blog post, contact), inspects your theme stylesheet, scans your media library for the logo and brand imagery, then synthesizes a complete design system: brand identity, color palette, typography scale, spacing scale, component patterns.
+
+The system is persisted to your site as machine data AND as a visible style-guide page you can open in your browser.
+
+## Two outputs, one workflow
+
+1. **Machine source of truth** — saved in `wp_options.respira_design_system`. Every Respira content-creation skill reads this at the top of its workflow so new pages snap to your brand.
+2. **Human-visible style-guide page** — a private (admin-only) page at `/design-system/` on your site that renders the synthesized tokens visually: color swatches with hex codes, typography samples in actual styles, spacing scale blocks, component previews, voice notes. Built with your active page builder so you can edit it like any other page.
+
+You can promote the page to public any time if you want a /design-system/ landing on your live site.
+
+## What's in the system
+
+- **Brand:** logo URL, favicon, social card, wordmark
+- **Colors:** primary, secondary, accent, neutrals (9-step scale), semantic (link / success / warning / error)
+- **Typography:** heading family + weights + sizes (H1–H6), body family + weight + line-height, mono family
+- **Spacing:** base unit, scale steps, section padding, container max width
+- **Components:** button styles, card styles, hero patterns, section patterns
+- **Voice hints:** person used (we / I / you), formality, average sentence length
+
+## Triggers
+
+- *"build a design system for my site"*
+- *"extract my brand"*
+- *"synthesize a design system"*
+- *"create my design tokens"*
+- *"what does my site look like"*
+
+## How other skills use it
+
+Future content skills (page generators, section builders, blog post writers) call `respira_get_option('respira_design_system')` at the top of their workflow. The tokens give the agent explicit values for colors, fonts, spacing, and patterns — no more invented hex codes, no more random font sizes.
+
+Pair with the **Brand Voice Synthesizer** for the full brand foundation (visual + verbal).
+
+## Requires
+
+- Respira for WordPress plugin **7.1+**
+- MCP server connected