penpot-design-to-code-review

penpot-design-to-code-review — 読み取り方向でデザイン↔コードの橋渡しを完成させる

1. タイトルと仕組み

このスキルは Penpot の選択範囲を読み取り、エンジニアが実装したコードと比較して、その差異を報告します。すべての変更は execute_code を通じて行い、export_shape で視覚的に検証し、penpotUtils.shapeStructure で構造を読み取ります（ツールの全容：shared/penpot-mcp-tool-reference.md）。penpotUtils.tokenOverview でトークンを読み取り、penpot.generateMarkup(shapes, opts) と penpot.generateStyle(shapes, opts) でデザインの HTML/CSS を抽出します（どちらも execute_code 経由で呼び出します）。また、別個の export_shape ツールで並べて比較するための画像を生成します。このスキルはデフォルトでキャンバスに対して読み取り専用（mode: suggest）であり、デザインを変更することはありません。レポートを出力し、明示的に要求された場合に限り、調整手順を提案します。コード側（React/Vue などのコンポーネントファイル、またはレンダリング済みの Storybook ストーリーとその DOM+CSS）は、ユーザーまたは別の MCP（filesystem、Storybook、ブラウザツール）から提供されます。コードソースが利用できない場合、このスキルは適切に機能を縮小し、選択範囲を代わりにデザインシステムのトークンと比較します。

---

2. 最も重要な唯一のルール

レビューを一度の処理で済ませてはならず、レビュー中に変更してはなりません。 抽出 → 正規化 → マッピング → 差分確認 → レポートの各ステップについて、論理的な execute_code 呼び出しを1回ずつ行い、各フェーズの間に読み取りまたは export_shape を挟みます。すべてを一度の処理でまとめた差異レポートは検証できず、トークン名についてほぼ確実に誤った内容になります。これは suggest モードのスキルであり、キャンバスには触れません。生成するのは構造化された DRIFT レポートのみです。調整編集が要求された場合は、それぞれのチェックポイントに従って、書き込み可能なスキル（トークン作業には penpot-foundations、レイヤー名の変更には penpot-rename-layers、構造の再構築には penpot-build-from-code）に引き継ぎます。

---

3. Penpot MCP ツールリファレンス

ツールの全容については shared/penpot-mcp-tool-reference.md を参照してください。このスキルで利用する呼び出しは次のとおりです。

必要な処理	呼び出し（特記がない限り execute_code 内）
選択範囲を解決する	penpot.selection（図形の配列）
選択範囲のオブジェクトツリーを読み取る	penpotUtils.shapeStructure(shape, maxDepth)
アクティブなトークンを読み取る（名前 → 解決済みの値）	penpotUtils.tokenOverview()
生の値から参照されているトークンを検索する	penpotUtils.findTokensByName(name) / findTokenByName(name)
デザインの HTML を生成する	penpot.generateMarkup(shapes, opts)
デザインの CSS を生成する	penpot.generateStyle(shapes, opts)
図形にバインドされたトークンを調べる	shape.tokens（プロパティ → トークンのマップ）
生のスタイル値を調べる	shape.fills、shape.strokes、shape.shadows、shape.borderRadius、および shape.width/height/bounds によるジオメトリ
比較画像を生成する	export_shape（別個の MCP ツールであり、JS ではありません）— 状態ボードごとに1回呼び出す

不慣れなシグネチャに依存する前に、penpot_api_info（例：penpot_api_info("Page", "generateMarkup")、penpot_api_info("Shape", "tokens")）を使って確認してください。

---

4. プラグイン API の基本事項

Gotcha の番号は shared/plugin-api-gotchas.md を参照します。このスキルで注意すべき点は次のとおりです。

