| 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
- 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.
- 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.
- 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.)
- Never edit WordPress core.
wp search-replace always dry-runs first.
- 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.)
- 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.
- 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.
