wp-abilities-api

wp-abilities-api 技能概覽

wp-abilities-api 是用來做什麼的

wp-abilities-api skill 幫你端到端處理 WordPress Abilities API：在 PHP 中註冊 abilities 與 categories，透過 REST 對外暴露，並從 @wordpress/abilities 消費它們。當你需要的是一套可靠的 wp-abilities-api skill 工作流程，而不是靠猜 hook 順序、REST 可見性或權限行為時，這個 skill 最有價值。

最適合的使用情境

這個 skill 適合後端開發任務，尤其是 ability 需要被 client 找得到、出現在 /wp-json/wp-abilities/v1/*，或是在 plugin、theme、mu-plugin，甚至 WordPress core checkout 中乾淨地註冊時。當你在修正「ability 沒有顯示出來」的問題、串接新的 server-side abilities，或是驗證 client 是否真的看得到 server 註冊的內容時，它特別合用。

最重要的是什麼

wp-abilities-api 最大的價值在於減少生命週期上的錯誤。這個 repo 強調註冊時機、source 掃描與 REST 暴露檢查，這比泛用的 prompt 寫法更重要，因為這個 API 很容易接錯，就算程式碼看起來完全沒問題也一樣。

如何使用 wp-abilities-api 技能

安裝並放到正確脈絡中

使用 npx skills add WordPress/agent-skills --skill wp-abilities-api 安裝。接著把 agent 指向 repo root，並告訴它這項工作是屬於 core、plugin、theme 還是 mu-plugin。做 wp-abilities-api install 判斷時，也要提供目標 WordPress 版本，因為 WP 6.9+ 的支援會影響這個 skill 能不能依賴 core 行為，或是必須走 plugin/package 路徑。

給 skill 正確的輸入

最好的 wp-abilities-api usage 不是從很大的目標開始，而是從具體任務開始。好的輸入會寫清楚 ability ID、category ID、想要的 label、callback 形狀，以及它是否一定要在 REST 中可見。例如：「在這個 plugin 裡加入 site/clear-cache ability，把它暴露到 REST，並確保 client 能列出它。」這比「設置 abilities」更好，因為它告訴 skill 應該產出什麼，以及要出現在哪裡。

先讀這些檔案

先看 SKILL.md，再檢查 references/php-registration.md 和 references/rest-api.md。這兩個檔案會帶出最關鍵的決策資訊：category 必須先於 ability 註冊、需要哪些 hooks，以及你應該驗證哪些 REST routes。若你要判斷現有 codebase 是否適用 wp-abilities-api guide，先搜尋 wp_register_ability(、wp_register_ability_category(、wp_abilities_api_init、wp_abilities_api_categories_init、wp-abilities/v1 和 @wordpress/abilities。

採用能避免「看似成功」的工作流程

實際可用的 wp-abilities-api workflow 是：先確認版本支援，找出既有註冊，先加 categories 再加 abilities，最後驗證 REST 暴露與 client 可見性。如果你在乎輸出品質，請 agent 交代它改了哪些確切 file path、每個註冊用了哪個 hook，以及它如何確認 ability 出現在 wp-abilities/v1/abilities 或 wp-abilities/v1/categories。

wp-abilities-api 技能 FAQ

wp-abilities-api 只適合後端開發嗎？

不完全是，但它最強的確是後端開發。wp-abilities-api for Backend Development 這個 use case 最能發揮它的價值：PHP 註冊、生命週期 hooks、REST 暴露，以及 capability 風格的檢查。如果你只是需要一次性的 UI prompt 或一段靜態 code snippet，通用 prompt 可能就夠了。

這跟自己寫 prompt 有什麼不同？

通用 prompt 可以描述目標，但 wp-abilities-api 提供的是一套聚焦在 WordPress 特定限制上的工作流程：hook 時機、REST 可見性、版本相容性，以及在新增之前先檢查既有註冊的必要性。這能減少反覆試錯，尤其是當 ability 已經存在於 code 裡，卻沒有出現在 REST 時。

初學者需要懂 WordPress internals 嗎？

有基本熟悉度會比較好，但只要你能找到 repo root，知道 plugin 或 theme code 放在哪裡，這個 skill 仍然能用。初學者最常踩的坑，是跳過必要輸入：WordPress 版本、專案類型，以及變更應該放在哪裡。如果缺少這些資訊，agent 可能會選錯註冊路徑。

什麼情況下不該用這個 skill？

如果你的任務跟 WordPress abilities 無關、專案低於 WP 6.9 且你無法加入所需的 package/plugin 路徑，或者你不需要 client 可見的 ability 註冊，就不要用 wp-abilities-api。在這些情況下，這個 skill 只會增加流程負擔，回報卻不夠。

如何改進 wp-abilities-api 技能

先給出精確的註冊目標

最好的結果來自一開始就講清楚 ability ID、category 與預期曝光方式。不要只說「加一個 admin ability」，而是說「把 acme/reindex-search 註冊到 acme-tools，在 REST 中暴露，並讓 JS clients 可用」。這會給 wp-abilities-api skill 足夠的結構，避免輸出含糊或對不上需求。

加上會改變實作方式的限制

請提及 WordPress 版本、這是 core 還是 plugin/theme，以及是否有 WP-CLI。這些細節會影響安裝路徑、hook 用法和驗證步驟。如果你省略它們，agent 可能會產出看起來對、實際卻無法在你的環境運作的 code。

要求驗證，不只是產碼

最常見的失敗模式包括 hook 順序錯誤、缺少 meta.show_in_rest，以及沒檢查 REST route 就假設 ability 會出現。請 agent 驗證 wp-abilities/v1/abilities，並說明為什麼某個註冊應該放在 wp_abilities_api_categories_init 或 wp_abilities_api_init。這樣才能把 wp-abilities-api guide 變成可檢查的工作流程。

根據 repo 證據迭代

如果第一次結果不完整，請把現有的確切檔案指給 agent，並要求它對齊既有實作，而不是從頭重寫。例如：「沿用 includes/abilities.php 裡既有的註冊模式，保持 category 命名一致，只有在必要時才改 REST visibility flag。」這是提升 wp-abilities-api usage、同時避免和 codebase 漸行漸遠的最快方式。