前言¶
在 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
