wp-rest-api

wp-rest-api 技能總覽

wp-rest-api 的用途

wp-rest-api 技能能幫你更少憑空猜測地處理 WordPress REST 端點：建立 routes、對外暴露內容類型、驗證參數、設計回應格式，以及排查驗證或權限失敗。當你需要的是一份可直接落地到真實 plugin、theme 或 mu-plugin 的實用 wp-rest-api 指南，而不只是泛用提示詞時，這個技能特別有用。

誰適合使用

如果你正在新增或除錯 register_rest_route()、WP_REST_Controller、register_rest_field、register_meta、show_in_rest，或 REST schema / validation 邏輯，就適合使用 wp-rest-api 技能。對需要快速判斷 repo 是否支援你的 endpoint 工作、以及該怎麼安全處理的開發者來說，它很適合拿來做安裝決策。

它有什麼不同

這個技能聚焦在 WordPress 特有、也最常卡住採用的限制：permission_callback、nonce 或 application password 驗證、route 命名空間、context=edit、_fields，以及以 schema 驅動的驗證。wp-rest-api 的主要價值，是在你開始寫 code 之前先把你導向正確的 REST 模式，這能減少權限壞掉、client regression 與不合法的回應格式。

如何使用 wp-rest-api 技能

安裝並確認範圍

使用 npx skills add WordPress/agent-skills --skill wp-rest-api 安裝 wp-rest-api 技能。開始修改前，先確認你在正確的 repo root，並找出實際的 plugin/theme entrypoint。如果專案是完整站台 codebase，請先縮小到擁有該 endpoint 的單一元件。

先準備最少但足夠的輸入

要讓 wp-rest-api install 的結果更好，請提供：目標 namespace 與 version、route path、預期 HTTP method、auth 模式，以及 WordPress 最低版本。弱一點的需求是「加一個 endpoint」。更強的需求會像是：「為已驗證的 editors 新增 my-plugin/v1/orders，只回傳 order ID、status 和 total，驗證 page 與 per_page，並支援 ?_fields= 以提升 client 效能。」

先讀對的檔案

先從 SKILL.md 開始，再查看 references/routes-and-endpoints.md、references/authentication.md、references/schema.md、references/responses-and-fields.md、references/discovery-and-params.md，以及 references/custom-content-types.md。這些檔案會告訴你這個技能預期 routes、permissions、schema 和內容曝光要怎麼接起來；比起盲目掃過整個 repo，這樣更有用。

依照實務流程走

先用這個技能盤點既有 REST 用法，再決定實作路徑：custom route、controller class，或把既有 type 對外暴露。提示詞要圍繞預期的 resource 形狀，而不只是 endpoint 名稱。例如，請一併說明回應是否公開或僅限 edit、是否要重用 core fields，以及資料來源是 post meta、CPT，還是計算邏輯。這樣模型才有足夠脈絡產生可用的 wp-rest-api usage 結果。

wp-rest-api 技能 FAQ

這只適用於自訂 routes 嗎？

不是。wp-rest-api 技能也很適合用於透過 show_in_rest 對外暴露 CPT 和 taxonomy、加入 custom fields 或 meta，以及調整既有 endpoint 的回應行為。如果你只需要一次性的 fetch 範例，普通提示詞可能就夠了；但如果你需要 route 設計或相容性檢查，這個技能會更合適。

什麼情況下不該用 wp-rest-api？

如果你的任務跟 WordPress REST 內部機制無關，或你是在只消耗既有穩定 API 的 client app 裡工作，就可以跳過它。當 server code 無法修改、你只需要文件或 request 範例時，它也不是好選擇。

對初學者友善嗎？

算友善，只要你能改 WordPress PHP 檔案，也能清楚描述想要的 resource。初學者最大的風險是 auth 與 permissions 寫得不夠精確，結果路由看起來能用，實際上對未登入使用者、編輯者或外部 client 卻失敗。

它跟一般提示詞比起來如何？

一般提示詞也許能給你 code，但 wp-rest-api 更適合你需要 WordPress 專屬保護措施時：必填的 permission_callback、schema 驗證、回應塑形，以及 route discovery。當你在意的是可靠性，而不只是語法時，這個技能在安裝決策上更有價值。

如何改進 wp-rest-api 技能

提供 resource 形狀，不只是目標

最有價值的改進，是明確說出 endpoint 應該回傳什麼、誰可以呼叫它。請註明 object type、fields、寫入權限，以及任何特殊 filters。範例：「回傳已發佈的 products，包含 id、name、price 和 stock_status；只允許已驗證的 managers 更新 stock_status。」這會讓 wp-rest-api 技能精準很多。

先提供失敗脈絡

如果你是在除錯，請把實際症狀直接寫出來：401、403、404、缺少 nonce、namespace 錯誤，或 schema 不合法。也要說明 route 是公開、使用 cookie-auth，還是採用 application passwords。這能幫模型分辨是 auth 失敗、route registration 問題，還是資料形狀問題。

在提示詞裡用 repo 細節

把 repo 裡已存在的相關檔案、controller classes 或 post types 名稱寫出來。如果 code 已經有 show_in_rest、rest_base 或 meta registration，也要一併說明。最好的 wp-rest-api guide 輸出，通常來自以既有架構為錨點的提示詞，而不是要求從零重新實作。

從驗證一路迭代到打磨

第一次輸出後，請一次只要求一項小幅改善：更嚴格的 schema、更好的 permission checks、用 _fields 縮減回應，或讓 route 相容非漂亮網址 permalinks。如果輸出品質還是不對，再把 prompt 收緊，加入精確 request 與預期 JSON 形狀；這通常比要求一個「更好」的 endpoint 更有效。