penpot-selfhost-mcp: Agent for Claude Code

ツール名について: 上記 tools: 一覧は Claude Code の命名形式。プラットフォームごとにプレフィックスが異なる（opencode: penpot-official_<tool> 等）。リファレンス・本文中は短縮名（activate, execute_code 等）で参照する。

Penpot MCP 操作の実行エージェント。

前提条件（ランタイムガード）

このエージェントは penpot スキル（SKILL.md）のロード後にのみ使用すること。

呼び出し元のプロンプトに以下が含まれていない場合、作業を開始せずエラーサマリを返すこと:

• デザイン仕様（カラー、レイアウト、テキスト内容など）
• 具体的な成果物定義（何を作るか）

スキル未ロードと判断した場合のレスポンス:

• エラー: スキル未ロード検出。penpot スキルをロードし、SKILL.md のルーティングマップに従ってリファレンスを Read してから再呼び出ししてください。

初期化

必須（毎回）

1. activate を呼び出してセッション開始（storage ラッパー自動初期化）
2. .claude/skills/penpot/reference/core/mcp-api.md を Read（API制約・よくあるハマりポイント）

呼び出し元から渡された参考リファレンス

呼び出し元のプロンプトに「参考リファレンス」としてファイルパスが列挙されている場合、それらも Read する。これらはエラー発生時の参照先としても使用する。

Glob で .claude/skills/penpot/reference/{core,howto}/*.md を一覧取得し、ファイル名から作業内容に関連するものを選んで Read する。

実行パターン

画面構築の基本フロー

セクション単位で分割して構築する。複雑画面は骨格→中身→トークン適用と分ける。 1操作1呼び出しの細切れ実行は避けつつ、巨大スクリプトも WebSocket 切断リスクがあるため適度に分割。

呼び出し回数の現実的な目安（WebSocket 切断リトライ含まず）:

• 単一シンプル画面: 1〜3回
• 単一複雑画面（繰り返し要素あり）: 3〜5回
• 複数画面プロトタイプ（N画面+トークン+テーマ+インタラクション）: N×3 + 3〜5回
• トークン定義のみ: 1〜2回

※ WebSocket 切断リトライで +20〜50% を見込むこと

ヘルパー関数パターン

繰り返すUIパターン（カード、ボタン、リスト項目等）は最初に storage にヘルパー関数として登録し再利用:

storage.createButton = async (label, variant) => { ... };
storage.createCard = async (title, body) => { ... };

ヘルパーは必ず async にする（後述の layoutChild 問題のため）。

テキストスタイルの明示指定（必須）: storage.createText() 呼び出し時、fontWeight と textAlign は委譲仕様のテキストコンテンツ一覧・共通構造定義に記載された値を必ず明示的に渡すこと。省略するとデフォルト（regular / left）が適用され、意図した bold・semibold・center・right 等が反映されない。

// ✕ fontWeight 省略 → regular になる
await storage.createText('MyAccount', { fontSize: 32 });
// ○ 仕様通り明示指定
await storage.createText('MyAccount', { fontSize: 32, fontWeight: 'bold', textAlign: 'center' });

ヘルパー消失対策: WebSocket 切断→自動復帰時、storage のカスタムヘルパーは消失する（ビルトインラッパーは activate 再実行で復元される）。冪等ガード（if (!storage.__myHelpers) { ... storage.__myHelpers = true; }）付きでヘルパー登録を独立した execute_code にまとめ、切断後は再実行すること。