bricks-skills

Use when writing custom-element controls or debugging control behavior: "what control type for a color?", "conditional control visibility", "dynamic data on a custom control". Covers the ~40 control types, the `required` syntax, CSS-binding via `css` key, dynamic-data support, and default-value gotchas.

Use before writing or editing Bricks element JSON, settings, controls, globals, page settings, or template settings. Gives the runtime lookup order plus bundled full resolved schemas so you can check exact control keys and value shapes instead of guessing.

Use after every write through the Bricks MCP: set-page-elements, update-element, update-element-conditions, update-element-interactions, batch-update-elements, set-template-conditions, set-global-variables, create-theme-style, etc. Defines the verify-after-write loop: read back the change, render the affected post, check for silent failures (empty render, unknown tags, unbalanced braces, query:null). Catches the "tool returned success but the page broke" class of bugs.

Use when the Bricks skills update check reports BRICKS_SKILLS_UPDATE_AVAILABLE, or when the user asks to update the Bricks skills pack.

Use at the start of every Bricks session. Orientation rules: call get-design-context before any design-system write, verify mutations with get-page-elements / list-revisions, and never force same-named globals to duplicate.

Use when creating or updating design tokens: global classes, variables, color palettes, theme styles, components. Enforces uniqueness, scale-generator usage, and conditions on theme styles. Prevents system fragmentation.

Use when get-design-context returns empty or near-empty and the user wants a full design system seeded on a greenfield Bricks install. Prescriptive flow: palette + shades, spacing scale, typography scale, root theme style, base classes: in the right order.

Use when checking Bricks' AI screen: the master Bricks abilities toggle, per-ability disable list, direct-tool fast path, `bricks-list-ability-status`, and error codes when an ability is off.

Use when the user asks to review, clean up, or fix their design system specifically: "review my classes", "why are my colors inconsistent", "clean up unused classes", "audit my design system". Read-only scan for orphans, unused tokens, dead theme styles, palette fragmentation. Never auto-fixes. For a full site health check, use bricks-site-audit instead.

Use when reading, adding, removing, or reordering Bricks responsive breakpoints. Covers `bricks/list-breakpoints` / `bricks/set-breakpoints`, mobile-first vs desktop-first semantics, and how breakpoint writes interact with the generated CSS.

Use when creating, editing, extracting, or deleting Bricks components. Covers properties, bindings, nested components, global-class property type, and what orphans when you delete a component in use.

Use when uploading or managing custom web fonts in Bricks: "upload Inter.woff2", "add a weight to an existing font", "list installed fonts". Covers the `bricks_fonts` CPT, font-face map, allowed formats, MIME enforcement, and the upload -> fontFaces flow.

Use when creating or managing reusable queries that multiple loop elements can share. Covers the `bricks_global_queries` option, categories, and how a query-list control on an element references a global query by ID.

Use when moving Bricks data between sites with the unified import/export MCP abilities. Covers transfer-package listing, export, inspect, import, conflict handling, sensitive settings, and site-to-site package migration.

Use when running Bricks housekeeping: "regenerate all CSS files", "find orphaned elements", "clean up abandoned builder data". Covers `bricks/regenerate-css-files`, `bricks/list-orphaned-elements`, `bricks/cleanup-orphaned-elements`. Excludes code-signature regeneration.

Use before creating or renaming any global class, variable, component, or template. Detect the site's existing naming convention and match it: never fragment by creating a parallel one.

Use when the user describes what they want in freeform ("build a pricing page", "add a hero", "make the button bigger"). Turns a brief into a concrete ability-call plan before any writes, surfacing gaps and ambiguities for user sign-off.

Use when reading or changing which WordPress roles can use Bricks builder panels and features. Covers builder permission keys, custom builder capabilities, role access assignments, and why code execution stays outside MCP.

Use when reading or changing Bricks global settings (post types, CSS loading, maintenance mode, performance toggles). Covers the allow-list registry flow, partial-merge semantics, and what keys are excluded from MCP by design.

Use when registering or managing custom WordPress sidebars through Bricks: "add a Shop sidebar", "rename the footer widget area". Covers `bricks_sidebars` option shape and how Bricks sidebars surface in WP's widget admin.

Use for a complete site-wide health check: "audit my site", "what's wrong with my Bricks install", "check everything". Covers design rot, template hygiene, revision bloat, dynamic-data mismatches, and Bricks abilities availability. For design-system-only audits, use bricks-audit-design-system instead.

Use when the user wants to visually confirm a Bricks page renders correctly, regressions are absent, or a build matches a target design: "verify this page looks right", "screenshot the homepage", "check the result in a browser". Covers resolving the frontend URL from post abilities, using the available browser tool, screenshot comparison, and the iterate-via-update-element loop.

