/migrate-oxygen-to-breakdance

name: migrate-oxygen-to-breakdance
description: "Use when the user says 'migrate oxygen to breakdance', 'convert oxygen to breakdance', or 'replace oxygen with breakdance'. Maps Oxygen Builder component trees to Breakdance 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 Breakdance

**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 Breakdance's 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 Breakdance. Audits every Oxygen-built page, maps components to their Breakdance equivalents, builds a migration plan for approval, and executes page-by-page conversion — all through duplicates so your live site stays untouched. Use this skill whenever someone mentions migrating from Oxygen to Breakdance, switching from Oxygen to Breakdance, converting Oxygen pages to Breakdance, or replacing Oxygen with Breakdance.

What This Skill Does

Oxygen and Breakdance share the same developer lineage (Soflyy), which makes this one of the smoothest builder migrations available. Many component concepts, naming conventions, and architectural decisions carry over directly. However, the underlying storage formats are completely different — Oxygen uses JSON shortcodes in `ct_builder_shortcodes` while Breakdance uses its own post_meta format — so content must still be extracted, mapped, and re-encoded.

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

**Handles:**

• Section → Breakdance Section mapping
• Container/Div → Breakdance Div 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

What This Skill Does NOT Do

• Migrate Oxygen's Global Styles or Style Sheets — Breakdance uses its own global styling system
• Convert Oxygen conditions (visibility rules) — Breakdance has its own conditions system that must be configured separately
• Migrate Oxygen's custom PHP/code block logic — flagged for manual porting
• Recreate Oxygen templates (headers, footers, archives) — Breakdance templates must be rebuilt using its template system
• Transfer WooCommerce builder templates — product/shop templates need separate handling
• Guarantee pixel-perfect visual parity — some spacing/sizing will need fine-tuning

Requirements

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

Trigger Phrase

• "migrate oxygen to breakdance"

Alternative Triggers

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

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: Breakdance**

• Content stored in post_meta
• Write via `respira_inject_builder_content` with `builder=breakdance`
• Elements: `EssentialElements\Section`, `EssentialElements\Div`, `EssentialElements\Heading`, `EssentialElements\Text`, `EssentialElements\Image`, `EssentialElements\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 all Oxygen-built content:

• `respira_list_pages` and `respira_list_posts` — identify all content
• `respira_find_builder_targets` with `builder=oxygen` — find Oxygen-managed pages

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 → Breakdance 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 | Breakdance Equivalent | Notes |
|---|---|---|
| ct_section | Section | Direct mapping — same developer lineage |
| ct_div | Div | Direct mapping |
| ct_headline | Heading | Direct mapping |
| ... | ... | ... |

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

### Items Requiring Manual Attention
- [Page X] — Custom PHP code block
- [Page Y]