• generateMarkup / generateStyle は単一のシェイプではなく、シェイプの配列を受け取り、opts オブジェクトも受け付けます。オプションを渡す前に、penpot_api_info("Penpot", "generateMarkup") / ("Penpot", "generateStyle") で opts の正確なキーを確認してください。オプション名を推測すると、何も通知されずにデフォルトの出力が生成され、「差異なし」と誤って結論づけることになります。penpot.selection は（すでに配列なので）そのまま渡してください。
• #1 スタイル配列の各項目は変更できません。読み取り（shape.fills[0].fillColor）は問題ありませんが、ここで塗りを「修正」しようとしてはいけません。このスキルでは変更を行いません。
• #5 width／height／parentX／parentY は読み取り専用です。差分の確認にはジオメトリを読み取りますが、ここでは resize()／setParentXY() を使用しません。
• #2 トークンの適用は非同期です（約 100 ms）。読み取りには関係ありませんが、照合作業でトークンを適用する場合、同じ呼び出しで値を読み戻さないでください（誤った失敗判定を避けてください）。
• shape.tokens は、どのデザイントークンがどのプロパティにバインドされているかを示す信頼できるマップです。生の 16 進数値からトークンを推測するより、こちらを優先してください。バインドされたトークンがない生の値も、それ自体が差異の指摘事項です（「デザインでトークンではなくハードコード値を使用している」）。
• generateStyle が出力するのは、デザインにおける CSS の概念であり、コード内のクラス名や変数は認識しません。その出力はデザインの意図として扱い、差分を取る前に両方を正規化してください（references/04 を参照）。生の CSS を文字列比較してはいけません。
• 推測せず、検証してください。generateMarkup／generateStyle が予期しない結果を返した場合、まず opts のキーが間違っているか、引数が配列ではない可能性を考えます。別の推測で再試行するのではなく、penpot_api_info でもう一度確認してください。

---

5. トークンを考慮したブリーフの契約

何かを抽出する前に、依頼内容を契約として言い直してください。デザインファイルを正式な仕様として扱い、トークンが存在する場合はハードコード値を決して受け入れない、シニアデザインエンジニアとして行動してください。

• コンテキスト — 何をレビューするのか（単一のコンポーネント、状態のセット、画面領域）と、誰のためか（対象のアプリ／ライブラリ、コードで使われているフレームワーク）。
• 目的 — 単一かつ具体的にします。例：「src/Button.tsx の <Button variant=primary size=md> が、hover／disabled 状態を含めて Penpot の選択内容と一致することを確認する。」「デザインをレビューする」では不十分です。
• 入力 —
  • Penpot の選択内容（解決してください。空の場合は、ユーザーに選択するかボード名を指定するよう依頼します）。
  • コードソース：ファイルパス／貼り付けられたコンポーネントコード、または Storybook のストーリー（URL またはレンダリング済みの DOM＋CSS）、あるいは明示的になし。
  • 使用するトークンセット（tokenOverview()）と、セマンティックトークンが解決されるべき階層。
• 制約 — どの側をどの要素の基準とするか（通常、視覚的なトークン、間隔、状態はデザインを基準とし、動作／a11y のセマンティクスはコードを基準とします）。4px グリッド上の値に限りトークンを使用すること。このスキルではキャンバスの変更は禁止です。
• 受け入れ基準（定量的） —
  • すべてのデザインプロパティを match／drift／code-only／design-only のいずれかに分類すること。
  • 色／間隔／角丸／タイポグラフィの差異すべてについて、該当するトークンを明記すること（または「トークンのバインドなし」と明示すること）。
  • 色の差異については、16 進数レベルの差分と、該当する場合は WCAG コントラストへの影響を報告すること。
  • 間隔の差異については、px 単位の差分と、その値が 4px グリッド上にあるかどうかを報告すること。
  • 状態の網羅状況をマトリックス（デザインの状態 × コードの状態）として報告し、明確な不足項目を示すこと。
  • §8 の評価基準に従って、すべての指摘事項に重大度（Critical／Major／Minor）を割り当てること。

---

6. 必須ワークフロー

フェーズ 0 — 発見（読み取り専用）

• 目標： 確認対象と、スタイルを読む前に存在するトークンを把握します。
• 手順：
  1. high_level_overview（セッションごとに 1 回）。
  2. execute_code：penpot.selection を解決します。空の場合は停止し、ユーザーにコンポーネント／ボードの選択を依頼します。ID、名前、種類、件数を返します。
  3. execute_code：選択されたトップレベルの図形ごとに penpotUtils.shapeStructure(sel[0], 4) を実行し、ツリー（名前、種類、ネスト）を記録します。
  4. execute_code：penpotUtils.tokenOverview() を実行し、トークンセット、名前、解決済みの値を記録します。
  5. ユーザーにコードのソース（ファイルパス／貼り付けられたコード／Storybook／なし）を確認します。
