penpot-router

penpot-router — ディスパッチャー

1. タイトルと仕組み

penpot-router は薄いエントリーポイントです。描画、トークン化、再構成は行わず、ユーザーの意図を読み取り、後続のスキルまたはワークフロー（画面の構築、スライドデッキの作成、デザインシステムの構築、監査、移行、DESIGN.md の抽出など）を必ず1つだけ呼び出します。変更はすべて execute_code を通じて行い、export_shape で視覚的に検証します。構造の読み取りには penpotUtils.shapeStructure を使用します（ツールの全体像は shared/penpot-mcp-tool-reference.md を参照）。このスキルが使用するのは、high_level_overview と読み取り専用の execute_code による検出呼び出し（penpotUtils.shapeStructure、penpotUtils.tokenOverview()）のみです。変更はすべて呼び出し先のスキルが担当します。このルーターは何も変更しないため、視覚的な検証も行いません。ホストクライアントが description に基づいてスキルをすでに自動選択する場合、このルーターはドキュメントとして機能する形に適切に切り替わります。その場合、references/01-intent-taxonomy.md の意図の分類は、アクティブなディスパッチャーではなく参照マップになります。

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

必ず1つの対象にルーティングし、その前に事前確認を行います。 ルーター内から変更を開始してはならず、1つのリクエストを複数の変更を伴うスキルに並列で振り分けてはなりません。1つのリクエスト → 1回の事前確認（概要と構造／トークンの簡易読み取り） → 1つの対象スキルまたはワークフロー → 引き継ぎ。2つの対象のどちらにするか意図が曖昧な場合は、確認の質問を1つしてください。推測して実行してはなりません。

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

ツールの全体像は shared/penpot-mcp-tool-reference.md を参照してください。ルーターが使用する呼び出しは2つだけです。

呼び出し	ルーターでの用途
high_level_overview	セッション開始時に必須の前置きです。ルーティングの判断を実行に移す前に、必ず呼び出してください。
execute_code（読み取り専用）	penpotUtils.shapeStructure(penpot.currentPage.root, 2) と penpotUtils.tokenOverview() を使ってファイルの現在の状態を把握し、推測ではなく実際の状況に基づいてルーティングします。

ルーターは作成／変更／削除のために execute_code を呼び出すことはなく、export_shape も呼び出しません（検証する対象がないためです）。変更と検証はすべて後続のスキルが担当します。

4. Plugin API の基本事項

ルーターが触れるのは読み取り専用のパスのみです。penpot.currentPage、penpot.selection、penpot.library.local.tokens、penpotUtils.shapeStructure、penpotUtils.tokenOverview、penpotUtils.getPages が対象です。注意点（shared/plugin-api-gotchas.md）：

• #2 トークンの適用は非同期です（約100 ms） — 解決済みの値を権威ある値として読み戻してはなりません。ルーターはトークンを一切適用しないため、実際に注意すべき落とし穴はやりすぎることだけです。 特定のシグネチャを持つ検出ヘルパーがあるかどうかわからない場合は、推測せずに penpot_api_info（例：penpot_api_info("PenpotUtils", "shapeStructure")）で確認してください。

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

ルーティングの前に、リクエストを簡潔な契約として言い換え、選択されたスキルが明確なブリーフを引き継げるようにします。 役割を割り当てます：「誤ったフローで作業を始めることのない、シニアのデザインシステムトリアージリードとして行動してください。」 次の内容をまとめます：

• コンテキスト — プロダクト、対象ユーザー、このファイルにデザインシステムがすでに存在するかどうか（tokenOverview() と shapeStructure から判断）。
• 目的 — 動詞で始まる意図を 1 つ（「設定画面を構築する」「コントラストを監査する」「Figma のボタンライブラリを移行する」）。ユーザーが 2 つ述べている場合は分割し、主な目的をルーティングして、残りはキューに入れます。
• 入力 — 選択中のシェイプ／ボード、対象ページ、参照するトークン／コンポーネント、外部参照（コードパス、Figma URL）。
• 制約 — 使用禁止のコンポーネント、遵守必須のルール、モード（提案／レビュー／自動修正）、スコープの上限。汎用的な AI らしい見た目を避けるかどうかをユーザーがすでに述べている場合は、antiSlop: on|off として引き継ぎます。そうするとビルドスキルはその設定を保存し、オプトインの質問を省略します。ルーター自身はこれを質問しません。
• 受け入れ条件 — 下流のスキルにとって「完了」が何を意味するか（例：「本文テキストのコントラスト比が WCAG AA の ≥ 4.5:1」「すべての間隔が 4px グリッドに沿っている」「State 軸のバリアントマトリクスが完成している」）。ルーターはこれらを検証せず、対象スキルに引き渡します。

