Add wordpress-elementor skill (elementor_* tool-usage playbook)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q8t9GEyyLZbUQu26na1JQg

skills/wordpress-elementor.md

@@ -0,0 +1,87 @@
+---
+name: wordpress-elementor
+description: Tool-usage playbook for driving Elementor correctly through this plugin's elementor_* tools — page/element model, safe edit order, global kit, templates, and the gotchas that corrupt _elementor_data. Read before any non-trivial Elementor build or edit.
+version: 1.0.0
+auto-load: false
+tags: [elementor, wordpress, tools, workflow]
+---
+
+# WordPress + Elementor — Tool Playbook
+
+## When to use this skill
+
+Load before any Elementor build or edit that is more than a one-line text change. `landing-page-builder` tells you *what* page to build; this tells you *how* to drive the tools without corrupting the document.
+
+---
+
+## The Elementor data model (what you're actually editing)
+
+An Elementor page is a tree stored in post meta `_elementor_data` as JSON. Nodes are **containers/sections → columns → widgets**. Every node has an `id` and a `settings` object. The plugin's tools read and write this tree for you — never hand-edit the raw JSON through `update_post_meta` unless there is no tool for the change, because a malformed tree blanks the page in the editor.
+
+Each widget type has its own settings schema. Discover it, don't guess:
+
+- `elementor_list_widgets` — what widget types exist on this install (Pro/Woodmart add more).
+- `elementor_get_page` / `elementor_get_element` — read the current tree and a node's exact settings before editing it.
+- `elementor_get_page_outline` — a compact structural view for planning edits.
+
+---
+
+## Safe build order
+
+1. `elementor_create_page` → title, status `draft`.
+2. Per section, outer wrapper first: `elementor_add_container` (or `elementor_add_section`).
+3. Set the container background and padding before adding children.
+4. Inner content wrapper: another `elementor_add_container` (max-width, centered).
+5. Add widgets into the inner wrapper: `elementor_add_heading`, `elementor_add_text`, `elementor_add_button`, `elementor_add_image`, or the generic `elementor_add_widget` for anything else.
+6. Only after a section is complete, move to the next. Building depth-first per section keeps parent IDs straight.
+
+Each add returns the new element's `id`. Hold onto it — later edits, motion, and nesting all key off that id.
+
+---
+
+## Safe edit order
+
+- Read before you write: `elementor_get_element` to see current settings, merge your change, then `elementor_update_element` / `elementor_update_widget`. Blind writes drop sibling settings.
+- Structural moves use the dedicated tools — `elementor_move_element`, `elementor_reorder_elements`, `elementor_duplicate_element`, `elementor_remove_element` — not hand-rebuilt JSON.
+- Bulk changes: `elementor_batch_update` for many edits in one pass; `elementor_replace_text` / `elementor_replace_urls` for find-and-replace across the page.
+- **Always finish with `elementor_regenerate_css`** (or `elementor_flush_css`), then `cache_purge_all`. Elementor serves a per-page CSS file; without regeneration your changes render in the editor but not on the live page.
+
+---
+
+## The global kit — consistency lives here
+
+Don't style widgets one by one when a global setting exists.
+
+- Colors: `elementor_get_global_colors`, `elementor_set_global_color`.
+- Fonts: `elementor_get_global_fonts`, `elementor_set_global_font`.
+- Kit settings (site-wide spacing, buttons, defaults): `elementor_list_kits`, `elementor_get_kit_settings`, `elementor_update_kit_settings`, `elementor_get_kit_custom_css`, `elementor_update_kit_custom_css`.
+- Page-level CSS when you truly need it: `elementor_get_page_custom_css`, `elementor_update_page_custom_css`.
+
+Set the system once, reference it everywhere. A hex pasted into a widget is a future inconsistency.
+
+---
+
+## Templates, conditions, dynamic content
+
+- Save a built section for reuse: `elementor_save_as_template`; apply it elsewhere: `elementor_apply_template`; browse: `elementor_list_templates` / `elementor_list_library`, import/export with `elementor_import_template` / `elementor_export_page`.
+- Theme-builder display rules (where a header/footer/template shows): `elementor_get_conditions`.
+- Dynamic tags (Pro — pull post/ACF/site data into widgets): `elementor_get_dynamic_tags`.
+- Form submissions (Pro forms): `elementor_get_form_submissions`.
+- Clone a whole page: `elementor_clone_page` / `duplicate_elementor_page`.
+
+---
+
+## Woodmart + Elementor
+
+This site runs Woodmart. Confirm theme widget support before relying on it: `theme_elementor_support`, `theme_elementor_tokens`, `theme_woodmart_elements`. Woodmart registers its own Elementor widgets — `elementor_list_widgets` will show them. For Woodmart theme options and HTML blocks, use the `woodmart-mcp` skill's tools, not Elementor's.
+
+---
+
+## Gotchas that cost hours
+
+- **Forgot `elementor_regenerate_css`** → "my change isn't showing". Regenerate, then purge cache.
+- **Edited a widget without reading it first** → lost other settings on that widget. Always get → merge → update.
+- **Hand-wrote `_elementor_data`** → editor shows a blank/broken page. Use the element tools.
+- **Duplicate slug `-2`** after re-running a build → check and fix the slug before publishing.
+- **Mobile untouched** → set responsive padding/typography per container; desktop values suffocate on phones.
+- **Published while cache served the old page** → `cache_detect` to see the engine, `cache_purge_all` after every structural change.