• 終了条件： デザインの構造、トークン、コードソース（またはソースがないことの確認）を説明できます。
• ✋ チェックポイント： 構造の概要＋トークン一覧＋差分比較の対象となるコードソースを提示します。スコープと、各観点でどちらを正とするかをユーザーに確認します。

フェーズ 1 — デザインからマークアップとスタイルを抽出

• 目標： 選択範囲を正規化された HTML＋CSS＋トークンマップに変換します。
• 手順： scripts/extractMarkupStyle.js を使用します。1 回の execute_code 呼び出しで penpot.generateMarkup(sel, opts) と penpot.generateStyle(sel, opts) を実行し、各ノードの shape.tokens を走査して、{ markup, style, perNode:[{id,name,type,tokens,rawFills,rawSpacing,radius,typography}] } を返します。
• 終了条件： デザインの HTML、CSS、ノードごとのトークン／生の値のマップが揃っています。
• ✋ チェックポイント： 抽出したマークアップ＋スタイル（抜粋）とトークンマップを提示します。マッピングの前に確認を取ります。

フェーズ 2 — 比較画像を取得

• 目標： エンジニアがレンダリング済みコードと見比べられる画像を用意します。
• 手順： scripts/exportForCompare.js を実行して図形 ID、境界、メタデータを収集し、続けて 'selection'（または取得した ID）と format: png を指定して export_shape MCP ツールを呼び出します。複数の状態があるコンポーネントでは、状態ボードごとに個別にエクスポートします。エンジニアに、レンダリング済みコード／ストーリーのスクリーンショットを依頼します（利用可能な場合はブラウザー MCP で取得します）。
• 終了条件： デザイン画像とコードのレンダリング画像が揃っています。
• ✋ チェックポイント： 並べて提示し、エンジニアに明らかな視覚的差異を優先順位付けしてもらいます。

フェーズ 3 — デザインとソースを対応付け

• 目標： デザインのノード／トークン／状態と、コードの要素／変数／プロパティの対応関係を確立します。references/02 を参照してください。
• 手順： 提供されたコードを解析します（プロパティ、CSS／変数の使用、状態クラス／バリアント）。対応表 designNode → codeElement、designToken → codeVar、designState → codeState を作成します。コードが Storybook のストーリーの場合は、ストーリーの args／controls から状態を導き出します（references/03 を参照）。コードソースがない場合： デザイントークンをデザインシステムのトークンセットにのみ対応付け、コード列は省略します（適切にフォールバックします）。
• 終了条件： すべてのデザインプロパティがコード側の対応物に関連付けられているか、未対応として明記された対応表が完成しています。
• ✋ チェックポイント： 対応表を提示し、差分比較の前に誤った対応付けを修正します。

フェーズ 4 — 差分を確認し、DRIFT レポートを出力

• 目標： 成果物を作成します。
• 手順： references/04 の比較ロジックを実行し、scripts/generateDriftReport.js で構造化された出力を組み立て、各検出結果を分類（match／drift／code-only／design-only）して重大度を割り当て、一致しない項目ごとに調整案を提示します。コントラストに影響する色の差異については、該当する WCAG の番号を記載します。
• 終了条件： トークン、構造、間隔、タイポグラフィ、状態を網羅し、重大度と調整案を含むレポートが完成しています。
• ✋ チェックポイント： レポートを提示します。ユーザーが修正の適用を希望する場合は、適切な書き込みスキルに引き継ぎます。ここでは変更を加えません。

7. 重要なルール

1. キャンバスは読み取り専用です。 このスキルは変更を加えるメソッドを呼び出しません。差分の調整は、後続スキル独自のチェックポイントを通過することを条件とした引き継ぎです。
2. 生の CSS を文字列比較しないでください。 差分を取る前に、両方を正規化します（単位 → px、色 → 小文字の 16 進数、短縮記法を展開、プロパティをソート）。references/04 を参照してください。
3. 対応するトークンのないハードコード値は、コードと見た目が一致していても指摘事項です。 「Minor」のデザイン衛生上の差異（「値がトークン化されていない」）として報告します。
4. すべての視覚的な指摘事項でトークン名を明記してください。 まず shape.tokens を読み取り、トークンがバインドされていない場合に限り、tokenOverview() と照合して生の 16 進数から判断します。
5. スペーシングの差分では px 値とグリッドへの整列状況を明記してください。 4 の倍数でない値は、コードと一致していてもすべて指摘します。
6. 推測せず、比較内容を制限してください。 コードソースがない場合は、デザインシステムのトークンを基準に比較することをレポートのヘッダーに記載し、コード側の情報を捏造しないでください。
7. 論理ステップごとに execute_code を 1 回だけ順番に実行し、フェーズ間にチェックポイントを設けてください。 抽出、マッピング、差分取得をまとめて実行しないでください。
8. オプションを渡す前に、penpot_api_info で generateMarkup／generateStyle の opts を確認してください。
9. 抽出を行う前に、選択範囲が空でないことを確認してください。選択範囲が空の場合、マークアップは何も返さず、エラーも表示されません。
10. 状態の網羅性はチェックボックスではなくマトリックスです。 （デザイン状態 × コード状態）のすべてのセルを報告してください。

