WordPress/agent-skills：官方维护的 WordPress AI 编程助手 skill 合集

WordPress 有一些只在主版本之间会变的约定，而大多数 AI 助手在 block 时代的 API 上还是会写错。WordPress/agent-skills 提供由 WordPress 贡献者维护的指南，让 AI 编程助手默认走现代写法。

为什么这个 Skill 重要

README 开头直陈痛点："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 的解法是：把"专家级的 WordPress 知识"装进 AI 助手真的能用得上的格式。

仓库在 GitHub 上有 2k star。许可证是 GPL-2.0-or-later（README 的 License 小节写"GPL-2.0-or-later"——这是 WordPress 项目的标准 copyleft，不是 MIT）。默认分支是 trunk，不是 main。

README 顶部的 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." v1 会在社区使用并贡献修复的过程中持续完善。

README 的 "Available Skills" 表里列了 17 个 skill：

• wordpress-router——给 WordPress 仓库分类，路由到对应的工作流
• wp-project-triage——自动检测项目类型、工具链与版本
• wp-block-development——Gutenberg block：block.json、attributes、渲染、deprecations
• wp-block-themes——block 主题：theme.json、模板、patterns、style variations
• wp-plugin-development——插件架构、hooks、Settings API、安全
• wp-rest-api——REST API routes/endpoints、schema、auth、response shaping
• wp-interactivity-api——用 data-wp-* 指令与 stores 做前端交互
• wp-abilities-api——基于能力（capability）的权限与 REST API 鉴权
• wp-abilities-audit——审计插件的 REST 表面积，提出 Abilities API 注册建议
• wp-abilities-verify——核对插件的 Abilities API 注册与声明的 annotation 一致
• wp-wpcli-and-ops——WP-CLI 命令、自动化、多站点、search-replace
• wp-performance——profiling、缓存、数据库优化、Server-Timing
• wp-phpstan——面向 WordPress 项目的 PHPStan 静态分析
• wp-playground——WordPress Playground 路由、CLI 运行、浏览器预览、快照
• wpds——WordPress 设计系统
• wp-plugin-directory-guidelines——WordPress 插件目录指南
• blueprint——WordPress Playground Blueprints，声明式环境配置

每个 skill 都是一个独立的目录，包含 instructions、references、可选的 scripts（SKILL.md、references/、scripts/）。Compatibility 一节里目标版本是 WordPress 7.0+（PHP 7.4.0+）。

安装

最快路径是 npx skills CLI：

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

看完整的 17 个 skill：

npx skills add WordPress/agent-skills --list

一次装多个：

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

README 把全局安装（~/.claude/skills/、~/.cursor/skills/）与项目级安装（.claude/skills/、.github/skills/、.cursor/skills/）区分开。加 -g 或 --global 是全局；不加就是项目级。

Claude Code 的全局安装需要先 build 再 install：

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

安装路径覆盖 Codex（.codex/skills/）、VS Code / Copilot（.github/skills/）、Claude Code（.claude/skills/）、Cursor（.cursor/skills/），以及 Antigravity（全局 ~/.gemini/antigravity/skills/；项目级 .agents/skills/ 需要显式 opt-in）。

实战：用现代写法做一个新插件

新启动一个 WordPress 插件，希望它走的是 block 时代的模式，而不是 pre-Gutenberg 的模板代码。

Step 1. 装三个相关 skill：

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

Step 2. 先让 agent 读 wp-plugin-development——它覆盖插件架构、hooks、Settings API 与安全。README 明确把"miss critical security considerations"列为 AI 助手最容易出问题的领域。

Step 3. 如果插件要暴露 REST route，让 agent 同时加载 wp-rest-api，拿到合适的 schema，再让 wp-abilities-audit 为这些 route 提出 Abilities API 注册建议。最后跑 wp-abilities-verify 核对注册与 annotation 一致。

Step 4. 合并前，让 agent 走一遍 wp-phpstan 做 WordPress 感知的静态类型检查；如果你打算把插件提交到 WordPress 插件目录，再加 wp-plugin-directory-guidelines。

Step 5. 启动 Playground 实例在浏览器里测插件，不必本地装——wp-playground skill 覆盖路由、CLI 运行、浏览器预览与快照；blueprint 处理声明式环境配置。

实战：把 pre-Gutenberg 主题迁到 block theme

接到了一个 classic 主题，要迁到 theme.json 又不破坏已有内容。

Step 1. 装 wp-block-themes 与 wp-project-triage：

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

Step 2. 先跑 wp-project-triage——它会检测项目类型、工具链与版本，避免 agent 假设错基线。

Step 3. wp-block-themes skill 覆盖 theme.json、模板、patterns 与 style variations。让 agent 先按现有 classic 的 settings 起草 theme.json，再为每个页面模板生成对应的 block 模板。

Step 4. 已有内容里若有 deprecated block，靠 wp-block-development——它的 references 里有 deprecations.md，讲清怎么正确做 block deprecation，迁移后的主题就不会在编辑器里冒"Invalid block"。

Step 5. 跑 wp-performance 检查新的 theme.json 没有让渲染时间退化，特别是在 Server-Timing 上。

技巧

• 采用前先读 AI Authorship Disclosure——这是 v1，README 显式邀请贡献修复。
• 不熟悉的仓库先装 wp-project-triage；不装的话 agent 会乱猜工具链和版本。
• 对 REST 表面积，wp-abilities-audit + wp-abilities-verify 这一对取代了临时起 route 的注册方式，换成带 capability 约束的 annotation。
• Block deprecations 一定要处理好——主题或 block 重写期间，把 wp-block-development/references/deprecations.md 一直开着。
• README 的 Compatibility 一节点明目标版本 WordPress 7.0+（PHP 7.4.0+）；如果你的部署目标更老，不要默认新模式适用。

何时不用这个 Skill

如果你的目标是 WordPress 7.0 以下或 PHP 7.4.0 以下，README 的 Compatibility 一节不覆盖你的部署目标。如果你需要 MIT 许可、且要手工策展的 skill 包，这个仓库是 GPL-2.0-or-later，copyleft 条款不同。如果你的仓库根本不是 WordPress 项目，这些 skill 一个都用不上，从别处挑一个领域内的 skill。

查看 排行榜 了解更多 skill。