@respira/wordpress-mcp-server 7.3.0 → 7.4.0

package/skills/migrate-wpbakery-to-bricks/SKILL.md

@@ -0,0 +1,336 @@
+# Migrate WPBakery to Bricks
+
+**Version:** 2.0.0
+**Updated:** 2026-06-30
+**Freshly updated:** v2.0.0 wires in current Respira safety and precision. Pre-migration now inventories source pages with `respira_find_builder_targets`. Every write is preceded by a `respira_get_snapshot`, and the existing draft-duplicate path is kept. After the first `respira_inject_builder_content`, validation issues (collapsed column widths from fraction conversion, broken parent refs, misdecoded Design Options) are corrected surgically with `respira_find_element` + `respira_update_element` (and `respira_batch_update` for multi-element or multi-page fixes) instead of re-injecting whole pages. Snapshot restore and draft deletion are now explicit rollback paths. Reflects the current 16 supported builders.
+
+Converts WPBakery Page Builder pages to Bricks Builder. Parses WPBakery's shortcode-based content from post_content, maps each element to its Bricks equivalent, generates a migration plan for approval, and writes clean Bricks JSON to the target pages. Use this skill whenever someone wants to move from WPBakery to Bricks, modernize an older WPBakery site with Bricks, or switch page builders from WPBakery/Visual Composer to Bricks.
+
+## What This Skill Does
+
+WPBakery is one of the most common legacy page builders — it comes bundled with thousands of ThemeForest themes and millions of sites still use it. Moving to Bricks is a significant modernization: from shortcode-based content in `post_content` to clean JSON in `_bricks_page_content_2`, from heavy frontend CSS/JS to Bricks' lightweight rendering, and from an aging interface to a modern visual editor.
+
+This skill handles the format translation — parsing WPBakery's `[vc_*]` shortcodes, decoding its URL encoding and Design Options CSS, and generating proper Bricks JSON with correct element hierarchies and settings.
+
+**Handles:**
+- vc_row/vc_column → Bricks Section/Container elements
+- vc_column_text → Bricks Text Basic element (parsed for headings, paragraphs)
+- vc_single_image → Bricks Image element
+- vc_btn/vc_button → Bricks Button element
+- vc_video → Bricks Video element
+- vc_separator → Bricks Divider element
+- vc_empty_space → Bricks spacing (via container padding or dedicated spacer)
+- vc_custom_heading → Bricks Heading element
+- vc_gallery/vc_images_carousel → Bricks Gallery/Carousel element
+- vc_toggle → Bricks Accordion item
+- vc_accordion → Bricks Accordion element
+- vc_tabs → Bricks Tabs element
+- vc_raw_html/vc_raw_js → Bricks Code element
+- vc_icon → Bricks Icon element
+- vc_gmaps → Bricks Map element
+- vc_progress_bar → Bricks Progress Bar element
+- vc_row_inner/vc_column_inner → nested Bricks containers
+- Design Options CSS → Bricks settings (background, padding, border)
+- el_class/el_id → Bricks custom CSS classes and attributes
+
+**Preserves:**
+- All text content and HTML formatting
+- Image URLs, alt text, captions
+- Typography where explicitly set
+- Color values from Design Options
+- Spacing from Design Options
+- Background colors and images
+- Button labels, URLs, targets
+- Video embed URLs
+- Gallery image sets
+- CSS classes (el_class) and IDs (el_id)
+
+## What This Skill Does NOT Do
+
+- **Theme-bundled custom elements** — Many ThemeForest themes add custom WPBakery elements (team member, portfolio, testimonial, pricing, etc.). These are theme-specific shortcodes with no Bricks equivalent. They are flagged for manual recreation.
+- **WPBakery addons** — Ultimate Addons for WPBakery, Starter Templates, Starter Sites, and other addon plugins add proprietary elements that cannot be auto-mapped.
+- **vc_grid/vc_masonry_grid** — Post grid elements with complex queries. These need Bricks' Query Loop or posts element configured manually.
+- **Revolution Slider / Layer Slider** — Often bundled with WPBakery themes but are separate plugins outside migration scope.
+- **Complex Design Options** — WPBakery encodes CSS in a single attribute string. Background gradients, complex border configurations, and CSS filters may be partially extracted.
+- **Frontend editor positioning** — Pixel-precise layouts from WPBakery's frontend editor may need spacing adjustment.
+- **Templates** — WPBakery saved templates are not auto-converted to Bricks templates.
+
+## Requirements
+
+- Respira for WordPress plugin installed and connected
+- MCP connection active (desktop or WebMCP)
+- WPBakery Page Builder plugin active (to ensure shortcodes are parseable)
+- Bricks theme installed and active (to write target content)
+- Read access to scan WPBakery content
+- Write access to create duplicates with Bricks content
+
+## Trigger Phrase
+
+- "migrate wpbakery to bricks"
+
+## Alternative Triggers
+
+- "convert wpbakery to bricks"
+- "switch from wpbakery to bricks"
+- "migrate visual composer to bricks"
+- "rebuild wpbakery pages in bricks"
+- "move from wpbakery to bricks"
+- "replace wpbakery with bricks"
+- "modernize visual composer site"
+
+## Source Builder: WPBakery
+
+WPBakery stores content as shortcodes in `post_content`:
+
+```
+[vc_row full_width="stretch_row" css=".vc_custom_123{padding:40px;background:#f5f5f5}"]
+  [vc_column width="1/2" el_class="custom-class"]
+    [vc_column_text]
+      <h2>Heading</h2>
+      <p>Paragraph content.</p>
+    [/vc_column_text]
+    [vc_single_image image="456" img_size="large"]
+  [/vc_column]
+  [vc_column width="1/2"]
+    [vc_btn title="Click" style="flat" link="url:https%3A%2F%2Fexample.com||target:_blank"]
+  [/vc_column]
+[/vc_row]
+```
+
+Key WPBakery specifics:
+- **Column widths as fractions**: `1/1`, `1/2`, `1/3`, `2/3`, `1/4`, `3/4`, `1/6`, `5/6`
+- **Inner rows**: `[vc_row_inner][vc_column_inner]` for nesting
+- **CSS attribute**: Encoded Design Options — `.vc_custom_XXXXX{property:value;...}`
+- **Link encoding**: `url:https%3A%2F%2F...|title:...|target:_blank|rel:nofollow`
+- **Full-width**: `full_width` attribute controls row stretching
+- **el_class / el_id**: Custom CSS class and ID attributes
+- **Image references**: By attachment ID (not URL)
+
+Read WPBakery content via `respira_extract_builder_content` with `builder=wpbakery`.
+
+## Target Builder: Bricks
+
+Bricks stores content in `_bricks_page_content_2` as a JSON array:
+
+```json
+[
+  { "id": "abc123", "name": "section", "parent": 0, "settings": {...} },
+  { "id": "def456", "name": "container", "parent": "abc123", "settings": {...} },
+  { "id": "ghi789", "name": "text-basic", "parent": "def456", "settings": { "text": "<p>...</p>" } }
+]
+```
+
+Key Bricks specifics:
+- Elements: `section`, `container`, `heading`, `text-basic`, `image`, `button`, `video`, `icon`
+- Parent-child via `parent` field
+- IDs are short alphanumeric strings
+- Responsive via `_breakpoints`
+
+Write Bricks content via `respira_inject_builder_content` with `builder=bricks`.
+
+## Execution Workflow
+
+### Phase 1: Pre-Migration Audit
+
+1. Verify Respira + MCP connection via `respira_get_site_context`. If unavailable, stop and show setup guidance.
+2. Confirm WPBakery is active via `respira_list_plugins`.
+3. Confirm Bricks theme is installed via `respira_get_site_context`.
+4. Identify active theme — note if it bundles WPBakery and adds custom elements.
+5. Inventory and scope the source pages with `respira_find_builder_targets` (builder=wpbakery) — this gives a fast, ranked list of every WPBakery-built page/post before you touch anything. Fall back to `respira_list_pages` / `respira_list_posts` + `respira_get_builder_info` to confirm builder per item where needed.
+6. Extract content via `respira_extract_builder_content` with `builder=wpbakery`
+7. Build inventory:
+   - Total WPBakery pages/posts
+   - Element types (frequency count)
+   - Theme-bundled custom elements (flagged)
+   - Addon elements (flagged)
+   - Grid/masonry elements (flagged)
+   - Design Options complexity
+   - Inner row nesting depth
+   - Complexity per page
+
+### Phase 2: Migration Plan
+
+```
+## WPBakery → Bricks Migration Plan
+
+### Modernization Context
+This migration moves your site from legacy shortcode-based content to Bricks'
+modern JSON format. Expect significantly faster page loads and a much better
+editing experience. Bricks also means switching your theme — plan for header,
+footer, and template setup.
+
+### Theme-Bundled Elements
+[If applicable]: Your theme ([name]) bundles WPBakery and adds X custom
+elements. These cannot be auto-migrated and are flagged below.
+
+### Site Inventory
+- Total WPBakery pages: X
+- Total elements to convert: X
+- Auto-convertible: X (Y%)
+- Manual attention: X (Y%)
+
+### Element → Bricks Mapping
+| WPBakery Element    | Bricks Element | Status |
+|--------------------|---------------|--------|
+| vc_column_text     | text-basic    | Auto   |
+| vc_single_image    | image         | Auto   |
+| vc_custom_heading  | heading       | Auto   |
+| vc_btn             | button        | Auto   |
+| vc_gallery         | gallery       | Auto   |
+| vc_accordion       | accordion     | Auto   |
+| vc_tabs            | tabs          | Auto   |
+| vc_toggle          | accordion     | Auto   |
+| vc_grid            | —             | Manual |
+| [theme element]    | —             | Manual |
+
+### Design Options Extraction
+- Simple Design Options (color + padding): X pages — fully extracted
+- Complex Design Options (gradients, borders): X pages — partially extracted
+
+### Page-by-Page Plan
+1. **[Page Title]** — X elements, [complexity]
+2. ...
+```
+
+Ask for confirmation:
+> Ready to modernize? Your WPBakery pages stay untouched — I'll create Bricks duplicates.
+> 1. Migrate all pages
+> 2. Migrate specific pages
+> 3. Start with a test page (recommended for theme-bundled WPBakery sites)
+> 4. Just keep this plan
+
+### Phase 3: Page-by-Page Migration
+
+For each approved page:
+
+1. Read WPBakery content via `respira_extract_builder_content` with `builder=wpbakery`
+2. Parse the shortcode tree:
+   - Build vc_row → vc_column → element hierarchy
+   - Handle vc_row_inner/vc_column_inner nesting
+   - Decode Design Options CSS from `css` attribute
+   - Decode link URLs from WPBakery's encoding format
+   - Resolve image attachment IDs
+3. Generate Bricks JSON array:
+   - `vc_row` → `section` element (check `full_width` for layout mode)
+   - `vc_column` → `container` element with flex width
+     - Convert fractions: `1/2`→50%, `1/3`→33.33%, `2/3`→66.66%, `1/4`→25%, etc.
+   - Map each element:
+     - `vc_column_text` → `text-basic` (preserve HTML, or split into heading + text-basic)
+     - `vc_single_image` → `image` (resolve attachment ID to URL, map alt, size)
+     - `vc_btn` → `button` (decode URL, map label, style, color)
+     - `vc_custom_heading` → `heading` (map text, tag, alignment)
+     - `vc_gallery` → `gallery` (resolve image IDs)
+     - `vc_accordion` → `accordion` (map items with titles and content)
+     - `vc_tabs` → `tabs` (map tab titles and content)
+   - Apply Design Options: background → settings background, padding → settings padding
+   - Apply el_class → Bricks CSS classes setting
+   - Generate unique IDs and proper parent references
+   - Flag unmappable elements
+4. Create duplicate via `respira_create_page_duplicate` or `respira_create_post_duplicate`
+5. Before writing, take a snapshot with `respira_get_snapshot` so the duplicate's pre-write state can be restored if anything goes wrong
+6. Write Bricks JSON via `respira_inject_builder_content` with `builder=bricks`
+7. Surgical fix pass — if the injected page has validation issues (column widths that collapsed during fraction conversion, broken parent refs, an element whose Design Options decoded wrong), do not re-inject the whole page. Locate the specific element with `respira_find_element` and correct it with `respira_update_element`. For repeated fixes across many elements or several pages, batch them with `respira_batch_update`
+8. Report status
+
+### Phase 4: Post-Migration Verification
+
+1. Summarize migrations:
+   - Pages migrated, elements created, items flagged
+2. For each migrated page:
+   - Link to Bricks editor
+   - Flagged items
+   - Design Options notes (what was extracted vs. simplified)
+3. Post-migration checklist:
+   - [ ] Open each duplicate in Bricks editor
+   - [ ] Verify section/container layout structure
+   - [ ] Check column widths match intended proportions
+   - [ ] Verify images load (attachment ID resolution)
+   - [ ] Test button links (URL decoding)
+   - [ ] Check responsive views
+   - [ ] Recreate theme-bundled custom elements
+   - [ ] Set up Bricks templates for header/footer/archive
+   - [ ] Review gallery and carousel elements
+   - [ ] Compare with WPBakery original
+   - [ ] Celebrate the speed improvement
+
+## Safety Model
+
+- Read-only analysis first — full content scan before any changes
+- Explicit user confirmation required before creating duplicates
+- Original WPBakery pages are never modified or deleted
+- All migrated content goes to draft duplicates only
+- Never auto-publishes migrated pages
+- Snapshot before every write — `respira_get_snapshot` captures the duplicate's pre-write state, and `respira_restore_snapshot` rolls it back if an injection goes wrong
+- Two explicit rollback paths: restore the snapshot to revert a bad write, or delete the draft duplicates entirely to undo the migration
+- Warns about theme-bundled element dependencies
+
+## Honest Disclaimer
+
+This skill converts WPBakery page content to Bricks format and creates draft duplicates for review.
+
+It cannot:
+- Convert theme-bundled custom WPBakery elements
+- Migrate WPBakery addon plugin elements
+- Perfectly extract all Design Options CSS
+- Convert post grids to Bricks Query Loop automatically
+- Handle Revolution Slider or other bundled plugins
+- Replace visual QA and manual review
+
+It can:
+- Convert 75-90% of standard WPBakery elements to Bricks equivalents
+- Parse and decode WPBakery's CSS and URL encoding
+- Handle nested inner row/column structures
+- Resolve image attachment IDs to proper URLs
+- Modernize legacy content to Bricks' clean JSON format
+- Dramatically improve page load performance
+- Keep original pages completely safe
+
+## Tooling
+
+**Core WordPress tools**
+- `respira_get_site_context`
+- `respira_list_plugins`
+- `respira_list_pages`
+- `respira_list_posts`
+- `respira_read_page`
+- `respira_read_post`
+- `respira_get_builder_info`
+- `respira_extract_builder_content`
+- `respira_inject_builder_content`
+- `respira_find_builder_targets`
+- `respira_create_page_duplicate`
+- `respira_create_post_duplicate`
+
+**Safety and surgical-fix tools**
+- `respira_get_snapshot`
+- `respira_restore_snapshot`
+- `respira_find_element`
+- `respira_update_element`
+- `respira_batch_update`
+
+## Telemetry
+
+After run completion, send fire-and-forget usage tracking to:
+
+- `POST https://www.respira.press/api/skills/track-usage`
+
+Include:
+- `skill_slug = migrate-wpbakery-to-bricks`
+- site/version context
+- duration and success
+- pages migrated, elements created, elements flagged counts
+- tools used
+
+Never block user flow on telemetry failure.
+
+## Related Skills
+
+- WordPress Site DNA (audit site structure and theme dependencies before migrating)
+- Internal Link Builder (verify links post-migration)
+- SEO & AEO Amplifier (verify SEO post-migration)
+- Technical Debt Audit (find WPBakery shortcode remnants and legacy theme code)
+
+---
+
+Built by Respira Team
+https://respira.press/skills/migrate-wpbakery-to-bricks