---

8. ドメインアーキテクチャ

DRIFT レポートスキーマ（generateDriftReport.js が返し、レンダリングするデータ）：

{
  runId, scope, codeSource: "file" | "storybook" | "none",
  authoritative: { visual: "design", behavior: "code", ... },
  summary: { match, drift, codeOnly, designOnly, critical, major, minor },
  findings: [
    {
      id,                         // stable, e.g. "drift-color-01"
      dimension: "color" | "spacing" | "typography" | "radius" | "structure" | "state",
      designNode, codeElement,    // either may be null
      designValue, codeValue,     // normalized
      token,                      // bound design token name or null
      status: "match" | "drift" | "design-only" | "code-only",
      delta,                      // px delta, hex delta, contrast delta, etc.
      grid4px,                    // boolean | null (spacing only)
      wcag,                       // criterion string if contrast-impacting, else null
      severity: "Critical" | "Major" | "Minor",
      reconciliation              // concrete, one-line suggested fix + which side to change
    }
  ],
  stateMatrix: { design: [...], code: [...], cells: [{ state, design: bool, code: bool }] }
}

この形式は shared/report-schemas/drift-report.schema.json で正式に定義されています。code-to-penpot-sync ワークフローが分岐に使用する、派生したトップレベルの drift 件数（= summary.drift + summary.designOnly + summary.codeOnly）を含めてください。

重大度の基準：

重大度	定義
Critical	機能やアクセシビリティに影響する同等性の崩れ：インタラクティブ要素の状態がデザインには存在するもののコードには存在しない（またはその逆）、あるいは色の差異によってコントラストが WCAG 1.4.3 AA（4.5:1／3:1）を下回る場合。
Major	ユーザーが気づく視覚的な不一致：誤ったセマンティックトークンがバインドされている、スペーシングが 8px 以上ずれている、フォントサイズ／ウェイトが一致しない、構造要素（アイコン、ラベル）が欠落している場合。
Minor	衛生上の問題／知覚しにくい差異：値が一致しているもののトークン化されていない、スペーシングの差分が 4px 以下、順序／命名の違い、任意の装飾的な差異。

差分を取る項目： トークンの使用状況（どのトークンか、バインド済みかハードコードか）、構造（ノードツリーと DOM ツリー）、スペーシング（4px グリッド上のパディング／ギャップ／マージン）、タイポグラフィ（フォントファミリー／サイズ／ウェイト／行の高さ／文字間隔）、角丸／境界線、状態の網羅性。

---

9. モードとポリシー

shared/modes-and-policies.md を参照してください。このスキルはデフォルトで suggest であり、そのまま維持されます。これは監査スキルです。キャンバスには何も自動適用しません。変更を行わないため、このスキルにセーフセットはありません。「出力」はレポートです。ユーザーが差異の修正を求めた場合、このスキルは明示的に引き継ぎます。トークンの置き換えは penpot-foundations（apply-with-review）、レイヤーの命名は penpot-rename-layers、構造／ジオメトリの変更は penpot-build-from-code に引き継ぎます。各調整は、正とする情報源を明記した提案として提示します。後続スキルのチェックポイントを経ずに変更することはありません。

---

10. 状態管理

shared/state-management.md を参照してください。RUN_ID のスラッグの例：d2c-2026-06-05-a。台帳のキーは storage を介して書き込まれます（このスキルはキャンバスに対して読み取り専用のため、ユーザーがレポートの永続化を選択しない限り setSharedPluginData は書き込みません）。

