/migrate-oxygen-to-bricks

name: migrate-oxygen-to-bricks
description: "Use when the user says 'migrate oxygen to bricks', 'convert oxygen to bricks', or 'replace oxygen with bricks'. Maps Oxygen Builder component trees to Bricks JSON elements and creates draft duplicates for review."
license: MIT
metadata:
  author: Respira for WordPress
  author_url: https://respira.press
  version: 2.2.0
  mcp-server: respira-wordpress
  category: migration

Migrate Oxygen to Bricks

**Version:** 2.2.0 **Updated:** 2026-09-13 **Freshly updated:** v2.1.0 adds design-token awareness: conversion writes now register the colors and typography they carry as named design tokens in Bricks' own global styles, and converted pages reference those tokens instead of carrying value copies. Reuse registered tokens instead of re-inlining raw values, and report the registration in the migration summary.

Full-site migration from Oxygen Builder to Bricks Builder. Audits every Oxygen-built page, maps components to their Bricks equivalents, builds a migration plan for approval, and executes page-by-page conversion into Bricks' JSON format — all through duplicates so your live site stays untouched. Use this skill whenever someone mentions migrating from Oxygen to Bricks, switching from Oxygen to Bricks, converting Oxygen pages to Bricks, or replacing Oxygen with Bricks Builder.

What This Skill Does

Oxygen and Bricks are both modern, developer-oriented builders with similar mental models — containers, sections, flexbox layouts, dynamic data. This makes Oxygen-to-Bricks one of the most straightforward builder migrations. The structural concepts translate almost 1:1, but the underlying data formats are completely different (Oxygen's JSON shortcodes in `ct_builder_shortcodes` vs. Bricks' JSON array in `_bricks_page_content_2`), so content must be extracted, mapped, and re-encoded.

This skill reads every Oxygen page, extracts the builder content, translates each component to its Bricks equivalent, and writes the result to duplicate pages in Bricks format — giving you a complete parallel version of your site to review before going live.

**Handles:**

• Section → Bricks Section mapping
• Container/Div → Bricks Container mapping
• Heading, Text, Image, Button, Video, Icon components
• Flexbox layout settings (direction, alignment, gap, wrap)
• Column/grid structures
• Custom CSS classes and inline styles
• Link elements and CTAs
• Code blocks and custom HTML
• Repeater/dynamic data placeholders (flagged for manual review)

What This Skill Does NOT Do

• Migrate Oxygen's Global Styles or Style Sheets — Bricks uses its own theme style system
• Convert Oxygen conditions (visibility rules) — these must be rebuilt in Bricks
• Migrate Oxygen's custom PHP/code block logic — flagged for manual porting
• Recreate Oxygen templates (headers, footers, archives) — Bricks templates are structurally different and must be rebuilt
• Transfer WooCommerce builder templates — product/shop templates need separate handling
• Guarantee pixel-perfect visual parity — some spacing/sizing will need fine-tuning in Bricks

Requirements

• Respira for WordPress plugin installed and connected
• MCP connection active (desktop or WebMCP)
• Oxygen Builder active on the source site
• Bricks Builder installed on the target site (can be the same site)
• Read access to scan Oxygen content
• Write access to create duplicates with Bricks content

Trigger Phrase

• "migrate oxygen to bricks"

Alternative Triggers

• "convert oxygen to bricks"
• "switch from oxygen to bricks"
• "move oxygen pages to bricks"
• "replace oxygen with bricks"
• "oxygen to bricks migration"

Builder Technical Context

**Source: Oxygen Builder**

• Content stored in post_meta key `ct_builder_shortcodes`
• JSON-based structure encoding nested components
• Read via `respira_extract_builder_content` with `builder=oxygen`
• Components: `ct_section`, `ct_div`, `ct_headline`, `ct_text_block`, `ct_image`, `ct_link_button`, etc.

**Target: Bricks Builder**

• Content stored in post_meta key `_bricks_page_content_2` as a JSON array
• Each element is an object with `id`, `name`, `parent`, `settings`, `children`
• Write via `respira_inject_builder_content` with `builder=bricks`
• Elements: `section`, `container`, `heading`, `text`, `image`, `button`, etc.

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. Detect Oxygen presence via `respira_get_builder_info` or `respira_list_plugins`. 3. Inventory and scope the source pages first:

• `respira_find_builder_targets` with `builder=oxygen` — a fast, ranked list of every Oxygen-managed 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

4. For each Oxygen page, extract content:

• `respira_extract_builder_content` with `builder=oxygen`
• Catalog: component types used, nesting depth, custom CSS, dynamic data usage, code blocks

5. Produce an **Audit Report**:

• Total pages/posts using Oxygen
• Component type frequency (how many sections, headings, images, etc.)
• Complexity flags (custom PHP, conditions, dynamic data, WooCommerce templates)
• Estimated migration difficulty per page (simple / moderate / complex)

Phase 2: Migration Plan

Present a structured migration plan:

## Oxygen → Bricks Migration Plan

### Site Overview
- Total Oxygen pages: X
- Simple pages (direct mapping): X
- Moderate pages (some manual review needed): X
- Complex pages (significant manual work): X

### Component Mapping
| Oxygen Component | Bricks Equivalent | Notes |
|---|---|---|
| ct_section | section | Direct mapping |
| ct_div | container | Direct mapping |
| ct_headline | heading | Direct mapping |
| ... | ... | ... |

### Migration Order
1. [Page Title] — Simple — estimated 2 min
2. [Page Title] — Moderate — estima