siteagent-elementor-studio

# SiteAgent Elementor Studio Skill You are operating against a WordPress site with the **elementor-mcp** server (`https://github.com/Digitizers/elementor-mcp` — our fork, Elementor 4.x-correct) connected via the WordPress MCP Adapter. This skill captures everything I learned the hard way the first time through, so subsequent sessions start at expertise level. ## 🛑 First Action Protocol — ASK BEFORE DOING **When this skill is invoked, do not start running tools. Ask the user what they want first.** > **Shell / setup actions run only on explicit user confirmation.** The bundled `setup-elementor-mcp.sh` (which shells out, runs Local's WP-CLI, downloads the plugin, and writes a credentialed `.mcp.json`) is never run automatically — offer it and wait for the user to say yes. If the user's invocation message *already* contains a clear task — *"build me a hero section from `index.html`"*, *"show me my current global colors"*, *"change the burgundy to navy"* — proceed with that task directly. Otherwise *(invocations like `/siteagent-elementor-studio` alone, or "use the Elementor MCP" with no follow-up)*, **respond with this menu and wait for the user to pick:** ``` What would you like to do with your Elementor site? 1. Build — create new pages or sections from a design 2. Edit — change something on an existing page 3. Reference — inspect current state (pages, colors, fonts, content) 4. Explore — show me what's possible / what can the MCP do here ``` Do **not** silently default to "build" — that's the most destructive action and forces a path the user may not want. Wait for the user to choose 1/2/3/4 *(or describe their task in their own words)* before invoking any MCP tool other than the harmless read-only ones at the bottom of this section. ### Read-only "smoke test" calls that are always safe to run When the user picks any option, you can run these **before** asking follow-up questions, since they help frame the next response: - `mcp__elementor__elementor-mcp-list-pages` — confirms auth + lists what's there - `mcp__elementor__elementor-mcp-get-global-settings` — current colors/fonts kit That's it for unprompted tool calls. **Anything that creates, modifies, or deletes data requires the user to have explicitly asked for it.** ## When this skill applies - The user mentions Elementor MCP, types `/siteagent-elementor-studio`, or says "use the Elementor MCP" - A `.mcp.json` in the project registers an MCP server pointing at `wp-json/mcp/elementor-mcp-server` - The user asks to build, edit, inspect, or troubleshoot an Elementor page - Tools beginning with `mcp__elementor__elementor-mcp-*` are available ## First-session setup (when MCP not yet connected) > **Engine:** this skill drives our fork `Digitizers/elementor-mcp` (v1.34.1, the release this kit's installer pins; Elementor 4.x-correct), a single self-contained plugin — no Freemius, no phone-home. Since fork v1.28.0 it carries its own update checker, which **offers** later GitHub Releases on the site's normal Updates screens (release-only, a user agent naming only the plugin); installing one is WordPress's ordinary update flow, and the fork does not switch on WordPress's per-plugin auto-update. **Never run it alongside the paid "MCP Tools for Elementor (Premium)" — same class names → fatal.** Details + switch commands → `references/engine-and-premium.md`. If the user has a WordPress site but no **working** `elementor` MCP connection — either no `.mcp.json` at all, or only this kit's committed placeholder config (values like `"WP_URL": "${WP_URL:-}"` with those env vars unset) and no `mcp__elementor__elementor-mcp-*` tools loaded: > In the placeholder case there are two fixes, not one: **export `WP_URL` / `WP_USERNAME` / `WP_APP_PASSWORD`** (the committed config reads them — fastest in this repo's checkout or a cloud session), or run the wizard below from a **separate per-site project directory** (it refuses to write credentials into the tracked placeholder file). 1. **Check whether they're using Local-by-Flywheel or a live host.** Setup paths differ. 2. **Run the bundled setup script** from the loaded skill's directory — it handles plugin install, auth wiring, and `.mcp.json` generation interactively for both flavors. The skill's base directory is announced when this skill loads (look for the filesystem path in the skill load message). Replace `<skill-dir>` with that announced path: ```bash bash "<skill-dir>/setup-elementor-mcp.sh" ``` Keep the quotes — plugin-cache paths can contain spaces (e.g. a Windows profile named `First Last`), and an unquoted substitution splits the path. **If `<skill-dir>/setup-elementor-mcp.sh` is not found** (e.g., from a manual `INSTALL.sh` run instead of plugin-marketplace), use the fallback path for manual installations: ```bash bash ~/.claude/scripts/setup-elementor-mcp.sh ``` 3. After the script completes, instruct the user to **quit and reopen Claude Code in the project directory** so the new `.mcp.json` is picked up. 4. On reopen, the deferred MCP tools will be exposed via ToolSearch — load the ones you need with `select:` queries. If something fails, see "Setup gotchas" below. ## Working session conventions ### Always do this first ``` mcp__elementor__elementor-mcp-list-pages # confirms auth + lists existing pages mcp__elementor__elementor-mcp-get-global-settings # see existing colors/fonts kit mcp__elementor__elementor-mcp-get-container-schema # ground truth on flex_* key names ``` ### 🎯 Detect Pro vs Free FIRST — it changes which path you take Before building anything, determine whether **Elementor Pro** is active. The whole skill branches on this: with Pro you use native widgets (Form, Theme Builder, Loop Grid, Popups, Dynamic Tags, Sticky/Motion); without it you use the free-tier workarounds documented further down (Fluent Forms, UAE/HFE, HTML for motion). **How to detect — by tool availability (the definitive Pro signal):** The elementor-mcp server exposes Pro tools **conditionally**. When Pro is active the tool list grows from ~74 to ~100+ tools and Pro-only tools appear. Check whether these exist in your available `mcp__elementor__elementor-mcp-*` tools: - `add-form` — present ⇒ **Pro active** - `create-theme-template` — present ⇒ **Pro active** - `add-loop-grid` / `add-loop-carousel` — present ⇒ **Pro active** - `create-popup`, `set-dynamic-tag` — present ⇒ **Pro active** If none of those Pro tools are exposed, treat the site as **Free** and use the workarounds. The **tool-presence check above is the definitive Pro-vs-Free signal** — prefer it. (`detect-elementor-version` is reliable on current builds — the old v1.5.0 schema bug is fixed — but it reports **atomic/version** support, not a Pro flag, so it doesn't settle Pro-vs-Free on its own.) > **Record the verdict once** ("Pro detected" / "Free only") and state it to the > user up front, then follow the matching branch in every section below. Each > "Forms", "Header/Footer", and motion section is written as **If Pro → … / > If Free → …**. Don't mix paths. ### 🧬 Also detect the ENGINE — classic vs atomic (Elementor 4 / V4) There's a **second** axis that changes everything: the page engine. Elementor 4 introduced the **atomic / V4** engine (`e-flexbox`, `e-div-block`, atomic widgets, a typed-prop `$$type` data model). Classic widget writes **do not persist on an atomic page** — they silently appear to do nothing. So before building, decide classic vs atomic. **How to detect — by atomic tool availability (preferred):** The atomic tools register only when the site is on the atomic engine. Check your available tools: - `add-flexbox`, `add-div-block`, `add-atomic-heading` / `add-atomic-button` / …, `add-atomic-widget` / `update-atomic-widget` present ⇒ **atomic (V4) engine** - Only classic `add-container` / `add-heading` / … present ⇒ **classic engine** You may also call `detect-elementor-version` (reliable on current releases — it returns whether atomic is supported). The old v1.5.0 schema bug is fixed; still, tool-presence is the most direct signal. > **Which elementor-mcp PLUGIN version am I on?** Some behaviour below branches on > it, and `detect-elementor-version` answers about *Elementor*, not the plugin. > Call **`server-info`**: it returns `plugin_version` (plus registered-vs-exposed > tool counts and what is withholding the rest). It is always registered and > cannot be disabled, so **its absence is itself the answer** — no `server-info` > means the site is on **1.28.0 or older**. Use it for the one branch that needs it — > whether `update-atomic-widget` can restyle in place (1.28.1+). Nothing else should > depend on the version: for the universal atomic tools, pass raw `$$type` values, which > are correct on every build. > ⚠️ **Antigravity / tight tool caps.** Antigravity caps MCP tools at ~100. The > full Pro+atomic set is ~113, so atomic tools can get truncated and never reach > the client — making a V4 site look like "writes don't persist". Fix: enable the > MCP plugin's **Low-tools mode** (WP Admin → MCP Tools screen). Its curated > essentials set **includes the 5 atomic essentials** (`detect-elementor-version`, > `add-atomic-widget`, `update-atomic-widget`, `add-flexbox`, `add-div-block`) and > stays under the cap. > 🐞 **Known root cause (older MCP builds).** Elementor often runs atomic as an > opt-in *experiment* while `ELEMENTOR_VERSION` still reads `3.x`. MCP builds that > gate atomic on `version_compare(ELEMENTOR_VERSION,'4.0.0','>=')` therefore never > register the atomic tools on those sites. Fixed upstream by detecting via the > experiment/module. If atomic tools are missing on a clearly-V4 site, update the > elementor-mcp plugin (or confirm the V4 experiment is on under Elementor → > Settings → Features). Record **both** axes: e.g. "Pro + atomic", "Pro + classic", "Free + classic". The Pro/Free axis picks Form vs Fluent Forms etc.; the engine axis picks classic vs atomic widget tools (next section). The container schema is large (~50KB). Read it once, then write down the keys you'll use in your reply text so you don't need to re-fetch it. Critical keys: - `flex_direction`, `flex_justify_content`, `flex_align_items`, `flex_gap`, `flex_wrap` — note the **`flex_` prefix** on justify/align (issue #32 was about these being written under wrong keys in older versions) - `content_width: "boxed"|"full"` + `boxed_width: {unit, size, sizes}` - `min_height: {unit, size, sizes}` — use unit `vh` for full-screen heroes - `padding`/`margin: {unit, top, right, bottom, left, isLinked}` — `isLinked: false` when sides differ - `background_background: "classic"|"gradient"|"video"` — must be set first or other background_* keys are ignored - `background_overlay_*` — separate parallel set for overlays. `background_overlay_opacity: {unit:"px", size: 0.5}` (yes, the unit is `px` even for opacity — quirk of the schema) ### Widget call convention — flat params, NOT nested in `settings` This bit me hard the first time. The `add-*` shortcut tools take their settings as **top-level parameters**, not inside a `settings: {}` object: ```js // ✓ CORRECT mcp__elementor__elementor-mcp-add-heading({ post_id: 11, parent_id: "abc123", title: "where estates <em>are entrusted</em>", header_size: "h1", title_color: "#FFFFFF", typography_typography: "custom", // ← required to enable typography typography_font_family: "Cormorant Garamond", typography_font_size: {size: 110, unit: "px"}, typography_font_weight: "300", typography_line_height: {size: 0.98, unit: "em"}, }) // ✗ WRONG — silently fails or returns "title is required" mcp__elementor__elementor-mcp-add-heading({ post_id: 11, parent_id: "abc123", settings: {title: "...", typography_font_family: "..."} }) ``` `add-container` is the **exception** — it takes a `settings: {}` object. Don't generalize from one to the other. ### Always set `typography_typography: "custom"` Without this, the other typography_* keys are ignored. Same applies to `css_filters_css_filter: "custom"` for image filters, etc. — these "enable" flags are how Elementor knows you want to override defaults. ### Italic emphasis pattern Display headings often need a single italic-emphasized word. Don't use a separate widget — just inline `<em>` in the title: ```js title: "A <em>quiet</em> practice for an <em>uncommon</em> clientele." ``` Cormorant Garamond and most luxury serifs have italic variants that auto-load when `<em>` appears. Confirm via the rendered page; if italics fail, the global typography needs the italic variant explicitly enabled. ### Responsive values — suffix keys (classic) vs. variants (atomic) Elementor stores a responsive control's per-breakpoint values under **suffixed keys**. The base (desktop) value has **no suffix**; each breakpoint appends its own suffix to the **same base control key**, with the **same value shape** as desktop: ```js // classic widget — tablet/mobile overrides of the same control: mcp__elementor__elementor-mcp-add-heading({ post_id, parent_id, title: "...", typography_font_size: {size: 110, unit: "px"}, // desktop (base, no suffix) typography_font_size_tablet: {size: 72, unit: "px"}, // tablet typography_font_size_mobile: {size: 44, unit: "px"}, // mobile align: "left", align_tablet: "center", // alignment per breakpoint }) ``` **The suffix set is breakpoint-dependent — do NOT hardcode an incomplete list.** It derives from Elementor's **active breakpoints** (`add_responsive_control()`), so beyond `_tablet` / `_mobile` a site may expose `_widescreen`, `_laptop`, `_tablet_extra`, `_mobile_extra`, or custom ones. Read the site's breakpoints rather than assuming; the fork passes any `<base>_<breakpoint>` key through as long as `<base>` is a real control. > **Atomic (V4) is different — no suffix keys.** On a V4 page responsive lives in a style > definition's **`variants` array**, keyed by a `breakpoint` meta (`desktop` = base, then > `tablet`/`mobile`/custom) — Global Classes take a `variants` param, local styles add > variant entries. Never put `_tablet`/`_mobile` suffix keys on atomic elements. See > `references/atomic-v4.md` and `references/design-system-crud.md`. ## The widget-vs-HTML decision — DEFAULT TO NATIVE WIDGETS > 🚨 **CRITICAL ANTI-PATTERN — read this first.** > > **Do NOT paste an entire HTML page into one HTML widget.** Do NOT build a homepage that is "1 container with 3 HTML widgets inside." That is not building with Elementor — that is using Elementor as a wrapper around a static webpage. The user **cannot edit it** in the Elementor visual editor, **cannot reuse the design tokens**, and **cannot iterate** on it without going back to source code. > > If you find yourself thinking *"I'll just dump this section as HTML, it's faster,"* **STOP.** Break it into native widgets. ### Always default to native widgets For every section the user wants, build it from native Elementor widgets: - **Headings** → `add-heading` widget *(supports inline `<em>` for italic emphasis)* - **Body copy** → `add-text-editor` widget - **Images** → `add-image` widget *(NOT an `<img>` tag inside an HTML widget)* - **Buttons / CTAs** → `add-button` widget *(NOT an `<a>` styled as a button)* - **Layout / spacing** → `add-container` with proper `flex_*` settings *(NOT `<div>`s with CSS flex)* - **Lists** → `add-icon-list` widget