wp-block-themes

wp-block-themes スキルの概要

wp-block-themes が対応する範囲

wp-block-themes スキルは、WordPress のブロックテーマ作業を支援します。対象は theme.json、テンプレート、テンプレートパーツ、パターン、スタイルバリエーション、そして「なぜスタイルが反映されないのか？」という典型的なデバッグの流れです。ブロックテーマについての一般論ではなく、ファイル構成を踏まえた WordPress 専用のワークフローが必要なときに最も役立ちます。

どんな人に向いているか

wp-block-themes スキルは、ブロックテーマを実装・保守している人、クラシックテーマを移行している人、Site Editor の挙動を調べている人に向いています。フロントエンド、エディター、ユーザーによるカスタマイズ後のスタイルまで含めて、結果を安定して揃えたい設計実装の作業に特に適しています。

何が違うのか

このスキルは意思決定を起点にしており、まず何を確認すべきか、どのファイルが重要か、WordPress がテーマ設定とユーザー上書きをどう解決するかを示します。そのため、「ブロックテーマを手伝って」とモデルに頼むよりも、対象範囲、互換性、変更を置くべき場所の見通しが立ちやすく、手探りを減らせます。

wp-block-themes スキルの使い方

正しくインストールして、対象範囲を絞る

インストールは次のコマンドで行います:
npx skills add WordPress/agent-skills --skill wp-block-themes

wp-block-themes のインストールとセットアップでは、何かを変える前に作業対象をアクティブなテーマルートに絞ってください。リポジトリに複数のテーマがある場合は、正確なテーマディレクトリと対象の WordPress バージョンを特定する必要があります。theme.json の機能や挙動は core のバージョンによって変わるためです。

適切な入力を与える

wp-block-themes の使い方は、次の点を明示すると最も効果的です:

• テーマルートまたは repo ルート
• 対象の具体的な範囲: theme.json、templates/、parts/、patterns/、styles/
• 問題が出ている場所: Site Editor、投稿エディター、フロントエンド、またはそのすべて
• 新規構築か、移行か、デバッグか

よいプロンプト例は次のようなものです: 「アクティブなブロックテーマの theme.json を更新して、ボタンの新しいブランドカラーをエディターとフロントエンドの両方に反映してください。ただし、ユーザーの上書きは維持します。対象は WordPress 6.9 です。必要なら template parts も確認してください。」

まず読むべきファイル

最初に SKILL.md を確認し、続いて次を見てください:

• references/theme-json.md
• references/templates-and-parts.md
• references/patterns.md
• references/style-variations.md
• references/debugging.md
• references/creating-new-block-theme.md

リポジトリ構成が不明確な場合は、scripts/detect_block_themes.mjs も確認してください。wp-block-themes のガイドは、編集に入る前にこの検出ステップを踏むことで、最も精度が上がります。

正しい順序で進める

実務的なワークフローは次の通りです:

1. テーマルートを検出する
2. 問題が出ている範囲を確認する
3. 関連する reference ファイルを読む
4. その挙動を持つべき最小のファイルだけを変更する
5. ユーザーのカスタマイズとキャッシュされたエディター状態を含めて検証する

この順序が重要なのは、壊れて見えるブロックテーマの問題の多くが、実際には theme ファイルの不具合ではなく、スタイル階層や保存済みのユーザー設定に起因しているからです。

wp-block-themes スキル FAQ

wp-block-themes は上級者専用ですか?

いいえ。すでに編集対象のテーマが分かっていて、変更したい内容を明確に説明できるなら、初心者にも使いやすいです。WordPress 固有の振り分けはスキルが担いますが、テーマの文脈と望む結果は、利用者側で伝える必要があります。

どんな場合は使わないほうがいいですか?

一般的な WordPress プラグイン作業、ブロックテーマ外の PHP テンプレート階層のデバッグ、テーマファイルに触れないビジュアルデザイン作業には wp-block-themes を使わないでください。問題が theme、ユーザーのカスタマイズ、Site Editor のどこにあるのか分からない場合も、最適な用途ではありません。

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

通常のプロンプトは、テーマの filesystem、互換性の範囲、ブロックテーマのファイル配置を確認しないまま変更案を出してしまうことがあります。wp-block-themes スキルは、特に配置先が重要な設計実装で、theme.json、templates、parts、styles にまたがる disciplined な wp-block-themes usage が必要なときに有効です。

導入を妨げる要因は何ですか?

最も多い障害は、テーマの対象範囲が曖昧なこと、WordPress のバージョン指定がないこと、theme のデフォルトとユーザーが選んだスタイルを混同していることです。これらを最初から答えられなくてもスキルは使えますが、最初の提案の精度は下がりやすくなります。

wp-block-themes スキルの改善方法

デザイン入力をもっと具体的にする

Design Implementation 用に wp-block-themes の結果を良くしたいなら、意図するデザインと、影響を受けるブロックや領域を正確に伝えてください。たとえば、「テーマをもっとすっきり見せて」ではなく、「すべてのテンプレートで見出しの余白とボタンの角丸をデフォルト設定にしてください」と伝えるほうがよいです。前者は実行可能ですが、後者は要件をモデルに推測させることになります。

デフォルトと上書きを分けて考える

よくある失敗は、theme.json の変更でユーザーのカスタマイズも上書きできると期待してしまうことです。問題が保存済みの global styles や選択中の style variation にあるなら、その点を明示してください。結果を改善したいときは、次のどれを望んでいるかをはっきり伝えると効果的です:

• theme のデフォルト
• editor のコントロール
• style variation
• 単発のテンプレート変更

最小の再現例で繰り返す

最初の出力が惜しいが完全ではない場合は、次の依頼を 1 ファイルと 1 症状に絞ってください。たとえば、「styles/blue.json が選ばれているのに再読み込み後に反映されません。これが想定動作かどうかと、何をテストすべきかを説明してください。」のようにすると、広い設計変更を求めるよりも、的確なデバッグにつながります。

リポジトリの規約に合わせて検証する

wp-block-themes スキルは、編集前にリポジトリが patterns、style variations、あるいは最小構成の theme scaffold を使っているか確認すると、さらに精度が上がります。最初の結果が一般的すぎると感じたら、repo の file path、アクティブな theme 名、適用したい具体的な reference ファイルを指定して、もう一度実行してください。