Teach AI coding assistants how to build WordPress the right way.
Agent Skills are portable bundles of instructions, checklists, and scripts that help AI assistants (Claude, Copilot, Codex, Cursor, etc.) understand WordPress development patterns, avoid common mistakes, and follow best practices.
AI Authorship Disclosure: These skills were generated using GPT-5.2 Codex (High Reasoning) from official Gutenberg and WordPress documentation, then reviewed and edited by WordPress contributors. We tested skills with AI assistants and iterated based on results. This is v1, and skills will improve as the community uses them and contributes fixes. See docs/ai-authorship.md for details. (WordPress AI Guidelines)
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, causing "Invalid block" errors
- 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.
| Skill | What it teaches |
|---|---|
| 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-patterns | Block patterns: registration, markup, design tokens, accessibility, and i18n |
| wp-plugin-development | Plugin architecture, hooks, settings API, security |
| wp-rest-api | REST API routes/endpoints, schema, auth, and 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 their declared annotations |
| wp-ai-client | Build AI features on WP 7.0+ using wp_ai_client_prompt() and the in-core AI Client |
| wp-ai-connectors | Register a new AI provider with the WP 7.0+ Connectors API (Settings → Connectors) |
| wp-ai-plugin | Extend the canonical AI plugin (WordPress/ai) with Experiments, paired Abilities, and Guidelines |
| 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 (config, baselines, WP-specific typing) |
| wp-playground | WordPress Playground for instant local environments |
| wpds | WordPress Design System |
| wp-plugin-directory-guidelines | WordPress Plugin Directory Guidelines |
| blueprint | WordPress Playground Blueprints for declarative Playground environment setup |
Each skill is a self-contained folder with instructions, references, and optional scripts:
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
When you ask your AI assistant to work on WordPress code, it reads these skills and follows the documented procedures rather than guessing.
Skills can be installed in two scopes:
Global — installed in your home directory (e.g. ~/.claude/skills/, ~/.cursor/skills/).
- Available across all your projects automatically.
- Best for individual developers who want WordPress knowledge in every repo.
Project — installed inside a repository (e.g. .claude/skills/, .github/skills/, .cursor/skills/).
- Available only within that specific project.
- Can be committed to version control so the entire team benefits.
You can use both at the same time. When a skill exists in both scopes, the project-level version is used.
Claude Code can add this whole repository as a plugin marketplace — no cloning, no build step:
/plugin marketplace add henryperkins/agent-skills
/plugin install wordpress-skills@wordpress-skills
That's it. All skills are installed and namespaced as /wordpress-skills:<skill-name> (e.g. /wordpress-skills:wp-block-development), and Claude automatically invokes them when relevant — same as any other skill. Keep them up to date with /plugin marketplace update wordpress-skills, or remove with /plugin uninstall wordpress-skills@wordpress-skills.
Prefer the repo's canonical location? Once merged upstream, the same commands work with WordPress/agent-skills instead.
The fastest way to install a skill is with a single command:
npx skills add WordPress/agent-skills --skill wp-plugin-developmentTo see all available skills:
npx skills add WordPress/agent-skills --listTo install multiple skills at once:
npx skills add WordPress/agent-skills --skill wp-plugin-development wp-abilities-api wp-playgroundnpx skills add asks to choose the skill project-scoped, selecting the local scope on which the skills are installed in the local project; it can be stored at the repository (e.g. .claude/skills/, .cursor/skills/) — so the skills can be committed to version control and shared with your team.
Installing globally makes the skill available to your user (across all your projects). Adding the -g / --global flag, it will install your skill with global scope:
npx skills add WordPress/agent-skills --skill wp-plugin-development --globalPrefer the plugin marketplace method above for a zero-clone install. If you'd rather vendor plain, unnamespaced skills (invoked as /wp-block-development instead of /wordpress-skills:wp-block-development), install them as files instead:
# Clone agent-skills
git clone https://github.com/WordPress/agent-skills.git
cd agent-skills
# Build the distribution
node shared/scripts/skillpack-build.mjs --clean
# Install all skills globally (available across all projects)
node shared/scripts/skillpack-install.mjs --global
# Or install specific skills only
node shared/scripts/skillpack-install.mjs --global --skills=wp-playground,wp-block-developmentThis installs skills to ~/.claude/skills/ where Claude Code will automatically discover them.
# Clone agent-skills
git clone https://github.com/WordPress/agent-skills.git
cd agent-skills
# Build the distribution
node shared/scripts/skillpack-build.mjs --clean
# Install into your WordPress project
node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=codex,vscode,claude,cursorThis copies skills into:
.codex/skills/for OpenAI Codex.github/skills/for VS Code / GitHub Copilot.claude/skills/for Claude Code (project-level).cursor/skills/for Cursor (project-level)
Antigravity is opt-in when building skillpacks because it uses the shared .agents/skills/ convention:
node shared/scripts/skillpack-build.mjs --clean --targets=antigravity
node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=antigravityThis copies skills into .agents/skills/ for Google Antigravity.
node shared/scripts/skillpack-install.mjs --targets=cursor-globalThis installs skills to ~/.cursor/skills/ where Cursor will discover them.
node shared/scripts/skillpack-build.mjs --clean --targets=antigravity
node shared/scripts/skillpack-install.mjs --targets=antigravity-globalThis installs skills to ~/.gemini/antigravity/skills/.
# List available skills
node shared/scripts/skillpack-install.mjs --list
# Dry run (preview without installing)
node shared/scripts/skillpack-install.mjs --global --dry-run
# Install specific skills to a project (e.g. Claude + Cursor)
node shared/scripts/skillpack-install.mjs --dest=../my-repo --targets=claude,cursor --skills=wp-wpcli-and-opsCopy any skill folder from skills/ into your project's instructions directory for your AI assistant.
- WordPress 6.9+ (PHP 7.2.24+) by default
- WordPress 7.0+ (PHP 7.4+) for skills covering 7.0-only features (AI Client, Connectors API, client-side Abilities API) — see
docs/compatibility-policy.md - Works with any AI assistant that supports project-level instructions
We welcome contributions! This project is a great way to share your WordPress expertise—you don't need to be a coding wizard. Most skills are written in Markdown, focusing on clear procedures and best practices.
See CONTRIBUTING.md for details on how to get started.
Quick commands:
# Scaffold a new skill
node shared/scripts/scaffold-skill.mjs <skill-name> "<description>"
# Validate skills
node eval/harness/run.mjs- Authoring Guide - How to create and improve skills
- Principles - Design philosophy
- Packaging - Build and distribution
- Compatibility Policy - Version targeting
GPL-2.0-or-later