ルーターはこの契約を引き継ぎペイロードとして出力します。トークンの値や名前を捏造することはありません。リクエストが新しいトークンを必要とする場合、その作業は下流のスキルが担当します（人間による承認ゲートが設けられます）。

6. 必須のワークフロー

フェーズ 0 — 検出（読み取り専用）

目標： セッションが初期化されており、ファイルの状態が把握できていることを確認します。

1. 今回のセッションで high_level_overview が呼び出されていることを確認します。呼び出されていない場合は、ここで呼び出します。
2. 状態を浅く把握するため、読み取り専用の execute_code を 1 回呼び出します：

   return {
     pages: penpotUtils.getPages().map(p => p.name),
     currentPage: penpot.currentPage && penpot.currentPage.name,
     selectionCount: penpot.selection.length,
     selection: penpot.selection.map(s => ({ id: s.id, name: s.name, type: s.type })),
     topLevel: penpotUtils.shapeStructure(penpot.currentPage.root, 1)
   };
   

3. トークンの状態を確認するため、読み取り専用の呼び出しを 1 回行います：

   return penpotUtils.tokenOverview();
   

終了条件： (a) トークン／セットが存在するか、(b) 何が選択されているか、(c) 深さ 1 のページレイアウトが把握できていること。✋ チェックポイント： 不要です。読み取り専用のため、そのままフェーズ 1 に進みます。

フェーズ 1 — 意図の分類

目標： ユーザーの言葉をルーティングテーブルの 1 行に対応付けます（§8／references/01-intent-taxonomy.md）。 リクエストの文言をそのまま読み、フェーズ 0 の状態と組み合わせます（例：「トークンがまだ存在しない」場合、曖昧な「デザインシステムを設定して」という依頼は penpot-foundations／design-system-bootstrap ワークフローに振り分けられます）。リクエストが 1 つの対象に明確に対応する場合は、そのまま進みます。確信度が同程度の候補が 2 つ以上ある場合は、✋ チェックポイント： どちらかを選べるよう、候補となる 2 つの対象を平易な言葉で示して、曖昧さを解消する質問を 1 つします。

フェーズ 2 — 引き継ぎ

目標： 明確なブリーフを添えて制御を引き渡します。

1. 選択した対象を明示します（「…のため、penpot-build-screen にルーティングします。」）。
2. §5 のトークンを考慮したブリーフ契約をペイロードとして出力します。
3. 後で対応する二次的な意図があれば、その旨を記します。
4. 対象スキルを呼び出す、または実行を指示します。ここでルーターの役割は終了し、変更は一切行いません。 終了条件： 対象が 1 つだけ指定され、契約が出力され、二次的な意図がキューに入っていること。 ✋ チェックポイント（条件付き）： 「X にルーティングします。確認しますか、それとも変更しますか？」と尋ねるのは、(a) フェーズ 1 で曖昧さがあった（確信度が同程度の候補が 2 つあった）場合、または (b) 既存のコンテンツがあるファイルに対して、コストの高い変更を伴うフローを実行する場合（移行、成熟したシステムへのブートストラップ、コンポーネントを再構成するあらゆる作業）に限ります。明確に一致する場合は、ルートを伝えてそのまま進みます。対象スキル独自のフェーズ 0 チェックポイントがユーザーにとって自然な確認の機会です。ここでの二度目の確認は安全性ではなく、手間を増やすだけです。

7. 重要なルール

1. ルートに対する操作を行う前に、必ず high_level_overview が実行されたことを確認してください。 概要の確認を省略したセッションでは、ルーティングの判断を実行しません。
2. リクエストごとに対象は1つです。 複数の意図を含むリクエストは分割し、主な意図をルーティングして、残りはキューに入れます。
3. 読み取り専用のみです。 ルーターは変更を伴う execute_code を呼び出さず、export_shape も呼び出しません。
4. 曖昧な場合は推測しません。 妥当な対象が2つある場合は、二者択一で決めず、質問を1つします。
5. ファイルの状態に基づいてルーティングします。 Phase 0 の読み取りで、空のファイルか成熟したシステムかなどを確認して判断します。
6. 依頼内容はそのまま転送します。 制約や受け入れ基準を黙って省略しないでください。
7. ドキュメントに切り替えます。 ホストが説明に基づいてすでにルーティングしている場合は、二重にディスパッチせず、分類表を案内図として提示して手を引きます。
8. デフォルトモードは提案です。 ルーターはルートを提案しますが、キャンバスの変更は行いません。

