diff --git a/skills/woodmart-mcp.md b/skills/woodmart-mcp.md
new file mode 100644
index 0000000..28cde84
--- /dev/null
+++ b/skills/woodmart-mcp.md
@@ -0,0 +1,81 @@
+---
+name: woodmart-mcp
+description: Playbook for controlling the Woodmart theme through this plugin's woodmart_* and theme_* tools — theme options, HTML blocks, layouts, widgets, and the backup/restore safety rule. Read before changing any Woodmart theme setting.
+version: 1.0.0
+auto-load: false
+tags: [woodmart, theme, woocommerce, options, html-blocks]
+---
+
+# Woodmart MCP — Theme Control Playbook
+
+## When to use this skill
+
+Load before touching anything Woodmart-specific: theme options (colors, header, shop layout), HTML blocks, mega menus, or Woodmart's own page-builder elements. For Elementor structure see `wordpress-elementor`; for store data see `woocommerce`.
+
+---
+
+## Step 0 — confirm Woodmart is active
+
+Always start with `woodmart_detect`. It returns `{active, name, version, option_store}`. On this site that is Woodmart 8.4.1, option store `xts-woodmart-options`. If `active` is false, stop — none of the woodmart_* tools will do anything useful and you may be on the wrong site. (Site targeting: resolve the request against the site registry id and use only that entry's access method.)
+
+---
+
+## Theme options — the single source of truth
+
+Woodmart stores its configuration in one serialized option, `xts-woodmart-options`. Read before you write.
+
+- `woodmart_list_options` — enumerate available option keys.
+- `woodmart_get_option(key)` — read one value.
+- `woodmart_set_option(key, value)` — write one value.
+- `woodmart_restore_option(key)` — roll back to the pre-change backup.
+
+**The safety rule:** `woodmart_set_option` snapshots the previous value into the `amp_wd_backup` store before writing. Every change is therefore reversible with `woodmart_restore_option`. Still: change one key at a time, verify on the live page, then move on. Never batch-blind a dozen theme options — a wrong serialized value can affect the whole site chrome.
+
+Common option domains: global colors/typography, header layout and sticky behavior, shop/catalog layout (columns, filters, quick-view), single-product layout, footer, and performance toggles. Confirm the exact key with `woodmart_list_options` rather than assuming the slug.
+
+---
+
+## HTML blocks — Woodmart's reusable content units
+
+Woodmart HTML blocks are a custom post type used for headers, footers, mega-menu panels, popups, and injected sections.
+
+- `woodmart_list_html_blocks` — list existing blocks with their ids.
+- `woodmart_get_block(id)` — read a block's content.
+- `woodmart_create_html_block(...)` — create a new block.
+
+Use blocks for content that must appear in several places (a promo bar, a footer column, a mega-menu panel) — edit once, it updates everywhere it's referenced. Don't rebuild the same markup inline across pages.
+
+---
+
+## Layouts and widgets
+
+- `woodmart_list_layouts` — Woodmart layout definitions (header/footer/shop layouts registered by the theme).
+- `woodmart_list_widgets` — Woodmart's own widgets/elements (the theme registers ~150, including Elementor widgets). Use this to see what Woodmart gives you before pulling in a third-party addon.
+- Theme-capability probes (useful for planning): `theme_woodmart_elements`, `theme_elementor_support`, `theme_elementor_tokens`, `theme_page_templates`, `theme_widget_areas`, `theme_taxonomies`, `theme_custom_post_types`.
+
+---
+
+## Woodmart + WooCommerce
+
+Woodmart is a shop theme — most of its options shape the WooCommerce experience (product grid, cart, checkout, wishlist, compare, quick view). When a store task is really a *presentation* task (how products look, shop columns, catalog filters), it's a Woodmart option, not a WooCommerce setting. Rule of thumb: **what the shop sells and how it transacts = `wc_*`; how the shop looks = `woodmart_*`.** See the `woocommerce` skill for the data side.
+
+---
+
+## Safe-change workflow
+
+1. `woodmart_detect` — confirm active + version.
+2. `woodmart_list_options` / `woodmart_get_option` — read current state.
+3. `woodmart_set_option` — change ONE key (auto-backs-up).
+4. `cache_purge_all` — Woodmart and the cache layer both cache theme output; purge or you'll see the old chrome.
+5. Verify on the live URL.
+6. Wrong? `woodmart_restore_option(key)` and purge again.
+
+---
+
+## Gotchas
+
+- **Change didn't show** → theme/cache layer served the old version. `cache_detect` then `cache_purge_all`. Woodmart also has its own CSS cache; a theme-option save usually regenerates it, but purge to be sure.
+- **Guessed an option key** → `woodmart_set_option` on a wrong key is a no-op or worse. Always list first.
+- **Batch theme edits** → one bad serialized value breaks site chrome globally. One key at a time, verify between.
+- **Edited shop *layout* via WooCommerce settings** → wrong layer. Catalog/product presentation is Woodmart options.
+- **HTML block edited but not showing** → confirm the block is actually referenced by the header/footer/menu location; creating a block doesn't place it.