WordPress agent skills: seventeen bundles of rules for AI assistants

The failure modes these skills are aimed at

The README states the problem as a list of four specific mistakes, and the specificity is the argument. AI coding assistants often generate outdated WordPress patterns, described as pre-Gutenberg and pre-block-themes. They miss security considerations that matter in plugin development. They skip proper block deprecations, which produces the Invalid block error on sites you did not touch. And they ignore existing tooling in the repository.

Every one of those four is a failure of context rather than of coding ability. An assistant can write a correct hook and a correct block render callback from general knowledge. What it cannot know is which rendering approach this codebase already uses, which WordPress version it targets, or that a block attribute was renamed two versions ago and every existing post still holds the old markup. Skills are a way to put that context in front of the model before it writes anything, and the four bullets map directly onto the seventeen skills that follow.

The stated goal is expert-level WordPress knowledge in a format an assistant can actually use. The framing of the repository as teaching rather than prompting matters, because a prompt asks for an answer while a skill specifies a procedure.

Provenance is disclosed up front, which is unusual and useful. The README states the skills were generated using GPT-5.2 Codex at high reasoning from official Gutenberg and WordPress documentation, then reviewed and edited by WordPress contributors, that they were exercised against AI assistants and iterated on based on the results, and that this is v1 with improvements expected as the community contributes fixes. It points to docs/ai-authorship.md for details and to the WordPress AI Guidelines. Generated-then-reviewed is a real process, but reading it is what lets you judge which parts of a skill to trust.

Seventeen skills, and the routing layer that decides which one runs

The skill list is longer than a casual reading suggests because it includes both domain knowledge and the machinery for choosing it. Two entries at the top are routers rather than topics.

`wordpress-router` classifies a WordPress repository and routes to the right workflow. `wp-project-triage` detects project type, tooling and versions automatically. Both exist so the model can decide what it is working on before it starts, which addresses the fourth failure mode in the list above, ignoring existing tooling.

The rest divide into authoring surfaces and operations. `wp-block-development` covers Gutenberg blocks with block.json, attributes, rendering and deprecations. `wp-block-themes` covers theme.json, templates, patterns and style variations. `wp-plugin-development` covers plugin architecture, hooks, the settings API and security. `wp-interactivity-api` is for frontend interactivity using data-wp-* directives and stores, which is the modern replacement for a plugin shipping jQuery to the frontend.

`wp-rest-api` covers routes, endpoints, schema, auth and response shaping. Three skills cluster around the Abilities API, which is the part of the set that points at where WordPress is heading rather than consolidating where it is. `wp-abilities-api` covers capability-based permissions and REST API authentication. `wp-abilities-audit` audits a plugin's REST surface and proposes Abilities API registrations. `wp-abilities-verify` verifies those registrations against their declared annotations.

That trio describes a migration path with a check on it, which is a more thoughtful structure than a single API reference would be. Audit what exists, propose registrations, then verify the registrations match what they claim. The middle step is a transformation, and transformations are exactly where an assistant needs procedure rather than recall.

The operational entries are `wp-wpcli-and-ops` for WP-CLI commands, automation, multisite and search-replace, `wp-performance` for profiling, caching, database optimization and Server-Timing, and `wp-playground` for Playground routing, CLI runs, browser previews and snapshots. `blueprint` covers Playground Blueprints for declarative environment setup.

Four entries are about standards rather than code. `wp-phpstan` is PHPStan static analysis for WordPress projects, covering config, baselines and WordPress-specific typing. `wpds` is the WordPress Design System. `wp-plugin-directory-guidelines` is the Plugin Directory Guidelines, which is the document that decides whether a plugin can be listed publicly. `wp-plugin-development` is listed with its own entry and the guidelines are separate, which tells you the plugin audience spans both people writing plugins and people trying to pass review.

How a skill is structured, and why the scripts folder exists

The README describes each skill as a self-contained folder with instructions, references and optional scripts, and shows the layout for one of them:

skills/wp-block-development/
├── SKILL.md              # Main instructions (when to use, procedure, verification)
├── references/           # Deep-dive docs on specific topics
│   ├── block-json.md
│   ├── deprecations.md
│   └── ...
└── scripts/              # Deterministic helpers (detection, validation)
    └── list_blocks.mjs

Three roles, three kinds of content. SKILL.md carries when to use it, the procedure, and verification, which means the skill describes both its trigger conditions and its own exit criteria. References hold depth that would drown the main file. Scripts hold deterministic helpers for detection and validation.

That third category is the one most worth pausing on. Detection and validation are the two things a language model is worst at being trusted with, because both require agreement with the outside world rather than plausibility. Enumerating the blocks a repository actually registers is a question with exactly one right answer, and getting it wrong produces confidently incorrect work. The scripts are written in .mjs, which is plain JavaScript with no build step, and the repository itself is JavaScript, so a helper script can read a plugin directory and report what is there without a toolchain.