8. ドメインアーキテクチャ — ルーティングテーブル

ルーターが提供するのはキャンバス上の成果物ではなく、判断です。判断の対象領域を以下の表に示します。 完全な表現マップとフォールバックについては、references/01-intent-taxonomy.md を参照してください。

スキル

意図	対象スキル	ユーザーの表現例
トークン／基盤の設定（色、余白、タイポグラフィ、角丸のスケール、テーマ）	penpot-foundations	「デザイントークンを設定する」「色と余白のスケールを作成する」「ダークテーマを追加する」「基盤を立ち上げる」
再利用可能なコンポーネントとバリアントの作成／拡張	penpot-component-factory	「バリアント付きの Button コンポーネントを作る」「状態を備えた Input を作る」「これをコンポーネント化する」「Size 軸を追加する」
依頼内容と既存のシステムに基づく画面／ビューの組み立て	penpot-build-screen	「設定画面をデザインする」「ダッシュボードをレイアウトする」「この依頼内容から料金ページを作る」
コード／マークアップに基づく画面／ビューの作成	penpot-build-from-code	「この React ページを Penpot で作成する」「このコンポーネントの JSX をボードに反映する」「このコードに一致する画面を作る」
依頼内容に基づくプレゼンテーション／スライドデッキのデザイン	penpot-build-deck	「プレゼンテーションを作成する」「スライドデッキを作る」「ピッチデッキを作る」「この講演用のスライドを作る」「この概要をスライドにする」
引き継ぎ用のデザイン文書化／注釈付け	penpot-document-handoff	「このデザインを文書化する」「この画面に注釈を付ける」「引き継ぎの準備をする」「観察メモを追加する」「批評カードを作成する」「開発者向けにこのフローを説明する」
アクセシビリティ監査（WCAG）	penpot-audit-accessibility	「アクセシビリティをチェックする」「WCAG AA 監査」「コントラストをチェックする」「タッチ対象は十分な大きさか」「a11y レビュー」
トークンガバナンス監査	penpot-audit-tokens	「ハードコードされた色を見つける」「トークンの使用状況を監査する」「4px グリッドから外れている箇所はどこか」「孤立／未使用のトークンを見つける」
デザインとコードの比較（乖離）	penpot-design-to-code-review	「このデザインはコードと一致しているか」「デザインとコードのレビュー」「Penpot とコンポーネントの乖離を見つける」
ファイルから持ち運び可能な DESIGN.md 仕様を抽出	penpot-design-md	「DESIGN.md を生成する」「デザインガイドラインを Markdown としてエクスポートする」「コーディングエージェント用のスタイルガイドファイル」
Figma からのインポート／移行	penpot-migrate	「この Figma ファイルを移行する」「Figma からインポートする」「Figma ライブラリを Penpot に取り込む」
汎用的な AI 風のデザインから離れるための確認／調整	penpot-anti-slop	「AI 生成のように見えるか」「アンチスロップチェック」「もっと個性を出す」「¿parece hecho por IA?」「evita la estética IA」
レイヤー名の意味に基づく変更	penpot-rename-layers	「これらのレイヤー名を変更する」「レイヤー名を整理する」「セマンティックな HTML レイヤー名」「Rectangle 12 の名前を修正する」

ワークフロー（複数スキルのオーケストレーション）

