WordPress/agent-skills: The Official WordPress Skill Pack for AI Coding Assistants

WordPress has conventions that change between major versions and block-era APIs that most assistants still get wrong. WordPress/agent-skills ships WordPress-contributor-maintained guidance so AI coding assistants default to the modern patterns.

Why This Skill Matters

The README opens with a blunt problem statement: "AI coding assistants are powerful, but they often generate outdated WordPress patterns (pre-Gutenberg, pre-block themes), miss critical security considerations in plugin development, skip proper block deprecations, and ignore existing tooling in your repo." Agent Skills solve this by giving AI assistants "expert-level WordPress knowledge in a format they can actually use".

The repository has 2k stars on GitHub. License is GPL-2.0-or-later (the README's License section states "GPL-2.0-or-later"; this is the WordPress project's standard copyleft license — not MIT). The project's default branch is trunk, not main.

The AI Authorship Disclosure at the top of the README is worth reading in full: "These skills were generated using GPT-5.2 Codex (High Reasoning) from official Gutenberg and WordPress documentation, then reviewed and edited by WordPress contributors." v1 will improve as the community uses them and contributes fixes.

The catalog has 17 skills (per the README's "Available Skills" table):

• wordpress-router — classifies WordPress repos and routes to the right workflow
• wp-project-triage — detects project type, tooling, and versions automatically
• wp-block-development — Gutenberg blocks: block.json, attributes, rendering, deprecations
• wp-block-themes — block themes: theme.json, templates, patterns, style variations
• wp-plugin-development — plugin architecture, hooks, settings API, security
• wp-rest-api — REST API routes/endpoints, schema, auth, response shaping
• wp-interactivity-api — frontend interactivity with data-wp-* directives and stores
• wp-abilities-api — capability-based permissions and REST API authentication
• wp-abilities-audit — audit a plugin's REST surface and propose Abilities API registrations
• wp-abilities-verify — verify a plugin's Abilities API registrations against declared annotations
• wp-wpcli-and-ops — WP-CLI commands, automation, multisite, search-replace
• wp-performance — profiling, caching, database optimization, Server-Timing
• wp-phpstan — PHPStan static analysis for WordPress projects
• wp-playground — WordPress Playground routing, CLI runs, browser previews, snapshots
• wpds — WordPress Design System
• wp-plugin-directory-guidelines — WordPress Plugin Directory Guidelines
• blueprint — WordPress Playground Blueprints for declarative environment setup

Each skill is a self-contained folder with instructions, references, and optional scripts (SKILL.md, references/, scripts/). Compatibility targets WordPress 7.0+ (PHP 7.4.0+), per the README's Compatibility section.

Installation

The fastest path is the npx skills CLI:

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

To see all 17 skills:

npx skills add WordPress/agent-skills --list

To install multiple at once:

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

The README distinguishes global install (~/.claude/skills/, ~/.cursor/skills/) from project install (.claude/skills/, .github/skills/, .cursor/skills/). Adding -g or --global installs globally; without the flag, the install is project-scoped.

For Claude Code global install, the README documents a build + install pair:

git clone https://github.com/WordPress/agent-skills.git
cd agent-skills
node shared/scripts/skillpack-build.mjs --clean
node shared/scripts/skillpack-install.mjs --global

The install path includes targets for Codex (.codex/skills/), VS Code / Copilot (.github/skills/), Claude Code (.claude/skills/), Cursor (.cursor/skills/), and Antigravity (global ~/.gemini/antigravity/skills/; opt-in project-level .agents/skills/).

Real Workflow: Build a Plugin the Modern Way

You are starting a new WordPress plugin and want it to follow current block-era patterns, not pre-Gutenberg boilerplate.

Step 1. Install the three relevant skills:

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

Step 2. Have the agent consult wp-plugin-development first — it covers plugin architecture, hooks, the settings API, and security. The README explicitly calls security out as the area AI assistants "miss critical" considerations on.

Step 3. If the plugin exposes REST routes, ask the agent to also load wp-rest-api for the right shape, then wp-abilities-audit to propose Abilities API registrations for those routes. Run wp-abilities-verify to confirm the registrations match declared annotations.

Step 4. Before merging, ask the agent to consult wp-phpstan for static analysis with WordPress-aware typing and wp-plugin-directory-guidelines if you intend to submit the plugin to the WordPress Plugin Directory.

Step 5. Spin up a Playground instance to test the plugin in-browser without a local install — the wp-playground skill covers routing, CLI runs, browser previews, and snapshots; blueprint handles declarative environment setup.

Real Workflow: Migrate a Pre-Gutenberg Theme to Block Theme

You inherited a classic theme and want to move it to theme.json without breaking existing content.

Step 1. Install wp-block-themes and wp-project-triage:

npx skills add WordPress/agent-skills --skill wp-block-themes wp-project-triage

Step 2. Run wp-project-triage first — it detects project type, tooling, and versions so the agent does not assume the wrong baseline.

Step 3. The wp-block-themes skill covers theme.json, templates, patterns, and style variations. Ask the agent to draft the theme.json based on the existing classic settings, then generate block templates for each existing page template.

Step 4. For any deprecated blocks in the existing content, lean on wp-block-development — its references include deprecations.md covering proper block deprecation so the migrated theme does not show "Invalid block" errors in the editor.

Step 5. Run wp-performance to check that the new theme.json does not regress render times, especially under Server-Timing.

Tips

• Read the AI Authorship Disclosure before adopting — this is v1 and the README explicitly invites fixes.
• Install wp-project-triage first on any unfamiliar repo; without it, the agent guesses at the project's tooling and version.
• For REST surfaces, the wp-abilities-audit + wp-abilities-verify pair replaces ad-hoc route registration with capability-bound annotations.
• Block deprecations matter — wp-block-development/references/deprecations.md is the file to keep open during a theme or block rewrite.
• The README's Compatibility section names WordPress 7.0+ (PHP 7.4.0+); do not assume older patterns apply if your target is older.

When Not to Use This

If you target a WordPress version older than 7.0 or PHP older than 7.4.0, the README's Compatibility clause does not cover your deployment target. If you need a hand-curated, MIT-licensed skill pack, this repo is GPL-2.0-or-later — different copyleft terms. If your repo is not a WordPress project at all, none of these skills apply; pick a domain-specific skill from elsewhere.

See the leaderboard for more skills.