wp-abilities-api

wp-abilities-api skill の概要

wp-abilities-api は何のためのものか

wp-abilities-api skill は、WordPress Abilities API を一通り扱うための skill です。PHP で ability と category を登録し、REST 経由で公開し、@wordpress/abilities から消費するところまでをカバーします。hook の順序、REST での可視性、権限の挙動を手探りで確かめるのではなく、信頼できる wp-abilities-api skill workflow が必要なときに最も役立ちます。

向いているユースケース

この skill は、client から発見できるようにしたい ability、/wp-json/wp-abilities/v1/* に表示したい ability、あるいは plugin / theme / mu-plugin / WordPress core checkout で整理して登録したい ability に向いた backend 開発タスクで使います。特に「ability が表示されない」問題の修正、新しい server-side ability の配線、server 側で登録した内容を client が本当に見えるかの検証に強い適性があります。

いちばん重要なポイント

wp-abilities-api の最大の価値は、ライフサイクル上のミスを減らせることです。repository では registration のタイミング、source のスキャン、REST 露出の確認が重視されています。コードは正しそうに見えても誤配線しやすい API なので、一般的な prompt の書き方よりもこちらのほうが重要です。

wp-abilities-api skill の使い方

インストールして文脈を伝える

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+ をサポートしているかどうかで、core の挙動に頼れるか、plugin/package の経路が必要かが変わるためです。

skill に正しい入力を与える

最も強い wp-abilities-api usage は、広い目的ではなく具体的なタスクから始まります。よい入力には、ability ID、category ID、望む label、callback の形、REST で見せる必要があるかどうかが含まれます。たとえば「この plugin に site/clear-cache ability を追加し、REST に公開し、client が一覧できるようにしてほしい」です。これなら、何をどこに出力すべきかが skill に伝わります。「abilities を設定して」だけでは、出力先も期待値も曖昧です。

まず読むべきファイル

最初に SKILL.md を読み、その次に references/php-registration.md と references/rest-api.md を確認します。この 2 つには、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 を検索してください。

偽の成功を防ぐ workflow を使う

実用的な wp-abilities-api workflow は、まず version support を確認し、既存 registration を見つけ、category を ability より先に追加し、そのあと REST 露出と client 可視性を検証する、という流れです。出力品質を重視するなら、変更した正確な file path、各 registration で使った hook、そして ability が wp-abilities/v1/abilities か wp-abilities/v1/categories に表示されることをどう確認したかまで、agent に含めさせてください。

wp-abilities-api skill の FAQ

wp-abilities-api は backend 開発専用ですか？

いいえ、ただし最も強いのは backend 開発です。wp-abilities-api for Backend Development のユースケースでは特に力を発揮します。PHP registration、lifecycle hooks、REST exposure、capability-style のチェックが中心になるからです。単発の UI prompt や静的な code snippet だけで足りるなら、汎用 prompt で十分なこともあります。

自分で prompt を書くのと何が違いますか？

汎用 prompt でも目的は説明できますが、wp-abilities-api は WordPress 固有の制約に合わせた集中 workflow を提供します。hook のタイミング、REST での可視性、version 互換性、そして新しい registration を足す前に既存の registration を確認する必要がある点まで含まれます。そのため、コード上は存在するのに REST に出てこない、という場面での試行錯誤を減らせます。

初心者にも WordPress internals の知識は必要ですか？

基本的な知識があると安心ですが、repository root を見分けられて、plugin や theme の code がどこにあるか分かるなら、skill 自体は使えます。初心者がつまずきやすいのは、必須入力を省くことです。WordPress の version、project type、変更を入れる場所を渡さないと、agent が間違った registration path を選ぶ可能性があります。

どんなときにこの skill を使うべきではありませんか？

WordPress abilities と無関係な作業なら、wp-abilities-api は使わないでください。また、project が WP 6.9 未満で必要な package/plugin path を追加できない場合、あるいは client から見える ability registration が不要な場合も不向きです。その場合は、手順のコストに対して見返りが十分ではありません。

wp-abilities-api skill の改善方法

正確な registration 対象を伝える

最良の結果を出すには、ability ID、category、意図する exposure を最初から名前で指定することです。「admin ability を追加して」ではなく、「acme/reindex-search を acme-tools の下に登録し、REST で公開し、JS client から使えるようにしてほしい」と伝えてください。そうすると、wp-abilities-api skill が曖昧な出力や食い違った出力を避けやすくなります。

実装を変える制約を含める

WordPress の version、core か plugin/theme か、WP-CLI が使えるかを必ず伝えてください。これらは install path、hook の使い方、検証手順に影響します。省略すると、見た目は正しくても環境で失敗する code が出てくることがあります。

コードだけでなく検証も依頼する

よくある失敗は、hook 順序の誤り、meta.show_in_rest の抜け、REST route を確認せずに ability が表示されると決めつけることです。wp-abilities/v1/abilities に対して検証し、なぜその registration が wp_abilities_api_categories_init または wp_abilities_api_init に属するのかを説明するよう agent に求めてください。そうすれば wp-abilities-api guide が、確認可能な workflow になります。

repository の証拠を起点に反復する

最初の出力が不十分なら、既存の正確な file を示して、それに合わせて調整させてください。ゼロから書き直させるのではなく、既存実装に寄せるのが重要です。たとえば「includes/abilities.php の既存 registration パターンを使い、category naming は統一し、必要な場合だけ REST visibility flag を変更して」と指示します。これが、codebase からずれずに wp-abilities-api usage を改善する最短ルートです。