意図	対象ワークフロー	ユーザーの発言例
どこから始めるか決める（メタ）	routing	「どのツールが必要かわかりません」「何から始めればよいですか」「このPenpotファイルについて手伝ってください」
コードまたはゼロからデザインシステムを構築する	design-system-bootstrap	「デザインシステム一式をセットアップして」「コードベースからトークン、コンポーネント、ドキュメントを作成して」「ライブラリ全体を立ち上げて」
ブリーフから完成画面まで（基盤の確認 → 構築 → アクセシビリティ）	brief-to-screen	「このブリーフから画面を仕上げて」「このページを端から端までデザインして検証して」
ブリーフから完成した再生可能なデッキまで（build-deck → スライドのアクセシビリティ + デッキ品質の反復）	brief-to-deck	「このアウトラインを洗練されたデッキにして」「このプレゼンテーションを端から端までデザインして検証して」
Penpotとコードを同期する	code-to-penpot-sync	「コンポーネントをコードに同期して」「Penpotとリポジトリを調整して」「デザインとコードの整合性を保って」
FigmaからPenpotへの完全な移行プログラム	figma-migration	「Figmaプロジェクト全体を移行して」「トークン、コンポーネント、画面を含めてFigmaを完全にインポートして」
引き継ぎ前にアクセシビリティをデザインの必須条件にする	accessibility-gate	「アクセシビリティに合格するまで引き継ぎを止めて」「アクセシビリティゲートを実行して」「リリース前に検証して」

9. モードとポリシー

デフォルトのモード：suggest（shared/modes-and-policies.mdを参照）。ルーターは本質的に読み取り専用のため、safe-setの自動修正項目はありません。どのモードでもキャンバスを変更することはありません。確認なしで実行できること：high_level_overviewの呼び出し、読み取り専用のshapeStructure／tokenOverviewによる探索、ルートの提案です。ユーザー（または後続スキル独自のゲート）の確認が必ず必要なこと：意図が曖昧な場合のルート実行、および対象スキルが行うすべての処理です（これらには対象スキルのモードが適用されます）。

10. 状態管理

ルーターが書き込む状態は最小限です（shared/state-management.md）。ルーターはRUN_IDワークフローを管理しません。これはルーティング先のスキルが管理します。ただし、再開したセッションで選択に至った経緯がわかるよう、判断を記録します。

• storage.router = { lastIntent, chosenTarget, queuedIntents, overviewCalled: true }（セッションキャッシュ）。
• 任意のファイル内ブレッドクラムを、setSharedPluginDataを介して名前空間penpot-ai、キーrouter.lastRouteに保存します。使用前にpenpot_api_infoでシグネチャを確認してください。

再開時：storage.routerとブレッドクラムを読み直し、Phase 0の探索を再実行してください（ファイルの状態が変わっている可能性があります）。そのまま続行せず、改めて分類してください。ルーティングには現在の状況を反映する必要があります。

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

フェーズの後	表示する成果物	確認する内容
Phase 0（探索）	ページ一覧、選択内容の概要、トークンセットの有無	（情報提供のみ — 承認不要。そのまま進めます。）
Phase 1（分類）— 曖昧な場合のみ	わかりやすい表現で示した2つの候補	「ご希望に近いのはどちらですか — AとB？」
Phase 2（引き継ぎ）— 曖昧な場合、または既存コンテンツを変更するコストの高いフローを対象とする場合のみ	選択した対象 + Token-Aware Brief Contract + キューに追加された意図	「Xにルーティングします — 確認しますか、それとも変更しますか？」（一致が明確な場合：ルートを伝えてそのまま進みます）

12. 命名規則

ルーター自体は名前を強制しませんが、ブリーフを言い換える際にはキットの用語を使う必要があります。これにより、後続スキルに正しい期待値が引き継がれます（shared/naming-conventions.md）。トークンはドット記法（color.action.primary.bg）、コンポーネントはPascalCase（Button）、バリアントはProperty=Valueの組み合わせ（State=Hover）、レイヤーには意味を表すkebab-caseのHTML名（nav、card-container）を使用します。リクエストがRUN_ID（複数ステップのワークフロー）を必要とする場合は、dsb-2026-06-05-aのような規則に沿ったスラッグを使用し、管理は対象スキルに任せてください。

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

