「アーキテクチャ図を描いて」とAIに頼むと、たいてい角丸の四角が均等に並んだ、どこの資料にも属さない図が返ってくる。cathrynlavery/diagram-design（MIT・2026-08-14時点★16,028）は、この「AIに図を頼むと角丸ボックスになる」問題を、汎用の作図AIではなく 27種の型と機械強制されたスタイル規約 で解こうとしたエージェントスキルだ。Claude Code／Codex／Pi のいずれにもプラグインとして入る。運用の全体像はClaude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引きにまとめてある。
30秒でわかる diagram-design
・型は27種、コードで固定——references/type-*.md はちょうど27ファイル。GitHubの説明文が29なのは数え方の違い
・自己完結の境界を実測——同梱HTML 103枚で <img> 0件・@import 0件、scriptは4枚のみ。ただし103枚すべてが Google Fonts のCSSを1本読む
・規約は文章でなくCIで強制——CIの19ステップのうち図の品質に直接効く8本を回し全合格
・壊した図は6通りすべて差し戻された——同梱 self_check.py に遠隔画像・script・onload属性などを注入し、6件すべて exit 1
・既存Mermaidは「変換」でなく「描き直し」——日本語フローチャートを同梱パーサに通すと11ノード11エッジを解析し「上限9を超過」「style 5個破棄」と報告
diagram-designとは——類似の作図スキルとの棲み分け
本稿の実測は2026-08-14時点のスナップショットです
上流の更新が速く、2026-09-10 時点では references/type-*.md は 40ファイル（GitHubの説明文は「38 editorial diagram types」）、同梱アセットHTMLは 162枚、スター数は 37,007 まで増えています。以下の型27種・同梱103枚という数値は2026-08-14に実際に走らせた結果であり、設計の考え方（型をコードで固定する・規約をCIで強制する・異常系を差し戻す）は変わっていませんが、個数そのものを引用する場合は最新の main で数え直してください。
2026年4月16日作成のリポジトリ。当時の伸びは急で、Internet Archive に残るリポジトリページで確認すると 2026-08-13 05:53 UTC でスター11,497・フォーク728・ウォッチャー43、その約28時間後の 2026-08-14 09:32 UTC ではスター16,028・フォーク961・ウォッチャー64 と、1日で4,500以上増えている。MITライセンス、.claude-plugin/plugin.json のバージョンは 2.3.3。
中身は素朴で、スキル本体はMarkdownの集合体だ。SKILL.md が振る舞いと選定ルールを、references/ が型ごとの仕様書を持つ。描くのはエージェント自身で、レンダラは介在しない。だから規約を人間の言葉で決め、機械で検査する構成になる。
作図系のClaude Codeスキルは既にいくつもあるが、入力と出力の向きで整理すると棲み分けがはっきりする。
| diagram-design | Archify | oh-my-mermaid | 素のMermaid | |
|---|---|---|---|---|
| 主な入力 | 自然文／draw.io／Mermaid | 自然文 | 既存コードベース | 手書きのDSL |
| 出力 | 自己完結HTML＋インラインSVG（PNG/SVG書き出し可） | 自己完結HTML（PNG/JPEG/WebP/SVG） | .mmd ＋ Markdown文書 |
描画結果 |
| 型の数 | 27種（＋primitive 4種） | 5種 | Mermaidの図種に準拠 | Mermaidの図種に準拠 |
| ブランド適用 | サイトURLからトークン抽出＋WCAG AA検査 | ダーク/ライト自動切替 | テーマ設定に依存 | テーマ設定に依存 |
| 規約の強制 | CI 19ステップ＋同梱 self_check.py | — | — | — |
| 配布 | Claude Code／Codex／Pi のマーケットプレース | zip配布 | npm ＋ 各ツールへの setup | ライブラリ |
| 向いている用途 | 公開する記事・スライド・提案書の版面 | 手早く技術図を1枚 | コードベースの構造文書化 | 開発内のやり取り |
oh-my-mermaid は「コードから図を起こす」、Archify は「言葉から手早く1枚」、diagram-design は 「出した図をそのまま公開できる版面にする」 に重心がある。本文へ直接埋め込むだけなら素のMermaidで足りるが、提案書に貼る図を毎回Figmaで整えているなら置き換えの候補になる。
「27」という単位——数え方と、型を増やさない工夫
references/type-*.md は ちょうど27ファイルで、READMEも本文3か所すべてで「27 visual types」と書く。verify-semantic-motion.py も「7つの意味パターンが27種の視覚型へ独立にルーティングされる」ことを検査しており、27はコードで固定された数字だ。GitHubサイドバーの説明文が「29 editorial diagram types」なのは、誤りというより 数え方の差 だ。
| 数え方 | 数 | 何を数えたか |
|---|---|---|
references/type-*.md |
27 | 型ごとの仕様書。スキルが「型」として扱う単位 |
| README本文の記述 | 27 | 本文3か所すべてで一致 |
assets/index.html のギャラリー項目 |
36 | <span class="eyebrow"> の数。縦組み・ターミナル装飾・取り込み例・モーション例を個別に数える |
| GitHubリポジトリの説明文 | 29 | 「29 editorial diagram types for Claude Code」。Internet Archive の2026-08-13スナップショットで確認。リリースタグは未作成でひも付け先が無い |
押さえるべきは「27が実装上の単位」の一点だ。なお references/ には注釈・アイコン・手描き風・ターミナル装飾の primitive が4種 あり、型を増やさず既存の型に重ねる装飾として扱われる。
27を保つ工夫が、v2.3で入った 意味パターン（semantic patterns） だ。ファンインするキュー、ステージ枠、非構造入力の変換、対になるポリシートレース、安全な舗装道路（paved road）、ガバナンスのカタログ、多層の防御——この7つは「振る舞い」であって型ではない。発火条件・部品・要素数の予算・アンチパターン・静止時のフォールバック・最も近い視覚型 が semantic-patterns.md に定義され、キューを描くときも新設せず既存の型へ寄せる。
モーションも型を増やさない。none／reveal／step／loop の4モードで 既定は none。静止first frameを必ず持ち、タイミングは決定論的、OSで「視差効果を減らす」が有効なら静止フレームだけを見せて再生コントロールを切る。許されるスクリプトは template-motion.html の正規コントローラのみだ。
diagram-designの主張は実測に耐えるか——自己完結性・CI・異常系
この種のスキルで気になるのは、規約がREADMEのポエムで終わっていないかだ。自己完結性・CIゲート・自己検査の3点を、2026-08-14時点の main で実際に走らせた。
同梱103枚——外部依存は書体1本だけ
READMEは「ビルド手順も、JavaScriptも、外部画像への依存も無い」と書く。skills/diagram-design/assets/*.html 103枚を機械的に数えた。
| 項目 | 実測値（103枚） | 何を意味するか |
|---|---|---|
<img> タグ |
0件 | 外部・ローカルとも画像ファイルに依存しない。図はすべてインラインSVG |
CSS @import |
0件 | スタイルシートの連鎖読み込みが無い |
インライン <script> |
4枚のみ | 静止99枚はscriptゼロ。モーションは明示的なopt-in |
| 外部ホスト | 1つ（fonts.googleapis.com） |
書体のみ。ホスト名完全一致でlintが検査 |
| 書体フォールバック | 全変数にあり | オフラインでは劣化するが破綻しない |
| 最小テンプレのサイズ | 3,253バイト | template.html。実例（example-*.html 96枚）は5,080〜30,457バイト |
scriptを含む4枚はギャラリーの index.html、モーション例2枚、モーションテンプレート1枚。静止図99枚はscriptを1行も持たない。ただし 103枚すべてが https://fonts.googleapis.com/css2?... を1本読み込む。原文は “no build step, JavaScript, or external image dependency” で “image” の一語が効いており、README自身もSVGエクスポート時のGoogle Fonts注入を明記している。隠された依存ではない。
判断材料になるのはフォールバックだ。--font-sans は 'Geist', system-ui, sans-serif、--font-serif は 'Instrument Serif', serif、--font-mono は 'Geist Mono', ui-monospace, monospace。エアギャップ環境では書体が差し替わるだけで版面は崩れない。
CIのゲート8本を回す
検証スクリプトは scripts/ に並び、GitHub Actions の ci.yml から呼ばれる。ci.yml がPythonスクリプトを走らせるステップは全部で19本あるが、そのうち図の品質に直接効く8本を選んでローカル再実行した（verify-semantic-motion.py だけは、CIが --markdown-only と --example-only に分けて呼ぶところを引数なしで通している。他の7本はCIと同じ引数）。
git clone --depth 1 https://github.com/cathrynlavery/diagram-design.git
cd diagram-design
python3 scripts/verify-docs-sync.py # 説明文・ギャラリー到達性・READMEツリーの同期
python3 scripts/verify-geometry.py --all # 4pxグリッド等の幾何検査
python3 scripts/lint-skin.py --all --baseline # 配色・外部資源・a11y契約
python3 scripts/verify-motion.py --shipped # 出荷済みモーションHTML
python3 scripts/verify-semantic-motion.py # 意味パターン→型のルーティング
python3 scripts/verify-mermaid-import.py # Mermaid取り込みの文法・上限・異常系
python3 scripts/verify-drawio-import.py # draw.io取り込み（DTD拒否含む）
python3 scripts/verify-sequence-oauth.py # シーケンス型のALT構造
8本すべてが合格した（終了コード0）。verify-geometry.py --all は103ファイル検査で指摘0、lint-skin.py は101検査20除外で指摘0。verify-mermaid-import.py は敵対的ラベルの不活性化や、文書化されたexit 2経路の発火まで見ている。
lint-skin が禁じているもの（ソースのメッセージ文字列から抽出）
配色以外にも、単一ファイル安全性とアクセシビリティの契約が同じlintで守られている。純黒 rgb(0,0,0) の使用、CSS @import、外部HTTP(S)の <link>／src、フラグメント以外の CSS url()、<svg> 上の実行可能属性はいずれも拒否される。加えて <svg> は先頭子要素として非空の <title> と <desc> を持ち、aria-labelledby がその順で両IDを指し、IDは図ごとに接頭辞を持つこと（id="title" のような裸のIDは不可）が要求される。モーションHTMLのコントローラは template-motion.html と完全一致でなければ通らない。
ただしCIの緑だけでは見えない事実がある。 --baseline を外すと終了コード1で46件——「パレットに無い色」（is not in the style-guide palette）36件と「許可色から派生していない色」（is not derived from an allowed palette color）10件で、指摘は11ファイル。baselineファイル（scripts/lint-skin-baseline.txt）には20ファイル名が並び、現時点で指摘の無い9ファイルも含む。教科書的なbaseline運用で欠陥ではないが、「全アセットがトークンだけで塗られている」とまでは言えない。取り込む前に一度外して見ておきたい。
壊した図を6通り食わせる
上のゲートはコントリビューション用だが、エージェントが自分の出力を検査する縮小版が scripts/self_check.py として同梱されている。無改変の example-architecture.html を対照群に、6通りの改ざんを食わせた。
cp skills/diagram-design/assets/example-architecture.html clean.html
python3 skills/diagram-design/scripts/self_check.py clean.html # → OK / exit 0
# 遠隔画像を注入
sed 's|<svg |<img src="https://evil.example.com/t.png"><svg |' clean.html > a.html
python3 skills/diagram-design/scripts/self_check.py a.html # → FAIL / exit 1
結果は 6件すべて exit 1、対照群のみ exit 0。返るメッセージも具体的だ。
| 注入した改ざん | self_check の応答 |
|---|---|
遠隔 <img> を挿入 |
remote reference on <img>: https://evil.example.com/... |
インライン <script> を追加 |
script 1 must carry only the canonical data-diagram-controls attribute |
<svg> に onload を付与 |
executable attribute onload on <svg> |
SVGの <title> を削除 |
svg 1 title must be its first child ほか3件 |
<desc> を空にする |
svg 1 needs non-empty title and desc |
フォント配信元を fonts.googleapis.com.evil.example に |
remote stylesheet is not the approved Google Fonts /css2 URL |
許可ホストの判定は部分一致ではなくホスト名の完全一致で、類似ドメインでは抜けられない。守備範囲も正確に切られている——HTMLの <head> 側の <title> を消しても exit 0 で通るのは、守るのがSVGのアクセシブル名（<svg> 直下の <title id="...">）であってページタイトルではないからだ。
導入と運用——3系統への配布、常駐コスト、ブランド取り込み
配布は3系統のプラグインマーケットプレース経由で、いずれも skills/diagram-design/ という同じディレクトリを読む。
# Claude Code（マーケットプレース追加 → インストール）
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design
# Codex
codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design
# Pi（Gitからの非固定インストール）
pi install https://github.com/cathrynlavery/diagram-design
更新の追随は系統ごとに違う。Claude Codeはサードパーティ製マーケットプレースの自動更新を既定で無効にしており、/plugin → Marketplaces → diagram-design → Enable auto-update を一度有効化しないと更新が降ってこない。Piには自動更新が無く pi update --extensions を手で叩く前提だとREADMEが明記する。スタイルガイドを編集するなら、更新で references/style-guide.md が上書きされうるためクローンしてシンボリックリンクを張る「editable install」が案内されている。組織のGitHubマーケットプレース（Cowork）はprivate/internalリポジトリを要求するので、自組織へミラーしてから接続する。版の固定は リリースタグが未作成（plugin.json の 2.3.3 のみ、GitHub Releases は空）なのでコミットSHA頼みだ。
インストール後は自然文で頼めばよく、エージェントが型を選んでHTMLを書き出す。ただし初回だけゲートが挟まる——新規プロジェクトで style-guide.md がカスタマイズ済みかを確認し、既定のままなら「オンボーディングを走らせるか、トークンを手で貼るか、既定で進めるか」を聞いて一時停止する。既定配色は style-guide.md の言葉で「白（white-smoke）の紙・ジェットブラックの文字・アトミックタンジェリンのアクセント・ブルースレートの副次テキスト」で、そのままでも見られる水準にはある。
PNG書き出しだけは追加セットアップが要る。pip install playwright && playwright install chromium が前提で既定倍率は2×。書き出したSVG/PNGは図だけで -full 版の編集カードやヘッダは含まれず、編集レイアウトごと欲しければ全ページ撮影かPDF出力を使う。
常駐コストは「37KBが常時」ではない
SKILL.md は37,408バイト、references/ 全体は429,282バイト（約419KB）。毎回丸ごと載れば負担だが、READMEが言う「プログレッシブ・ディスクロージャー」は3段のはしごだった。
| 段 | 何が載るか | 実測サイズ | いつ |
|---|---|---|---|
| 1段目 | SKILL.md frontmatter の name + description |
614バイト | 常時（スキル一覧として） |
| 2段目 | SKILL.md 本体 |
37,408バイト | 作図系の依頼で起動したとき |
| 3段目 | 選ばれた型の references/type-*.md 1本 |
中央値2,790バイト（最小991／最大29,984） | 型が確定したとき |
参照全体が載ることはまず無い。最大の primitive-icons.md は単体で106,768バイトと参照全体の約4分の1だが、アイコンを明示的に使うときしか読まれない。つまり 「37KBが常時」ではなく「作図依頼のときに37KB＋数KB」 が正しい。測り方はClaude Skillsとは｜「スキル=フォルダ」の仕組みと作り方・使い方を徹底解説の構造をそのまま当てはめればよい。
サイトURLからブランドトークンを引く
「onboard diagram-design to https://yoursite.com」と頼むと、エージェントがトップページを取得し、パレットとフォントスタックを意味的な役割へ割り当てる。<body> の背景が paper、主要な文字色が ink、副次テキストが muted、カード類が paper-2、最も使われるブランド色（CTA・リンク・見出し）が accent。フォントは <h1> が title、<body> が node-name、<code> が sublabel だ。
書き込み前に ink と paper のコントラストをWCAG AAで検査し、9〜12pxという図中の実サイズで基準を割る色があれば調整値と理由を出す。適用後は「忠実度レシート」——サンプリングしたURL、色の役割の対応、フォントファミリーとウェイト、配信元URL、フォールバックの有無——が出る。取得できなかったものを黙って差し替えない設計だ。以降の図は #eb6c36 のような生の値ではなく accent を参照するため、スタイルガイドの表を書き換えるだけで27種すべてに反映される。
既存資産の取り込み——日本語のMermaidで試した
既存資産の扱いは「変換」ではなく「描き直し」だ。引き継がれるのは コンポーネント・関係・グルーピング・方向 だけで、元の座標・配色・フォント・draw.ioの斜め線・Mermaidの自動レイアウトは捨てられる。
当て先は4つのダイヤルで決める。フォーマット（html／svg／png／html+png）、サイズ（doc-inline〜slide-16x9〜print-a4-landscape など9種、viewBoxだけでなく文字サイズのランプも変わる）、詳細度（faithful ≤24ノード／balanced ≤12／simplified ≤7）、読み手（engineer／mixed／executive——ノード数ではなく語彙が変わり、Auth Service / JWT · RS256 · :8443 が Sign-in になる）。この詳細度の上限が実質の制約で、大きな既存図は必ずどこかを落とすが、何を統合し何を落としたかは「忠実度台帳」に出る。
前段だけはエージェント任せではなく、scripts/mermaid_extract.py という実行可能なパーサだ。日本語で動くのかを確かめるため、当サイトの既存記事に載っている日本語のフローチャート——全角の判断ノード、<br/> による改行、style ... fill:#4CAF50 の色指定を含む実物——を投げた。
python3 skills/diagram-design/scripts/mermaid_extract.py jp-decision.mmd
# 1 diagram(s): [0] flowchart (11n/11e)
# - shapes: {'rect': 7, 'rhombus': 4}
# - budget: nodes OVER (max 9), edges ok (max 12)
# - discarded: 5 style directives, 0 click handlers
読み取れることが4つある。日本語ラベルはそのまま保持され、<br/> は digest 上で ⏎ になる（--json のIR側では \n のままで情報は落ちない）。rect 7個・rhombus 4個という内訳から判断ノードを正しく識別している。budget: nodes OVER (max 9) は描き直す前に推奨ノード上限の超過を警告する。discarded: 5 style directives は元の色指定を5個捨てたと明示する——捨てたことを黙らないのが特徴だ。
digest には「ハブ（注目候補）」「入口ノード」「終端ノード」まで出る。当サイトの図では「チームで運用するか？」が次数4で最大のハブと判定された。アクセント色を当てる先の候補、という意味づけだ。draw.io側も .drawio / .drawio.xml / .drawio.png（埋め込み図）/ .drawio.svg と圧縮ペイロードに対応し、verify-drawio-import.py はDTD拒否・PNG境界・資源上限まで検査していた。
キュー・ポリシートレース・信頼境界など"] B -->|"いいえ"| D["視覚型27種から直接選ぶ"] C --> D D --> E{"元ソースがあるか"} E -->|"draw.io / Mermaid"| F["描き直し
4つのダイヤルで当て先を決める"] E -->|"自然文のみ"| G["新規作図"] F --> H["自己完結HTMLを書き出す"] G --> H H --> I{"モーションを明示要求か"} I -->|"いいえ・既定"| J["静止HTML
scriptなし"] I -->|"はい"| K["template-motion.html の
正規コントローラのみ許可"] J --> L["self_check.py で自己検査"] K --> L
まとめ——効くのは型の数より「規約が機械で守られているか」
図の品質が「そのまま公開できるか」で決まる以上、最後に効くのは型の数ではない。diagram-design の面白さは、27という数字より、その27を崩さないための検査が実際に走るコードとして同梱されている点にある。回した8本のゲートは全合格し、壊した図は6通りすべて差し戻された。
一方で、baselineを外せば配色の逸脱が46件見え、詳細度の上限は大きな既存図を必ず削り、版の固定はコミットSHA頼みだ。いずれも「規約を機械で守る」設計と地続きの制約で、把握して使えば見積もりを外さない。
参照ソース
・cathrynlavery/diagram-design — GitHubリポジトリ（README・SKILL.md・scripts/・skills/diagram-design/）
・diagram-design 公式ギャラリー（cathrynlavery.github.io/diagram-design）
・Agent Skills — Anthropic 公式ドキュメント
・本稿の実測: 2026-08-14 時点のツリー（コミット e1d47bb0、plugin.json v2.3.3）を対象に検証した。同梱アセット103枚の集計、ci.yml が呼ぶゲート8本の再実行、self_check.py への異常系入力6件、mermaid_extract.py への日本語Mermaid入力（当サイトのプロンプトエンジニアリングとハーネスエンジニアリングの違いに載せている11ノードのフローチャート）はいずれも本稿のために実施した。本文の引用文字列・ファイル名・数値は2026-09-10に同ツリーへ再度突き合わせ済み。リポジトリのスター数等は Internet Archive のスナップショットで確認した