• storage.run.scope — 解決済みの選択 ID／名前。
• storage.run.tokens — キャッシュされた tokenOverview() の結果。
• storage.run.extracted — フェーズ 1 の { markup, style, perNode }。
• storage.run.mapping — フェーズ 3 のデザイン↔コードのマッピングテーブル。
• storage.run.report — 最終的な DRIFT レポートオブジェクト。

再開： storage.run を再読み込みします。存在しない場合（新しいセッション）は、フェーズ 0 の検出を再実行し、古いレポートを信頼せずに shapeStructure と tokenOverview から再度導出します。ユーザーが引き継ぎ用にファイル内での永続化を希望する場合に限り、レポートを setSharedPluginData(NS, "${RUN_ID}.driftReport", JSON.stringify(report)) にミラーリングすることもできます。

---

11. ユーザー確認ポイント

フェーズ後	表示する成果物	確認する内容
0 検出	構造の概要、トークン一覧、特定されたコードソース	「対象範囲と、各側がどの観点で正とするかを確認してください。」
1 抽出	整理したマークアップとスタイル、ノードごとのトークンマップ	「デザインで宣言されている内容として、これで想定どおりですか？」
2 ビジュアル	コードのレンダリングと組み合わせた export_shape の PNG	「優先して対応すべき明らかなビジュアル上の差異があればお知らせください。」
3 マッピング	デザイン↔コードのマッピングテーブル	「誤ってマッピングされたノード／トークン／状態があれば修正してください。」
4 レポート	DRIFT レポート全体（概要＋検出事項＋状態マトリクス）	「承認しますか？ 調整作業を write スキルに引き継ぎますか？」

---

12. 命名規則

shared/naming-conventions.md を参照してください。このスキルは名前を読み取るため、デザインノードを DOM 要素にマッピングできるよう、名前が意味のあるもの（button、label、icon、h1～h6）であることを前提とします。自動生成された名前（Rectangle 12、Board）はマッピングの品質を低下させます。選択範囲にそのような名前が多い場合は、まず penpot-rename-layers の実行を推奨し、レポートに構造差分の信頼度が低下することを記載してください。トークンは shared/tokens-schema.json のドット記法の分類に照らして照合します。トークンの type 文字列は Penpot で使われる正確な表記（color、spacing、borderRadius、fontSizes など）です。コード変数（CSS カスタムプロパティ、JS テーマキー）は、マッピング前にそのドット記法に正規化されます（例：--color-action-primary-bg ↔ color.action.primary.bg）。

---

13. 合理化を防ぐための表

LLM が述べる言い訳	それが誤りである理由	決定論的な対策
「CSS の文字列が異なるので、ずれています。」	generateStyle は 16px を出力しますが、コードは 1rem を出力します。#FFF と #ffffff、省略形と完全形の違いもあります。文字列をそのまま比較すると、無意味な指摘が大量に出ます。	両方を先に正規化します（単位は px に変換、色は小文字の 6 桁の 16 進数に変換、省略形を展開、プロパティをソート）。正規化したマップのみを比較します。
「16 進数の値がコードと一致しているので、このプロパティは合格です。」	紐付けられたトークンがない状態で値が一致していても、テーマ設定とガバナンスが損なわれます。ダークモードに切り替えても、ひそかに反映されなくなります。	shape.tokens を確認します。トークンが紐付けられていない場合、16 進数の値が一致していても、「値がトークン化されていない」という Minor の指摘を出します。
「Storybook／コードが渡されていないので、レビューできません。」	このスキルには、状況に応じて適切に処理を縮退させることが求められます。	デザインシステムのトークンモードに切り替えます。選択範囲を tokenOverview() と比較し、レポートヘッダーで codeSource: "none" を指定して、デザイン側の指摘のみを報告します。
「generateStyle の結果がほとんど空だったので、デザインにはスタイルがほとんどありません。」	単一のシェイプを配列ではなく渡したか、誤った opts キーを指定した可能性のほうがはるかに高いです。	次の点を再確認します。penpot.selection（配列）を渡していること、penpot_api_info で opts を確認していること。再抽出してから、「ずれなし」と結論づけてください。
「ここにいるついでに、Penpot のトークンの不一致を修正しておきます。」	これは suggest モードの読み取り専用スキルです。変更を加えると契約に違反し、後続のチェックポイントを飛ばすことになります。	変更は加えないでください。調整案として提案し、penpot-foundations／penpot-build-from-code に引き継ぎます。
「どちらも間隔が 18px なので一致しています。合格です。」	18 は 4px グリッドから外れています。コードと一致していても、正しいとは限りません。	コードと一致するかどうかにかかわらず、4 の倍数ではない間隔はすべて指摘（grid4px:false）として挙げ、最も近いグリッドトークンを提案します。