package/skills/migrate-wpbakery-to-gutenberg/SKILL.md

@@ -0,0 +1,345 @@
+# Migrate WPBakery to Gutenberg
+
+**Version:** 2.0.0
+**Updated:** 2026-06-30
+**Freshly updated:** v2.0.0 weaves in the current Respira safety and precision flow — `respira_find_builder_targets` to inventory and scope the WPBakery source pages up front, a `respira_get_snapshot` checkpoint before any write, and surgical fixes via `respira_find_element` + `respira_update_element` (and `respira_batch_update` for multi-block or multi-page corrections) instead of rewriting whole pages. Rollback is now explicit (restore the snapshot, delete the draft duplicates). Reflects the current 16 supported builders.
+
+Converts WPBakery Page Builder (formerly Visual Composer) pages to native Gutenberg blocks. Parses WPBakery's shortcode-based content from post_content, maps each element to its closest core block equivalent, generates a migration plan for approval, and writes clean block markup to the target pages. Use this skill whenever someone wants to move from WPBakery to Gutenberg, eliminate the WPBakery dependency, switch to native blocks, or modernize an older WordPress site still running WPBakery.
+
+## What This Skill Does
+
+WPBakery is one of the oldest and most widely-installed WordPress page builders — millions of sites still run it. It stores content as shortcodes in `post_content` using the `[vc_*]` prefix. The good news: WPBakery's shortcode structure is relatively straightforward compared to Divi's encoding complexities. The challenge: many WPBakery sites are older and may use deprecated elements, custom shortcodes from themes, or VC-specific plugins that add nonstandard elements.
+
+This skill parses the WPBakery shortcode tree, extracts content and settings, and generates equivalent Gutenberg blocks. The result is clean, modern WordPress content free from shortcode dependencies.
+
+**Handles:**
+- vc_row/vc_column → Columns and Column blocks
+- vc_column_text → Paragraph blocks (preserving HTML)
+- vc_single_image → Image block
+- vc_btn/vc_button → Buttons block
+- vc_video → Video or Embed block
+- vc_separator/vc_text_separator → Separator block
+- vc_empty_space → Spacer block
+- vc_row_inner/vc_column_inner → nested Columns blocks
+- vc_custom_heading → Heading block
+- vc_gallery/vc_images_carousel → Gallery block
+- vc_toggle → Details block (WP 6.3+)
+- vc_accordion/vc_accordion_tab → Group with Details blocks
+- vc_tabs/vc_tab → Group blocks with headings
+- vc_raw_html/vc_raw_js → Custom HTML block
+- vc_icon → Paragraph with icon (or HTML block)
+- vc_gmaps → Custom HTML block with embed
+- vc_progress_bar → HTML approximation
+- vc_wp_* widgets → corresponding WordPress widget blocks
+
+**Preserves:**
+- All text content and HTML formatting within vc_column_text
+- Image URLs, alt text, link targets
+- Heading text and hierarchy
+- Button labels, URLs, and basic styles
+- Video embed URLs
+- Gallery image collections
+- Code/HTML block contents
+- CSS classes applied via `el_class` attribute
+- Custom element IDs via `el_id` attribute
+
+## What This Skill Does NOT Do
+
+- **Theme-bundled WPBakery elements** — Many themes add custom WPBakery elements (portfolio grids, team members, testimonial carousels, etc.). These are theme-specific and cannot be auto-mapped. They are flagged for manual recreation.
+- **WPBakery addons** — Ultimate Addons for WPBakery, Starter Templates, etc. add proprietary shortcodes that are flagged, not converted.
+- **vc_grid/vc_masonry_grid** — Post grid elements with complex query settings need manual recreation using Query Loop block or a posts plugin.
+- **Design options** — WPBakery's Design Options panel (accessed via `css` attribute containing encoded CSS) stores background, border, padding as a single encoded string. Basic properties are extracted; complex combinations may be simplified.
+- **Frontend editor layouts** — Some WPBakery designs rely on the frontend editor's pixel-precise positioning which has no block equivalent.
+- **WooCommerce elements** — vc_wp_product, cart, and checkout elements need WooCommerce blocks.
+- **Revolution Slider, Layer Slider** — Often bundled with WPBakery themes but are separate plugins.
+- **Templates** — WPBakery saved templates are not migrated as reusable blocks automatically.
+
+## Requirements
+
+- Respira for WordPress plugin installed and connected
+- MCP connection active (desktop or WebMCP)
+- WPBakery Page Builder plugin active (to ensure shortcodes render/parse)
+- WordPress 6.0+ (6.3+ recommended for Details block)
+- A block-compatible theme (often needed since WPBakery sites tend to run older themes)
+- Read access to scan WPBakery content
+- Write access to create duplicates with Gutenberg content
+
+## Trigger Phrase
+
+- "migrate wpbakery to gutenberg"
+
+## Alternative Triggers
+
+- "convert wpbakery to blocks"
+- "switch from wpbakery to gutenberg"
+- "migrate visual composer to gutenberg"
+- "remove wpbakery"
+- "rebuild wpbakery pages with blocks"
+- "wpbakery to block editor"
+- "decommission wpbakery"
+- "get rid of visual composer"
+
+## Source Builder: WPBakery
+
+WPBakery stores content as shortcodes in `post_content`:
+
+```
+[vc_row full_width="stretch_row" css=".vc_custom_123{padding-top:40px}"]
+  [vc_column width="1/2" el_class="my-class"]
+    [vc_column_text]
+      <h2>Welcome</h2>
+      <p>Content with <strong>formatting</strong>.</p>
+    [/vc_column_text]
+    [vc_single_image image="456" img_size="large" alignment="center"]
+  [/vc_column]
+  [vc_column width="1/2"]
+    [vc_btn title="Learn More" style="flat" color="primary" link="url:https%3A%2F%2Fexample.com"]
+  [/vc_column]
+[/vc_row]
+```
+
+Key WPBakery specifics:
+- **Row/column structure**: `[vc_row]` → `[vc_column width="1/2"]` → elements
+- **Column widths as fractions**: `1/1`, `1/2`, `1/3`, `2/3`, `1/4`, `3/4`, `1/6`, `5/6`
+- **Inner rows**: `[vc_row_inner][vc_column_inner]` for nested layouts
+- **CSS attribute**: Encoded CSS from Design Options panel — e.g., `css=".vc_custom_12345{background-color:#f5f5f5;padding:20px}"`
+- **Link encoding**: URLs in button/link elements use percent-encoding — `url:https%3A%2F%2F...||target:_blank`
+- **Full-width modes**: `full_width` attribute: `stretch_row`, `stretch_row_content`, `stretch_row_content_no_spaces`
+- **Element classes**: `el_class` for custom CSS classes, `el_id` for IDs
+- **Templates**: Saved as separate post type, referenced by ID
+
+Read WPBakery content via `respira_extract_builder_content` with `builder=wpbakery`.
+
+## Target: Gutenberg (Block Editor)
+
+Gutenberg stores content in `post_content` as HTML with block delimiters:
+
+```html
+<!-- wp:columns -->
+<div class="wp-block-columns">
+  <!-- wp:column {"width":"50%"} -->
+  <div class="wp-block-column" style="flex-basis:50%">
+    <!-- wp:heading {"level":2} -->
+    <h2 class="wp-block-heading">Welcome</h2>
+    <!-- /wp:heading -->
+    <!-- wp:paragraph -->
+    <p>Content with <strong>formatting</strong>.</p>
+    <!-- /wp:paragraph -->
+  </div>
+  <!-- /wp:column -->
+</div>
+<!-- /wp:columns -->
+```
+
+Key Gutenberg specifics:
+- Block attributes in opening comment JSON
+- Column widths as percentages
+- Inline styles via `style` attribute
+- Everything in `post_content`
+
+Write Gutenberg content via `respira_update_page` or `respira_update_post` targeting the `content` field.
+
+## Execution Workflow
+
+### Phase 1: Pre-Migration Audit
+
+1. Verify Respira + MCP connection via `respira_get_site_context`. If unavailable, stop and show setup guidance.
+2. Confirm WPBakery is active via `respira_list_plugins`.
+3. Check WordPress version (6.0+ required, 6.3+ ideal).
+4. Identify active theme — note if it bundles WPBakery and adds custom elements.
+5. Scan and scope all WPBakery content:
+   - `respira_list_pages` and `respira_list_posts` — identify all content
+   - `respira_find_builder_targets` with `builder=wpbakery` — inventory the WPBakery-managed pages to scope the migration
+   - Confirm the builder per page via `respira_get_builder_info`
+6. Extract WPBakery content via `respira_extract_builder_content` with `builder=wpbakery`
+7. Build inventory:
+   - Total pages/posts using WPBakery
+   - Element types used (frequency count)
+   - Theme-specific custom elements (flagged)
+   - Third-party addon elements (flagged)
+   - vc_grid/masonry elements (flagged)
+   - Design Options CSS complexity
+   - Complexity per page (simple/moderate/complex)
+   - Encoded links that need decoding
+
+### Phase 2: Migration Plan
+
+```
+## WPBakery → Gutenberg Migration Plan
+
+### Site Context
+WPBakery sites are often older WordPress installations. Consider this migration
+as a modernization opportunity — not just a builder swap.
+
+### Theme Note
+[If theme bundles WPBakery]: Your theme ([theme name]) bundles WPBakery
+and likely adds custom elements. These theme-specific elements (X found)
+will need manual recreation. Consider whether this theme should also
+be updated to a modern block theme.
+
+### Site Inventory
+- Total WPBakery pages: X
+- Total elements to convert: X
+- Direct block equivalents: X (Y%)
+- Approximate equivalents: X (Y%)
+- Manual recreation needed: X (Y%)
+
+### Element Mapping Summary
+| WPBakery Element    | Gutenberg Block  | Fidelity  |
+|--------------------|-----------------|-----------|
+| vc_column_text     | wp:paragraph    | Exact     |
+| vc_single_image    | wp:image        | Exact     |
+| vc_custom_heading  | wp:heading      | Exact     |
+| vc_btn             | wp:buttons      | Close     |
+| vc_row/vc_column   | wp:columns      | Close     |
+| vc_gallery         | wp:gallery      | Close     |
+| vc_toggle          | wp:details      | Close     |
+| vc_grid            | wp:query        | Manual    |
+| [theme element]    | —               | Manual    |
+
+### Design Options Analysis
+- Pages with simple Design Options: X (colors and padding — auto-mapped)
+- Pages with complex Design Options: X (gradients, borders — partially mapped)
+
+### Page-by-Page Plan
+1. **[Page Title]** — X elements, [complexity]
+2. ...
+```
+
+Ask for confirmation:
+> WPBakery → Gutenberg is a modernization step. Pages will be cleaner and faster.
+> 1. Migrate all pages
+> 2. Migrate specific pages
+> 3. Start with a test page (recommended for sites with theme-bundled elements)
+> 4. Just keep this plan
+
+### Phase 3: Page-by-Page Migration
+
+For each approved page:
+
+1. Read WPBakery content via `respira_extract_builder_content` with `builder=wpbakery`
+2. Parse the shortcode tree:
+   - Identify vc_row → vc_column → element hierarchy
+   - Decode CSS from Design Options attribute
+   - Decode link URLs from WPBakery's percent-encoding format
+   - Handle vc_row_inner/vc_column_inner nesting
+3. Map each element:
+   - `vc_row` → `<!-- wp:columns -->` (check `full_width` for alignment)
+   - `vc_column` → `<!-- wp:column {"width":"X%"} -->` (convert fractions: 1/2→50%, 1/3→33.33%, etc.)
+   - `vc_column_text` → Parse inner HTML, split into appropriate blocks:
+     - `<h2>` → `<!-- wp:heading {"level":2} -->`
+     - `<p>` → `<!-- wp:paragraph -->`
+     - `<ul>/<ol>` → `<!-- wp:list -->`
+   - `vc_single_image` → `<!-- wp:image {"id":N,"sizeSlug":"large"} -->`
+   - `vc_btn` → `<!-- wp:buttons -->` (decode URL, map style/color)
+   - `vc_custom_heading` → `<!-- wp:heading -->` (extract tag, text, alignment)
+   - Map Design Options CSS to block style attributes where possible
+   - Apply `el_class` as `className` in block attributes
+   - Apply `el_id` as `anchor` in block attributes
+   - Flag unmappable elements with `<!-- MIGRATION NOTE: ... -->`
+4. Assemble block markup
+5. Take a `respira_get_snapshot` checkpoint of the target before any write, so the page can be restored exactly if the conversion needs unwinding
+6. Create duplicate via `respira_create_page_duplicate` or `respira_create_post_duplicate`
+7. Write the block markup to the duplicate via `respira_update_page` or `respira_update_post`
+8. Surgical fixes (not a rewrite): when a single block lands wrong — a heading, a button label, a column width — locate it with `respira_find_element` and correct it in place with `respira_update_element`. For repeated corrections across many blocks or several migrated pages, batch them with `respira_batch_update` rather than regenerating and re-writing whole pages.
+9. Report: elements converted, flagged, layout notes
+
+### Phase 4: Post-Migration Verification
+
+1. Summarize all migrations
+2. For each migrated page:
+   - Link to edit in Gutenberg
+   - Flagged items
+   - Design Options settings that were simplified
+3. Post-migration checklist:
+   - [ ] Open each duplicate in block editor — verify all blocks are valid
+   - [ ] Check that vc_column_text HTML parsed into correct block types
+   - [ ] Verify images (check that image IDs still resolve)
+   - [ ] Test all buttons (decoded URLs working correctly)
+   - [ ] Check responsive preview
+   - [ ] Recreate theme-bundled custom elements manually
+   - [ ] Set up any needed block patterns for repeated layouts
+   - [ ] Consider theme modernization if using an older WPBakery-bundled theme
+   - [ ] Test page speed (expect significant improvement)
+   - [ ] Search for any remaining vc_ shortcode remnants
+
+## Safety Model
+
+- Read-only analysis first — full content scan before any changes
+- Explicit user confirmation required before creating duplicates
+- Original WPBakery pages are never modified or deleted
+- All migrated content goes to draft duplicates only
+- Never auto-publishes migrated pages
+- Takes a `respira_get_snapshot` checkpoint before each write
+- Explicit rollback: restore the snapshot via `respira_restore_snapshot`, or delete the draft duplicates if they are not wanted
+- Warns about theme-bundled element dependencies
+
+## Honest Disclaimer
+
+This skill converts WPBakery page content to Gutenberg blocks and creates draft duplicates for review.
+
+It cannot:
+- Convert theme-specific custom WPBakery elements
+- Migrate WPBakery addon plugin elements
+- Perfectly translate complex Design Options CSS
+- Convert post grids (vc_grid) to Query Loop automatically
+- Handle Revolution Slider or other bundled plugins
+- Replace visual review and manual adjustment
+
+It can:
+- Convert 70-85% of standard WPBakery elements to clean blocks
+- Parse and decode WPBakery's URL encoding and CSS attributes
+- Handle nested row/column structures including inner rows
+- Split vc_column_text HTML into proper individual blocks
+- Dramatically reduce page weight and load time
+- Modernize older WordPress sites
+- Keep original pages completely safe
+
+## Tooling
+
+**Core WordPress tools**
+- `respira_get_site_context`
+- `respira_list_plugins`
+- `respira_list_pages`
+- `respira_list_posts`
+- `respira_read_page`
+- `respira_read_post`
+- `respira_get_builder_info`
+- `respira_extract_builder_content`
+- `respira_find_builder_targets`
+- `respira_create_page_duplicate`
+- `respira_create_post_duplicate`
+- `respira_update_page`
+- `respira_update_post`
+- `respira_get_snapshot`
+- `respira_restore_snapshot`
+- `respira_find_element`
+- `respira_update_element`
+- `respira_batch_update`
+
+## Telemetry
+
+After run completion, send fire-and-forget usage tracking to:
+
+- `POST https://www.respira.press/api/skills/track-usage`
+
+Include:
+- `skill_slug = migrate-wpbakery-to-gutenberg`
+- site/version context
+- duration and success
+- pages migrated, blocks created, elements flagged counts
+- tools used
+
+Never block user flow on telemetry failure.
+
+## Related Skills
+
+- WordPress Site DNA (audit site structure and theme before modernizing)
+- Internal Link Builder (verify links post-migration)
+- SEO & AEO Amplifier (verify SEO post-migration)
+- Technical Debt Audit (find WPBakery shortcode remnants and outdated theme code)
+
+---
+
+Built by Respira Team
+https://respira.press/skills/migrate-wpbakery-to-gutenberg