README

Install the official WordPress agent skills into your project for Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Windsurf, Zed, Gemini CLI, Junie, and OpenCode — the same idea as laravel/boost, but for WordPress plugins and block themes.

Skills are sourced from WordPress/agent-skills. wp-boost bundles a pinned snapshot and can pull the latest on demand.

Requirements

• PHP 8.1+
• Composer 2.x

Don't have Composer yet?

Check first:

composer --version

If you see a version like Composer version 2.x, you're ready — skip to Install.

If the command isn't found, install it:

macOS / Linux:

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

Windows: download and run the installer from getcomposer.org/download.

Then make sure Composer's global bin directory is on your PATH (you'll install wp-boost there):

# find the path
composer global config bin-dir --absolute
# e.g. /Users/you/.composer/vendor/bin

# add to your shell profile (~/.zshrc, ~/.bashrc)
export PATH="$HOME/.composer/vendor/bin:$PATH"

Reload your shell (source ~/.zshrc) and verify:

composer --version

Install

composer global require huzaifaalmesbah/wp-boost

Verify:

wp-boost --version

Use

Inside any WordPress plugin or block theme project:

cd /path/to/your-project
wp-boost install

wp-boost will:

1. Detect your project type (plugin, block theme, core) and pre-select recommended skills.
2. Detect which AI agents you already use (by looking for .claude/, .cursor/, .github/, etc.) and pre-select them.
3. Let you confirm or change the selection.
4. Copy the right files into each agent's skills directory and write wp-boost.lock.json.

Non-interactive / CI

--yes accepts detected defaults. Override with flags as needed:

wp-boost install --yes                                      # use detected defaults
wp-boost install --preset=plugin --yes                      # force project type
wp-boost install --agents=claude_code,cursor --yes          # pick agents explicitly
wp-boost install --skills=wp-plugin-development --yes       # pick skills explicitly
wp-boost install --path=/path/to/project --yes              # different project path

Inspect

wp-boost doctor            # detected project type, detected agents, available skills

Get help

Every command has built-in help (provided by Symfony Console):

wp-boost                      # show all commands (same as: wp-boost list)
wp-boost --help               # top-level help
wp-boost --version            # print version

wp-boost help install         # help for a specific command
wp-boost help update
wp-boost help doctor

wp-boost install --help       # same thing, -h also works

Updating

There are two kinds of "update" and it's important to understand the difference.

1. Update wp-boost itself (the CLI tool)

Ships new features, bug fixes, and any tweaks to agent definitions (agents.json).

composer global update huzaifaalmesbah/wp-boost

(If you installed per-project instead: composer update huzaifaalmesbah/wp-boost --dev inside that project.)

2. Update the skills content in your project

Two sub-cases:

A. Re-sync from the bundled snapshot — useful after you composer global update (the new release may include newer bundled skills), or if you manually edited files and want them reset.

cd /path/to/your-project
wp-boost update

B. Refresh the global bundle, then apply to the current project

cd /path/to/your-project
wp-boost update --remote        # shortcut for: wp-boost sync  +  wp-boost update
wp-boost update --remote --upstream   # same, but pulls from WordPress/agent-skills@trunk

C. Refresh the global bundle only — no project needed

# works from anywhere, doesn't touch any project
wp-boost sync                   # default: pull from huzaifaalmesbah/wp-boost@main (vetted)
wp-boost sync --upstream        # opt-in: pull from WordPress/agent-skills@trunk (bleeding edge)

Afterwards, run wp-boost update inside each project you want to apply the new skills to. This is the fastest way to update many projects: refresh the bundle once, then cheap local syncs everywhere else.

Two sources to sync from

What exactly does sync / --remote change?

Both refresh wp-boost's own bundled skills/ directory (a copy that lives inside the installed wp-boost package itself, not inside any project).

wp-boost update --remote does the sync and re-syncs the current project in one step. Plain wp-boost sync just refreshes the bundle.