The verification slot in SKILL.md is worth noting alongside that. A skill that only says what to do is a tutorial. A skill that also says how to confirm the work happened is a procedure, and procedures are what you want when the output is code that will run on someone else's site.

The repository tree backs this up: `skills/` for the content itself, `shared/` for the build and install scripts, `docs/` for the documentation including the AI authorship note, `eval/` for evaluation, and a CONTRIBUTING.md. The presence of `eval/` is the most interesting entry, since it implies the skills are measured rather than merely published.

Installing: npx for one skill, a build script for all of them

There are two install paths and they suit different situations.

For a single skill, the README leads with npx:

npx skills add WordPress/agent-skills --skill wp-plugin-development

Listing everything available, and installing several at once:

npx skills add WordPress/agent-skills --list

npx skills add WordPress/agent-skills --skill wp-plugin-development wp-abilities-api wp-playground

The npx path asks you to choose a scope. Project scope installs into the local repository, at `.claude/skills/` or `.cursor/skills/` among others, which means the skills can be committed and shared with the team. The global flag installs for the user across all projects:

npx skills add WordPress/agent-skills --skill wp-plugin-development --global

For the full set, the documented route is to clone, build and install with the scripts in `shared/`:

node shared/scripts/skillpack-build.mjs --clean
node shared/scripts/skillpack-install.mjs --global

Targeting a specific project instead, with an explicit assistant list:

node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=codex,vscode,claude,cursor

The mapping that produces is worth stating plainly, because it explains why the repository calls these portable: `.codex/skills/` for OpenAI Codex, `.github/skills/` for VS Code and GitHub Copilot, `.claude/skills/` for Claude Code, and `.cursor/skills/` for Cursor. Antigravity is opt-in for project-level installs, enabled by including `antigravity` in both the build and install target lists, and installs to `.agents/skills/`. The global Antigravity path targets `~/.gemini/antigravity/skills/`. The global Cursor variant uses a `cursor-global` target.

Six assistant directories from one source tree is the whole portability claim, and it is a claim about file format rather than about an API. Nothing here needs a WordPress-side integration, because a skill is just Markdown and scripts that the assistant already knows how to read.

One precedence rule settles conflicts: when a skill exists in both scopes, the project-level version is used. That is the behaviour you want, since the committed copy is the one your team has reviewed.

What the README does not settle

A few questions remain open, and they are worth identifying because they are the ones that decide whether this helps your project or adds drift.

There is no stated version compatibility. Skills depend on WordPress version and Gutenberg feature maturity, and the release notes for Abilities API related work move fast, but the README does not say which WordPress version a given skill targets or how to tell whether a skill is stale for your install. The `eval/` directory in the tree suggests some answer exists; the README does not describe it.

There is no per-skill version or change log. The project describes itself as v1 with community contributions expected, and the repository has 57 open issues and 320 forks on 2,155 stars, so movement is real. Without a way to see which skill changed when, adopting skills project-scoped means you are committing content that a contributor may revise underneath you.

The license is reported as NOASSERTION in the repository metadata, and a LICENSE file exists in the tree. The README itself does not state a license, which is a small thing to confirm before you vendor these into a commercial codebase.

There is also no published measurement. The README says the skills were exercised against AI assistants and iterated on, which describes a loop without reporting its results. No accuracy figure, no before-and-after comparison, no list of which failure modes were fixed. The `eval/` directory is the place that evidence would live if it were published.

None of that undercuts the value. The instructions on installing, choosing scope and mapping to assistant directories are complete enough to act on today. But the difference between a skill that documents WordPress correctly and one that documents it correctly for your version of WordPress is the difference worth tracking, and that is a question the README leaves open.

Editorial conclusion

The interesting decision in this repository is not which skills exist but who the reader is. Documentation written for a person can be incomplete and still work, because a human fills gaps with knowledge they already have. A skill has no reader to fill the gaps, so every procedure has to be written down and every assumption has to be stated, which is why a skill folder carries references and scripts alongside its instructions and why the verification step is part of the procedure rather than an afterthought. Two things follow for anyone adopting it. Install project-scoped first, since the whole point is that the knowledge is committed and shared, and the README is explicit that a project-level copy wins over a global one. And read docs/ai-authorship.md before trusting a skill on a security-sensitive topic, because the README says the content was generated with a model and then reviewed and edited by contributors, which is a process description rather than a correctness guarantee. The two abilities skills are the most forward-looking part and the least documented. Proposing Abilities API registrations for a plugin's existing REST surface is a migration assist, and verifying registrations against declared annotations is the kind of check that usually arrives after someone has shipped the wrong permissions.

Frequently asked questions

Official sources

1. Issues
2. README
3. WordPress/agent-skills on GitHub