LLMがする言い訳	それが誤りである理由	フローを停止する決定論的な対策
「これは明らかにビルドの依頼です。今すぐボードの作成を始めましょう。」	ルーターは読み取り専用です。ここで変更を始めると、対象スキルの調査、ブリーフの契約、チェックポイントを迂回することになります。	停止します。penpot-build-screen／penpot-build-from-code にルーティングし、§5 のブリーフを出力して、Phase 0 とすべての変更をそのスキルに任せます。
「依頼にはトークンと画面の両方が書かれているので、両方に同時にルーティングしましょう。」	変更を行う2つのスキルに並行して振り分けると、編集が競合し、実行内容を監査できなくなります。	意図を分割します。主要な目的をルーティングし、残りは storage.router.queuedIntents にキューイングします。1つの依頼につき対象は1つです。
「意図が少し曖昧ですが、可能性が高そうなスキルを選んで進めましょう。」	誤ったフローで開始すると、元に戻すコストが高くなります（ジオメトリやバリアントの変更は安全に元に戻せるとは限りません）。	Phase 1 のチェックポイントで停止し、候補となる2つの対象を提示して、曖昧さを解消する質問を1つ尋ねます。
「high_level_overview はおそらく前に呼び出されています。省略しましょう。」	MCP 独自のガイダンスを読み込まずに操作することが、後続で API を誤用する最大の原因です。	今回のセッションで実行されたことを確認します。不確かな場合は呼び出します。そうでなければ、ルートは実行しません。
「ホストクライアントがスキルを自動選択しましたが、念のため再ディスパッチしましょう。」	二重ディスパッチすると、同じ処理が2回実行されたり、2つのスキルが競合したりします。	ホストによる自動選択を検出し、ドキュメント提供に切り替え（分類をマップとして提示）、処理を譲ります。
「ユーザーの言葉だけをもとにルーティングしましょう。ファイルを読む必要はありません。」	同じ表現でも、空のファイルと成熟したシステムではルーティング先が異なります（「デザインシステムを設定して」→初期設定か拡張か）。	Phase 0 の読み取り（tokenOverview、shapeStructure）を実行し、分類前にファイルの状態を使って候補を絞り込みます。

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

読み取り専用の調査のみ — ルーターは変更を行いません。

// Phase 0a — state sense (paste into one execute_code call)
return {
  pages: penpotUtils.getPages().map(p => p.name),
  currentPage: penpot.currentPage && penpot.currentPage.name,
  selectionCount: penpot.selection.length,
  selection: penpot.selection.map(s => ({ id: s.id, name: s.name, type: s.type })),
  topLevel: penpotUtils.shapeStructure(penpot.currentPage.root, 1)
};

// Phase 0b — token state (does a design system already exist?)
const ov = penpotUtils.tokenOverview();
return {
  hasTokens: !!(ov && ov.totalTokens),
  overview: ov
};

// Optional — drop a routing breadcrumb into the file (verify signature first via
// penpot_api_info("PenpotFile", "setSharedPluginData"))
penpot.currentFile.setSharedPluginData(
  "penpot-ai",
  "router.lastRoute",
  JSON.stringify({ chosenTarget: "REPLACE-ME", at: "RUN_ID_HERE" })
);
return { recorded: true };

15. 参考リソース

• penpot_api_info("PenpotUtils", "shapeStructure")、penpot_api_info("PenpotUtils", "tokenOverview") — 調査ヘルパーのシグネチャを確認します。
• penpot_api_info("PenpotFile", "setSharedPluginData") — ブレッドクラムのシグネチャを確認します。
• shared/penpot-mcp-tool-reference.md — ツールの一覧です。
• shared/modes-and-policies.md — ルーターが提案のみを行う理由です。
• 兄弟スキル独自の SKILL.md の説明 — ルーターが対応付ける、信頼できるトリガー一覧です。

16. 補助ファイル

references/（段階的開示による詳細資料）

ファイル	読み込むタイミング	内容
references/01-intent-taxonomy.md	Phase 1（分類）	ユーザーの表現から対象スキル／ワークフローへの完全な対応表。フォールバック、優先順位の判断基準、複数意図の分割ルールを含みます。
references/02-preflight-overview.md	Phase 0（調査）	high_level_overview の呼び出し方法と、ルーティング判断の根拠となる簡易的な shapeStructure／tokenOverview の読み取り方法です。

scripts/（execute_code に貼り付けるテンプレート）

なし。ルーターは変更を行わず、再利用可能な変更用テンプレートも必要ありません。execute_code の使用は、§14 にあるインラインの読み取り専用調査スニペットのみです。

workflows/ (ネイティブインストールに同梱)

ネイティブ版の Claude Code をインストールすると、このスキルのバンドルには workflows/ も含まれます。ここには、複数のスキルを組み合わせた7つのパイプライン（§8 のワークフロー対象：routing、design-system-bootstrap、brief-to-screen、brief-to-deck、code-to-penpot-sync、figma-migration、accessibility-gate）があり、それぞれ README.md（説明文）と pipeline.json（決定的なステップリスト）で構成されています。ワークフローにルーティングする際は、ここからそのファイルを開いてください。シードポインター方式のインストールでは、キットのルートにある workflows/ に格納されています。

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