"How do I know a project needs wp-boost update?"

wp-boost stamps the bundle's commit SHA into every wp-boost.lock.json on install/update. Whenever you run wp-boost doctor, it compares the project's stamped SHA against the current bundle's SHA and prints a warning if they differ:

Bundle:   def5678 from huzaifaalmesbah/wp-boost@main (2026-04-14T08:30:00+00:00)
Project:  abc1234 (installed 2026-04-10T14:02:00+00:00)

⚠  Project is using skills from bundle abc1234; current bundle is def5678.
   Run `wp-boost update` to apply the new skills.

After wp-boost update, the SHAs match and the warning goes away.

Typical workflows

Global-install users (most common):

# refresh the global bundle once, from anywhere
wp-boost sync

# then apply to each project you care about
cd ~/project-a && wp-boost update      # fast local sync, no network
cd ~/project-b && wp-boost update

Per-project install: run wp-boost update --remote inside each project you want to refresh.

Commands

Supported agents

Driven by agents.json:

What gets written to your project

After wp-boost install (depending on agents selected):

your-project/
├── .claude/skills/<skill-name>/SKILL.md
├── .cursor/rules/<skill-name>.mdc
├── .github/instructions/<skill-name>.md
├── ...
└── wp-boost.lock.json         # records installed agents + skills

Re-running wp-boost install or wp-boost update overwrites existing skill files with the latest content — safe to do anytime.

Uninstall

composer global remove huzaifaalmesbah/wp-boost

Installed skill files stay in your project. Delete .claude/skills/, .cursor/rules/, etc. manually and remove wp-boost.lock.json if you no longer want them.

Contributing & reporting issues

Where you file things depends on what you're reporting — the CLI tool lives here, the skill content lives upstream at WordPress/agent-skills.

See CONTRIBUTING.md for the full dev guide: local setup, project structure, adding a new AI agent, testing, and release process.

Credits & attribution

wp-boost is a downstream distributor, not an author of the skill content. Everything inside the skills/ directory is an unmodified redistribution from upstream — please credit upstream first whenever you share or fork this project.

Primary credit — skill authors

WordPress/agent-skills — the WordPress contributors who author, review, and maintain every SKILL.md this tool installs. All skill content, examples, and guidance are their work and their copyright, licensed GPL-2.0-or-later.

If a skill helped you, please ★ star their repo and file issues / PRs against their tracker, not this one. Skill-content changes made against wp-boost cannot be accepted — they must land upstream so the whole WordPress + AI community benefits.

Snapshot provenance

The bundled skills/ directory is a pinned snapshot of WordPress/agent-skills@trunk. The exact upstream commit is recorded in skills/.bundle.json (sha, syncedAt, source) and stamped into every project's wp-boost.lock.json on install, so you can always trace a skill file back to the upstream commit it came from.

An automated job — .github/workflows/sync-skills.yml — runs every Monday and opens a PR bumping the snapshot whenever upstream has moved. Under normal conditions the bundle is never more than 7 days behind WordPress/agent-skills@trunk.

Also thanks to

• The WordPress community — for building and maintaining the ecosystem this tool serves.
• laravel/boost — the inspiration for the UX pattern: auto-detect the project + the agents the developer already uses, then install the right skills in one shot. wp-boost does the same job for the WordPress ecosystem.
• Every contributor to the AI coding agents this tool targets (Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, Zed, Gemini CLI, Junie, OpenCode) for shipping the skills / rules / instructions protocols this installer plugs into.

License

wp-boost is licensed under the GNU General Public License v2.0 or later (GPL-2.0-or-later), matching WordPress/agent-skills and the wider WordPress ecosystem. See LICENSE for the full text.

The bundled content in skills/ is an unmodified redistribution from WordPress/agent-skills and remains under its original GPL-2.0-or-later license, copyright the WordPress contributors.