前言¶
在 WordPress 里做插件，常见难点不是「能不能写出一个功能」，而是生命周期、后台设置和安全细节容易漏：激活钩子注册位置不对、Settings API 没接上 sanitize、卸载时数据没清干净。官方 Plugin Handbook 和安全文档很全，但 Agent 在改代码时往往要跨多份文档自己拼顺序。
下面介绍 WordPress 官方 Agent Skills 仓库里的 wp-plugin-development：把插件架构、Hooks、Settings API、数据与定时任务、安全基线以及发布打包，整理成可执行的步骤与参考文档索引，并与同仓库里的区块开发类 Skill 形成互补——一个覆盖传统插件主战场，一个覆盖区块侧开发。
这是什么¶
wp-plugin-development 是 WordPress/agent-skills 下的一个 Skill，面向「从初始架构到发布打包」的插件开发工作流。
Skill 元数据中的说明概括为：在开发 WordPress 插件时使用，涵盖架构与 Hooks、激活/停用/卸载、管理端 UI 与 Settings API、数据存储、定时任务、安全（nonces、capabilities、清洗与转义），以及发布打包。
兼容性与环境（以 SKILL front matter 为准）：
- 目标 WordPress 7.0+，PHP 7.4.0+
- 基于文件系统的 Agent，需要 bash + node
- 部分流程需要 WP-CLI
核心功能¶
以下能力均来自官方 SKILL 正文，按推荐执行顺序组织。
项目分诊与插件入口定位¶
- 运行项目分诊脚本：
node skills/wp-project-triage/scripts/detect_wp_project.mjs
- 扫描插件头信息（确定性扫描）：
node skills/wp-plugin-development/scripts/detect_plugins.mjs
若仓库是整个站点，应先选定 wp-content/plugins/ 或 mu-plugins/ 下的具体插件再改代码。
可预期的插件架构¶
- 单一引导文件（带插件头的主文件）
- 避免在文件加载时产生重副作用；通过 Hooks 加载
- 优先用独立的 loader/类注册 Hooks
- 管理端代码放在
is_admin()或管理端 Hooks 之后，减轻前台开销
详细约定见 Skill 内 references/structure.md。
Hooks 与生命周期¶
激活相关 Hooks 易出错，官方给出的约束包括：
- 在顶层注册激活/停用 Hook，不要嵌在其他 Hook 里
- 仅在需要时 flush 重写规则，且在注册 CPT/规则之后
- 卸载路径要明确且安全：
uninstall.php或register_uninstall_hook
见 references/lifecycle.md。
Settings API 与管理端 UI¶
优先用 Settings API 管理选项：
register_setting()、add_settings_section()、add_settings_field()- 通过
sanitize_callback做清洗
见 references/settings-api.md。
安全基线¶
发布前应默认检查：
- 输入尽早校验/清洗，输出在展示前转义
- Nonce 防 CSRF，同时用 capability 做授权
- 不直接信任
$_POST/$_GET；使用wp_unslash()并只取明确键名 - SQL 使用
$wpdb->prepare()，避免字符串拼接 SQL
见 references/security.md。
数据存储、Cron 与迁移（按需）¶
- 小配置优先用 options；确有必要再用自定义表
- Cron 任务应幂等，并提供手动执行路径（WP-CLI 或管理端）
- 表结构变更要有升级例程并记录 schema 版本
见 references/data-and-cron.md。
验证与常见故障¶
验证清单：插件激活无 fatal/notice；设置可读写且 capability + nonce 生效；卸载只删除预期数据；若仓库有 PHPUnit/PHPCS 或前端构建，应跑通。
典型故障（节选）：
- 激活 Hook 不触发：注册不在主文件作用域、主文件路径错误、或网络激活等
- 设置不保存：未
register_setting、option group 错误、缺少 capability、nonce 失败 - 安全回退：有 nonce 无 capability，或输入已清洗但输出未转义
见 references/debugging.md。更深细节应查 Plugin Handbook 与安全指南，而不是自造模式。
安装与启用¶
officialskills.sh 列出的安装方式为：
npx skills add https://github.com/WordPress/agent-skills --skill wp-plugin-development
也可将 Skill 目录链接交给支持 Agent Skills 的编码助手安装：
https://github.com/WordPress/agent-skills/tree/trunk/skills/wp-plugin-development
资料中未区分 Cursor、Codex CLI、Claude Code 的安装差异；以上述 npx skills add 与仓库路径为准。
典型用法¶
开始插件相关任务前，Agent 应拿到：
- 仓库根目录与目标插件路径（若已知，主插件文件路径）
- 运行环境：单站点还是多站点；是否适用 WP.com 约定
- 目标 WordPress 与 PHP 版本（影响 API 与
$wpdb->prepare()占位符等行为）
适用工作示例（官方 When to use）：
- 新建或重构插件结构（bootstrap、includes、命名空间/类）
- 添加 actions/filters
- 激活/停用/卸载行为与迁移
- 设置页、选项、管理端 UI（Settings API）
- 安全修复（nonces、capabilities、清洗/转义、SQL 安全）
- 发布打包（构建产物、readme、资源）
适用场景与注意¶
适合：需要在 Agent 辅助下系统完成插件全生命周期开发的 WordPress 开发者；与区块开发 Skill 搭配时，可分别覆盖「经典插件」与「区块」两条主线。
注意：
- 依赖 node 脚本做分诊与插件检测，环境需具备 bash 与 node
- 部分流程依赖 WP-CLI，本地或 CI 需预先安装
- 目标版本为 WordPress 7.0+ / PHP 7.4+，旧环境 API 与占位符行为可能不同
结尾¶
wp-plugin-development 把插件开发的推荐顺序、参考文档入口和常见失败模式写进一份 Skill，减少在 Handbook 与安全文档之间手工对照的成本。官方目录：
https://github.com/WordPress/agent-skills/tree/trunk/skills/wp-plugin-development
