wp-interactivity-api

wp-interactivity-api スキルの概要

このスキルでできること

wp-interactivity-api スキルは、WordPress Interactivity API の機能を、directive、store の形、サーバー側とクライアント側の接続を勘で埋めずに実装・デバッグするためのものです。data-wp-* マークアップ、@wordpress/interactivity、viewScriptModule、wp_interactivity_*() 関数を扱っていて、壊れたインタラクションを動く状態に戻すための実践的な道筋が必要なときに特に役立ちます。

どんな人向けか

WordPress のブロック、テーマ、プラグインで Frontend Development を行っていて、初回レンダーをきれいに通過するインタラクティブ UI が必要なら、wp-interactivity-api skill を使ってください。すでに repo があり、hydration が失敗する理由、directive が発火しない理由、新しいインタラクティブ領域をどう構成すべきかを追いたい場合に特に相性が良いです。

インストールする価値

最大の価値は、判断を速くできることです。何を検索すべきか、どの入力が重要か、block ベース・theme レベル・plugin 拡張のアプローチをどう切り分けるかが分かります。そのため、wp-interactivity-api ガイドは一般的なプロンプトよりも役立ちます。WordPress 6.9+ の実際の制約と、この API の接続のされ方を踏まえているからです。

wp-interactivity-api スキルの使い方

正しくインストールして範囲を定める

ディレクトリのエントリポイントにある wp-interactivity-api install パターンを使い、そのうえで bash と Node が使える filesystem-backed agent session 内でスキルを適用してください。repo には WordPress 6.9+ との互換性、また一部のワークフローでは WP-CLI の利用が記載されています。環境が project files を確認できない、または WordPress コマンドを実行できない場合、結果は弱くなります。

最初に渡すべき入力をそろえる

wp-interactivity-api usage は、次の情報を与えると最も効果的です。

• repo root
• wp-project-triage の triage output
• 影響範囲: frontend、editor、または両方
• WordPress のバージョンと、module/build の制約

弱いプロンプトの例: “Fix the Interactivity API.”
より強いプロンプトの例: “Debug why data-wp-on--click does not fire in this block on the frontend, WordPress 6.9, module scripts enabled, triage attached, and the issue only appears after navigation.”

まず確認するファイル

最初に SKILL.md を開き、次に以下を見てください。

• references/directives-quickref.md — directive 名と検索の足がかり
• references/debugging.md — 失敗時のチェックリスト
• references/server-side-rendering.md — PHP 側のセットアップと hydration ルール

今のタスクにこのスキルが合うかを判断したいなら、この 3 つのファイルを見るほうが、repo ツリーだけを見るより実際のワークフローが早くつかめます。

実践的なワークフローに沿って進める

このスキルは、次のシンプルな流れを前提に整理されています。

1. data-wp-interactive、@wordpress/interactivity、viewScriptModule を検索して既存利用を見つける
2. store namespace を特定し、マークアップが同じ名前を期待しているか確認する
3. server-rendered の context と初期 state を検証する
4. root element、view script module、event directive がすべて rendered HTML に存在するか確認する
5. 壊れている directive か state path が特定できるまでスコープを絞る

新しい interactive block を作る場合は、構造をゼロから考えるよりも、公式の scaffold template を使うほうがよいです。

wp-interactivity-api スキル FAQ

これはデバッグ専用ですか？

いいえ。wp-interactivity-api skill は build と debug の両方をカバーします。特に、block の viewScriptModule で interactivity を追加するべきか、既存の markup を plugin で拡張するべきか、theme レベルの挙動を hydration まで含めてどう接続するべきかを判断したいときに役立ちます。

通常のプロンプトと何が違いますか？

通常のプロンプトは、成功可否を実際に左右する WordPress 固有の詳細、たとえば directive の命名、store namespace の一致、server-side context、WordPress 6.9 の挙動変更を見落としがちです。このスキルはそれらの確認を前提にしているため、手戻りを減らし、最初に見るべきファイルを絞り込めます。

初心者にも向いていますか？

はい。目的を説明できて、正しい repo 範囲を agent に示せるなら使えます。API 全体をゼロから学ぶためのチュートリアルではありませんが、interactive root の不足、namespace の不一致、間違った rendering path といった、導入時によくあるミスを避ける助けになります。

どんなときに使わないべきですか？

WordPress Interactivity API とは関係のない JavaScript UI 作業には使わないでください。また、機能が完全に静的で、server-rendered directives を必要としない場合も対象外です。さらに、実際の repo files を確認できないなら相性はよくありません。このスキルは repo 固有の markup と PHP/JS の統合詳細に依存するためです。

wp-interactivity-api スキルの改善方法

ソースの文脈をもっと正確に渡す

最良の結果を得るには、対象の block、theme、plugin のどれを扱っているかを示し、レビューしてほしい directive か function を明確に伝えてください。data-wp-interactive、data-wp-context、それに対応する store namespace の前後を含めると、agent が意図と実装を推測ではなく比較できます。

症状だけでなく失敗モードを伝える

wp-interactivity-api skill では、“button does nothing” だけでは曖昧すぎます。観測できる壊れ方と期待動作を具体的に書くほうがよいです。たとえば、“click handler is bound but state does not update after server render” や “hydration works on first load but fails after client-side navigation” のように伝えると、directive の問題か、state 初期化の問題か、module 読み込みの問題かを切り分けやすくなります。

repo を読ませる出力を求め、反復する

良い wp-interactivity-api guide の進め方は、次の情報を出してもらうことです。

• もっとも可能性が高い根本原因
• 次に確認すべき正確なファイル
• 最小限のコード変更
• WordPress 6.9 互換性のリスク

そのうえで、最初の結果を手元に置いて反復します。問題が server rendering に関係するなら、関連する PHP と rendered HTML を含めてください。イベント処理に関する問題なら、directive の markup と store actions のファイルを含めてください。そうすることで、このスキルは検索補助から、実際に使える実装チェックリストに変わります。