wp-contributing

Contributing to Claude WP Builder

CONTRIBUTING.md is the front door: how to fork, where files go, the PR template, the code of conduct. Read it first. This skill is the part that is not written down anywhere else — the rules you only learn by breaking them.

The one sentence that explains this repo: it is a plugin made almost entirely of prose, so nothing fails at runtime when the prose goes wrong. A contract that drifts produces a worse site, silently, three commands later. Every convention below exists because that already happened.

Part 1 — Contributors

The four layers, and what may call what

commands/*.md     user-facing slash commands — orchestration, argument parsing, step order
   ↓ dispatches
agents/*.md       specialized subagents (wp-template, wp-css, wp-acf, wp-audit-*, …)
   ↓ reads
skills/*/SKILL.md knowledge libraries — methodology, never actions
   ↓ produces
starter-theme/    PHP scaffolds copied into the user's project

Calls go down only. The rules that follow from that:

• A command must never reimplement a builder. /wp-yolo is the model: it normalizes the demo once, then drives /wp-settings, /wp-cpt, /wp-header, /wp-footer, /wp-section and /wp-seed in dependency order. It owns the order, never the work. When you need a command to do something a builder already does, dispatch that builder — a second implementation is a second thing to keep correct, and it will diverge.
• Skills inform; they never act. A skill that tells an agent to run WP-CLI belongs in an agent. user-invocable: false is not decoration — it is the whole contract.
• Every agent's first mandatory step reads the project's .claude/CLAUDE.md — the file /wp-init generates in the user's WordPress project, which is a different file from this repository's own CLAUDE.md. It carries the function prefix, theme slug, languages, template and i18n strategy. prefix_ in any agent or skill doc is a placeholder, never a literal.
• Plugin-relative paths in commands are always ${CLAUDE_PLUGIN_ROOT}/…, never relative. A relative path resolves against the user's project, not the plugin.