Loading plugin...

wordpress-agent-skills · Flowy

README

Agent Skills for WordPress

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)

Why Agent Skills?

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.

Available Skills

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-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-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

How It Works

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.

Global vs. Project Scope

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.

Quick Start

The fastest way to install a skill is with a single command:

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

To see all available skills:

npx skills add WordPress/agent-skills --list

To install multiple skills at once:

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

Choosing a scope

npx 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 --global

Install globally for Claude Code

# 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-development

This installs skills to ~/.claude/skills/ where Claude Code will automatically discover them.

Install into your repo

# 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,cursor

This 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 for project-level installs. To also copy skills into .agents/skills/, include antigravity when building and installing:

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

Install globally for Cursor

node shared/scripts/skillpack-install.mjs --targets=cursor-global

This installs skills to ~/.cursor/skills/ where Cursor will discover them.

Install globally for Antigravity

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

This installs skills to ~/.gemini/antigravity/skills/ where Antigravity will discover them.

Available options

# 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-ops

Manual installation

Copy any skill folder from skills/ into your project's instructions directory for your AI assistant.

Compatibility

WordPress 7.0+ (PHP 7.4.0+)
Works with any AI assistant that supports project-level instructions

Contributing

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

Documentation

Authoring Guide - How to create and improve skills
Principles - Design philosophy
Packaging - Build and distribution
Compatibility Policy - Version targeting

License

GPL-2.0-or-later

File tree

171

WordPress/agent-skillsView on GitHub ↗

.github/
  state/
    last-sync.json
  workflows/
    ai-skill-maintenance.yml
    ci.yml
    props-bot.yml
    upstream-sync.yml
.gitignore
CONTRIBUTING.md
docs/
  ai-authorship.md
  authoring-guide.md
  compatibility-policy.md
  packaging.md
  principles.md
  skill-set-v1.md
  upstream-sync.md
eval/
  harness/
    run.mjs
  scenarios/
    abilities-register-and-expose.json
    block-add-attribute-and-migrate.json
    block-convert-to-dynamic-render-php.json
    block-create-interactive-inner-blocks.json
    interactivity-route-and-debug.json
    performance-autoload-options-bloat.json
    performance-profile-slow-endpoint.json
    phpstan-fix-third-party-class.json
    plugin-add-settings-page.json
    plugin-add-uninstall-cleanup.json
    plugin-directory-license-review.json
    plugin-directory-name-trademark.json
    plugin-security-nonce-and-capability.json
    README.md
    rest-api-add-custom-endpoint.json
    router-route-theme-json.json
    skillpack-build-and-install.json
    theme-add-pattern-file.json
    theme-add-style-variation.json
    theme-json-add-typography-preset.json
    triage-output-contract.json
    upstream-sync-indices.json
    wp-abilities-audit.json
    wp-abilities-verify.json
    wp-patterns-album-poster-split.json
    wp-patterns-bold-duotone-cover-cta.json
    wp-patterns-create-hero-pattern.json
    wp-patterns-forest-editorial-cover.json
    wp-patterns-header-hero-image.json
    wp-patterns-image-text-color-field.json
    wp-patterns-large-cover-exhibition.json
    wp-patterns-media-text-case-study.json
    wp-patterns-offset-wordmark-hero.json
    wp-patterns-query-date-title-index.json
    wp-patterns-repeating-display-text-cover.json
    wp-patterns-two-tone-centered-image.json
    wpcli-multisite-targeting.json
    wpcli-safe-search-replace.json
LICENSE
README.md
shared/
  references/
    .gitkeep
    gutenberg-releases.json
    wordpress-core-versions.json
    wp-gutenberg-version-map.json
  scripts/
    ai-generate-updates.mjs
    scaffold-skill.mjs
    skillpack-build.mjs
    skillpack-install.mjs
    update-upstream-indices.mjs
skills/
  blueprint/
    SKILL.md
  wordpress-router/
    references/
      decision-tree.md
    SKILL.md
  wp-abilities-api/
    references/
      delegate-helper-pattern.md
      domain-vs-projection.md
      error-code-vocabulary.md
      grouping-heuristic.md
      input-schema-gotchas.md
      php-registration.md
      plugin-family-patterns.md
      rest-api.md
      shared-core-service.md
    SKILL.md
  wp-abilities-audit/
    references/
      audit-schema.md
      capability-gate-tracing.md
      controller-enumeration.md
    SKILL.md
  wp-abilities-verify/
    references/
      annotation-correctness.md
      audit-schema-validation.md
      permission-roundtrip.md
      runtime-harness.md
      schema-lints.md
      static-enumeration.md
    SKILL.md
  wp-block-development/
    references/
      attributes-and-serialization.md
      block-json.md
      creating-new-blocks.md
      debugging.md
      deprecations.md
      dynamic-rendering.md
      inner-blocks.md
      registration.md
      supports-and-wrappers.md
      tooling-and-testing.md
    scripts/
      list_blocks.mjs
    SKILL.md
  wp-block-themes/
    references/
      creating-new-block-theme.md
      debugging.md
      patterns.md
      style-variations.md
      templates-and-parts.md
      theme-json.md
    scripts/
      detect_block_themes.mjs
    SKILL.md
  wp-interactivity-api/
    references/
      debugging.md
      directives-quickref.md
      server-side-rendering.md
    SKILL.md
  wp-patterns/
    references/
      anti-patterns.md
      block-markup-reference.md
      design-with-tokens.md
      pattern-categories-and-types.md
      pattern-registration.md
    SKILL.md
  wp-performance/
    references/
      autoload-options.md
      cron.md
      database.md
      http-api.md
      measurement.md
      object-cache.md
      query-monitor-headless.md
      server-timing.md
      wp-cli-doctor.md
      wp-cli-profile.md
    scripts/
      perf_inspect.mjs
    SKILL.md
  wp-phpstan/
    references/
      configuration.md
      third-party-classes.md
      wordpress-annotations.md
    scripts/
      phpstan_inspect.mjs
    SKILL.md
  wp-playground/
    references/
      blueprints.md
      cli-commands.md
      debugging.md
    SKILL.md
  wp-plugin-development/
    references/
      data-and-cron.md
      debugging.md
      lifecycle.md
      security.md
      settings-api.md
      structure.md
    scripts/
      detect_plugins.mjs
    SKILL.md
  wp-plugin-directory-guidelines/
    references/
      gpl-compliance.md
      guideline-review-checklist.md
      naming-rules.md
    SKILL.md
  wp-project-triage/
    references/
      triage.schema.json
    scripts/
      detect_wp_project.mjs
    SKILL.md
  wp-rest-api/
    references/
      authentication.md
      custom-content-types.md
      discovery-and-params.md
      responses-and-fields.md
      routes-and-endpoints.md
      schema.md
    SKILL.md
  wp-wpcli-and-ops/
    references/
      automation.md
      cron-and-cache.md
      debugging.md
      multisite.md
      packages-and-updates.md
      safety.md
      search-replace.md
    scripts/
      wpcli_inspect.mjs
    SKILL.md
  wpds/
    SKILL.md