---

14. ヘルパーコードスニペット

選択範囲を解決して要約します（フェーズ 0）：

const sel = penpot.selection || [];
return sel.length === 0
  ? { empty: true, hint: "Select the component/board to review, then re-run." }
  : { count: sel.length, items: sel.map(s => ({ id: s.id, name: s.name, type: s.type })) };

ノードに紐付けられたトークンと生の値を読み取ります（フェーズ 1）：

const s = penpotUtils.findShapeById("REPLACE-ME-shape-id");
const tokens = s.tokens ? Object.fromEntries(Object.entries(s.tokens)) : {};
const fill = Array.isArray(s.fills) && s.fills[0] ? s.fills[0].fillColor : null;
return { id: s.id, name: s.name, boundTokens: tokens, rawFillColor: fill, radius: s.borderRadius ?? null };

何も紐付けられていない場合に、生の 16 進数を既存のトークンと照合します（フェーズ 4 のフォールバック）：

const overview = penpotUtils.tokenOverview();
const target = "REPLACE-ME-#0066ff".toLowerCase();
// scan resolved color tokens for an exact value match
const hit = (overview.tokens || []).find(t =>
  t.type === "color" && String(t.resolvedValue).toLowerCase() === target);
return { rawValue: target, suggestedToken: hit ? hit.name : null };

---

15. 参考リソース

• penpot_api_info("Penpot", "generateMarkup") と ("Penpot", "generateStyle") — フェーズ 1 の前に opts キーを確認します。
• penpot_api_info("Shape", "tokens") — 紐付けられたトークンのマップ構造を確認します。
• penpot_api_info("Page", "shapeStructure")／penpotUtils — 構造を読み取ります。
• shared/penpot-mcp-tool-reference.md — ツールの一覧とグローバル。
• shared/plugin-api-gotchas.md — 不変配列、非同期トークン、読み取り専用のジオメトリ。
• shared/tokens-schema.json — トークンの型文字列、階層、4px グリッドのルール。
• 色のずれの重大度を引き上げる際は、W3C WCAG 1.4.3（コントラスト）を参照します。

---

16. 補助ファイル

参考資料（段階的な開示 — 該当するフェーズの実行時に読み込みます）

ファイル	読み込むタイミング	内容
references/01-extract-markup-style.md	フェーズ 1	generateMarkup／generateStyle の使用方法、opts、shape.tokens と生の値の読み取り、ノードごとのマップの作成
references/02-mapping-to-source.md	フェーズ 3	渡されたコンポーネントコードの解析、デザインノードから DOM へのマッピング、トークンから CSS 変数／テーマキーへのマッピング、状態から props／クラスへのマッピング
references/03-storybook-compare.md	フェーズ 3（Storybook の場合）	ストーリーの args／controls からの状態の導出、レンダリングされた DOM と CSS の取得、URL のみが渡された場合の適切な処理縮退
references/04-drift-report.md	フェーズ 4	正規化ルール、差分アルゴリズム、重大度の基準、レポートのレンダリング、調整案の表現方法

スクリプト（execute_code 呼び出しに貼り付けます。プレースホルダーを置き換えてください）

スクリプト	用途
scripts/extractMarkupStyle.js	フェーズ 1 — 選択範囲の generateMarkup + generateStyle + ノードごとのトークン／生値マップ
scripts/exportForCompare.js	フェーズ 2 — 呼び出し元が export_shape MCP ツールを呼び出せるように、シェイプ ID、境界、メタデータを収集
scripts/generateDriftReport.js	フェーズ 4 — 抽出したデザインデータとマッピング済みコードデータから、構造化された DRIFT レポートを作成

ドクトリンのパス。 ネイティブインストールでは、shared/… と policies/… はこのバンドル内で解決されます（インストーラーによって同梱されます）。Claude Code プラグインのインストールでは、プラグインルート（このファイルから 2 つ上のディレクトリ）にあり、パスは ${CLAUDE_PLUGIN_ROOT}/shared/… です。