Use when building a Bricks child theme, scaffolding a new one, or debugging "my child-theme code doesn't run": "set up a child theme for Bricks", "where do custom elements go?", "how do I override a Bricks function?". Covers the directory structure, `functions.php` skeleton, autoloader patterns, hook priorities, asset enqueuing, and `woocommerce/` template overrides.

Use when writing or reviewing any custom code in Bricks: echo tag, hooks, Code element (PHP/HTML/CSS/JS), theme style CSS, page/element custom CSS, Settings > Custom code, or Custom Query PHP. Covers capability gating, render order, security, silent-failure debugging, and which extension point to reach for.

Use when adding custom Bricks dynamic-data tags in a child theme or plugin: "add a custom tag", "integrate my plugin's data with Bricks dynamic tags", "register a provider class". Covers the supported hook pattern, the internal `Base` provider contract, tag lifecycle, and scope binding in loops.

Use when building custom Bricks elements in a child theme or plugin: "register a new element", "my custom element doesn't show", "builder-preview differs from frontend". Covers the base `Element` class contract, registration via `bricks/load_elements/after`, the render split, and builder-preview parity.

Use when working with Bricks dynamic data tags: "what's the tag for ACF field X?", "why doesn't {post_title} show?", "how do modifiers work?", "format a date with dynamic data". Covers the 8 providers, `:modifier` vs `|` syntax, scope binding in loops, and the `{echo:...}` cross-reference.

Use when creating or debugging Bricks element display conditions: "show this block only for logged-in users", "hide this CTA on product archives", "why is this element not rendering?". Covers `_conditions`, OR groups, AND items, dynamic-data conditions, and the update-element-conditions MCP writer.

Use when porting a Figma frame, page, or design system into Bricks: "convert this Figma design", "build this from the Figma file", "import Figma tokens". Covers the Figma integration handoff, token mapping (colors -> create-color-palette/create-color, spacing/radius/typography -> set-global-variables), structure via convert-html-css-to-bricks-data, components via create-component, and end-to-end verification via the bricks-browser-verify skill.

Use when building or debugging Bricks forms: "add a contact form", "hook my form to a webhook", "why isn't my form emailing?", "add a reCAPTCHA", "save submissions to the database". Covers 18 field types, up to 14 action types, submissions table, anti-spam, and the silent-failure modes production forms always hit.

Use when authoring or editing Bricks header/footer templates: "add a logo to the header", "make the footer sticky", "the header changes I made disappeared". Covers the three-meta-keys storage model, why naive postmeta edits silently no-op, and how MCP element-writes route the right area automatically.

Use when you need to find the right Bricks hook: "what filter modifies a query?", "how do I intercept render?", "is there a hook for form submit?". Curated index of Bricks actions/filters grouped by purpose, with file:line citations and return-value + priority traps.

Use when converting raw HTML and CSS into Bricks data: "convert this HTML snippet", "import this codepen", "turn this CSS into Bricks classes", "turn this markup into Bricks elements". Covers the `convert-html-css-to-bricks-data` ability, its known limits (nestables, interactions, JS), class-collision prevention via `list-global-classes`, variable-extraction strategy, CSS-only conversion, and when to author manually.

Use when building or debugging Bricks element interactions: "make this button open a popup", "toggle a class on click", "scroll to section", "why does my interaction fire twice?". Covers the 27 element triggers, 18 actions, target-selector rules, global-class inheritance, and infinite-loop traps.

Use when adding, replacing, finding, or wiring images, video, audio, galleries, or other WordPress media in Bricks. Covers upload-media, find-media, Image element settings, Gallery/Image Gallery usage, alt text, and avoiding external hotlinks.

Use when creating, editing, or debugging Bricks mega menus: Nav Nested + Dropdown mega panels, WordPress menu-backed mega menus, menu item template assignment, mobile mega menu behavior, or header navigation that needs rich dropdown content.

Use when building or debugging Bricks Slider/Accordion/Tabs/Dropdown/Nav/Offcanvas: "build a product carousel", "my tabs aren't rendering children", "add items to this accordion". Covers the 12 nestable elements, child-element contracts, loop-context scope, and component/query boundaries.

Use when diagnosing or fixing Bricks site performance: "why is my site slow?", "CSS is huge", "first-load is bad", "LCP is 4 seconds". Covers the `cssLoading` file-vs-inline setting, the loop-marker preservation trap, random-seed TTL, query cache, and the real-world fixes that move numbers.

Use when building or debugging Bricks popups: "add a newsletter popup", "show popup on exit intent", "why doesn't my popup show?", "popup shows every page load". Covers trigger types, display conditions, frequency limits, the `bricksOpenPopup` JS API, and triggers-vs-conditions (two separate systems).

Use when adding or debugging Bricks Query Filters: "add a taxonomy filter", "why doesn't my filter do anything?", "filter by a meta field", "range filter for price". Covers the 8 filter elements, the `filterQueryId` binding, the filter index, and why filters silently do nothing.