wordpress

name	wordpress
description	Create, edit, and test WordPress sites locally. Use for any WordPress work - creating or editing sites, block themes, templates, patterns, Gutenberg block markup, theme.json, wp-cli, WordPress Playground, or local WordPress development and testing.

WordPress (local-first)

Build and edit WordPress sites locally on WordPress Playground: site lifecycle, block themes and patterns, block-markup validation, design polish, and backup discipline. Deploying to WordPress.com is not yet supported by this skill — stay local or point the user to the WordPress.com UI.

Requirements: Node 18+ and a POSIX shell (macOS/Linux/WSL — native Windows is unsupported). Script paths below are relative to this skill directory; resolve them to absolute paths. Run scripts/playground.sh from the project directory (its state lives in ./workdir/.playground/).

Routing

Task	Read
Run/create a local site, any server lifecycle or wp-cli need, Playground facts	references/local-sites.md
Write or edit ANY block markup (templates, parts, patterns, post content)	references/block-markup.md
Build a theme: structure, theme.json, fonts, patterns, navigation, query loops	references/themes-and-patterns.md
New site / redesign (browser design previews + selection); polish rendered output	references/design.md
User points at a reference website (inspiration, "build for", rebuild, "unlike X")	references/inspiration.md
Decide the site's page-frame shape + header behavior before building (site spec)	references/site-spec.md
Build the page-frame CSS for a non-default layoutMode (sidebar, landing, magazine, gallery)	references/layout-modes.md
Make a theme look designed, not generated: aesthetic direction + per-page composition	references/aesthetics.md
Add tasteful scroll motion to a built theme (reveal, hero-fade, sticky header)	references/motion.md
Images for a site: generate (AI via the user's WordPress.com login), add, or remove	references/images-media.md
Anything destructive on a site the user calls production	references/backups-and-safety.md

Non-negotiable rules

1. Local WordPress = Playground via scripts/playground.sh (verbs: bootstrap | ensure | wp | front-page | status | stop). Docker is banned. Never hand-roll a MySQL/PHP stack, never wp-now.
2. Local sites you created are disposable; production is not. Before any destructive write to a user-designated production site, create and verify a backup manifest (references/backups-and-safety.md). If the user says to skip it, refuse — creating one takes ~30 seconds. File copies count as writes.
3. Block work isn't done until both gates pass. Per file, as you write/edit markup: auto-repair with fix-blocks.cjs (mechanical, no browser; fixes the recurring cover/border/order INVALID cases), then validate-blocks.cjs — both instant. Run the slow editor-gate.mjs (live editor) once per hand-back, at the very end, after every file is inner-loop-clean — not per file and not as a fix-discovery loop; it should pass first try. Do not hand-fix validity or open the editor to fix it; run the fixer. Invalid blocks render fine on the frontend and break only in the editor — screenshots can't catch them. (references/block-markup.md.)
4. Never edit WordPress core. wp search-replace always dry-runs first.
5. Leave the server running when you hand work back — the user needs it live to test. Do NOT run playground.sh stop just because development is "done"; stopping a site the user is about to try is a defect, not cleanup. Stop ONLY when the user asks, or when you must restart to change the mount set. Whenever you stop — and when you finish — give the user the one-line playground.sh ensure … command to bring the site back. (stop still asserts clean teardown and must print "stopped clean" on the occasions you do run it.)
6. End every rendered change by printing a clickable link the user can test. Print the live URL from the recorded port — http://127.0.0.1:$(cat workdir/.playground/server.port)/ — deep-linked to the part you changed: a section anchor (…/#<anchor>), a specific page (…/sample-page/), or the editor (…/wp-admin/) for editor-only work. Default to the home page for general or site-wide changes. Always resolve the real running port; never hardcode or assume one.
7. For new sites/redesigns, users choose from rendered HTML previews in a browser (references/design.md) — never from text directions, terminal option lists, or ASCII mockups. The number of previews scales to the brief: an open brief or material redesign gets the 4-direction gallery; a tightly-specified brief gets a first-fold preview built to that brief (still shown and approved in the browser — not silently skipped). Build what the user asked for; previews confirm the execution, they don't reopen a decision the brief already made.