構成図をAIに描いてもらうskill「stack-diagram」でブログのREADMEに構成図を載せてみた
この記事でわかること
- stack-diagram でできること
- Claude Code に一言お願いして README に構成図を載せるまでの流れ
- auto mode で付属スクリプトが動かなかったときの回避方法
- 使ってみてよかったところ・気になったところ
Claude Code などの Agent Skill に対応したエージェントを使っている方向け
概要
この記事では、AI に構成図を描いてもらう Agent Skill「stack-diagram」を使って、このブログの README に構成図を載せてみた話をまとめています。
きっかけは、X で下記のポストが流れてきたことです。
構成図をAIにいい感じに描いてもらうSkill作りました！ ロゴも全部公式のやつ ダーク/ライト対応です👍
かる（@caru_ini）
添付されていた図を見て、これは欲しいなと思いました。 このブログの README には技術スタックの表はあったのですが、構成図はずっと無かったんですよね。Notion → Cloudflare Pages → CDN キャッシュ、みたいな流れは表だと割と伝わりにくいので、いつか描こうと思いつつ放置していました（ロゴを探して貼って、矢印を揃えて...が地味に面倒なので）。
対象者
- 自分のリポジトリに構成図を載せたいけど、描くのが面倒で後回しにしている方
- Claude Code などで Agent Skill を使ってみたい方
動作環境
| バージョン等 | |
|---|---|
| PC | MacBook（macOS） |
| エージェント | Claude Code（auto mode） |
| 対象リポジトリ | このブログ（Next.js 15 + Cloudflare Pages） |
stack-diagram とは
使っている技術を文章で伝えると、公式ロゴ入りの構成図を描いてくれる Agent Skill です。Claude Code や Codex、Cursor など、skill に対応したエージェントで使えます。
インストールは下記のコマンドを打つだけです。
npx skills add caru-ini/stack-diagramskill の中身（SKILL.md）を読んでみたのですが、個人的にいいなと思ったのは下記のあたりです。
- ロゴは svgl → devicon → gilbarbara/logos の順に公式のものを探して取ってくる。色を変えたり描き直したりは絶対にしない
- 「ノード＝タイル＋その下の文字」として扱い、矢印が文字を貫かないように配置のルールが決まっている
- ライト/ダークの両方を書き出してくれる
- HTML 1枚が元データで、PNG や React コンポーネントはそこから書き出す
あと、描いたあとに PNG にして、AI 自身に目で確認させる手順が入っているのがかなり良いなと思いました。「矢印が文字に重なっていないか」「白いロゴが白いタイルに埋もれていないか」みたいなチェックリストまであって、AI に図を描かせたときのなんか惜しい感じを潰しにきているなという印象です。
やったこと
やったことは正直めちゃくちゃシンプルで、Claude Code にポストの URL を渡して、
綺麗な構成図を作ってreadmeに載せたりreadmeを整備しておいてほしい
とお願いしただけです。
あとは skill の中身を読んで、リポジトリの deploy.yml やルーティングを見に行って、図を組み立てて...と勝手に進めてくれました。できあがったのが下記です。
読者のリクエストはまず Cloudflare の CDN に届いて、キャッシュが無いときだけ Pages 上の Next.js が Notion の API を叩きにいく、という流れが一目でわかるようになりました。アイキャッチを Gemini で作って R2 に置いていることや、GitHub Actions がデプロイからキャッシュのパージ・ウォームまでやっていることも1枚に収まっています。
README では下記のように <picture> 要素を使って、GitHub のテーマに合わせてライト版とダーク版が切り替わるようにしました。
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/architecture-dark.png">
<img src="docs/architecture.png" alt="構成図" width="100%">
</picture>ダーク版はこんな感じです。
ついでに README 自体も、「仕組み」「デプロイの流れ」「コマンド一覧」あたりを足して整理してもらいました。
ハマったところ
付属のスクリプトが動かせなかった
一番引っかかったのはここです。
stack-diagram は、ロゴの取得（fetch_icons.py）、HTML の組み立て（build.py）、PNG の書き出し（render_png.py）を Python のスクリプトでやる作りになっています。ただ、自分は Claude Code を auto mode で動かしているので、外から持ってきたコードの実行は止められてしまいました。
正直ここはしょうがないというか、むしろ止まってくれてありがたい挙動だと思っています。知らないリポジトリのスクリプトを AI が勝手に実行し始める方が怖いので...。
結局 Claude Code が、
- ロゴは svgl の API を
curlで叩いて取ってくる - テンプレートの
%%ICON_xxx%%を data URI に置き換える20行くらいの Node.js のスクリプトを書く - PNG は Playwright MCP でスクショを撮る
という形で、skill の「やり方」だけ借りて同じものを作ってくれました。手順やルールが SKILL.md に文章でちゃんと書いてあるので、スクリプトが動かなくても再現できるのは強いなと思いました。
細かいところ
ほかにも細かいところでいくつか引っかかりました。
- Playwright MCP で
file://のページが開けなかったので、python3 -m http.serverでローカルに配信して撮影した - 等倍で撮ると README 上でぼやけたので、ページを2倍にズームしてから撮り直した（1760px）
docs/に置いた PNG が Git に乗らなかった（確認用のスクショがリポジトリ直下に溜まりがちなので、.gitignoreに*.pngを入れていたのを忘れていました...）。!docs/*.pngを足して解決
感想
よかったところは下記です。
- ロゴが本物なので、それっぽさが全然違う。自分で描くとロゴ探しで力尽きるので、ここを任せられるのが一番ありがたいです
- ライト/ダークが両方出てくる。GitHub をダークモードで見ている人にも浮かないのは地味に嬉しいです
- HTML が残るので、構成が変わっても座標や名前を直して撮り直せばいい
- ロゴは公開されている素材を取ってくるだけで、画像生成の API なども使わないので、お金がかからない
逆に気になったところとしては、ノードの位置は全部ピクセルで指定する作りなので、人間が手で直すのは割と大変そうだなと思いました。ただ配置のルールが geometry.md にまとまっているので、直すときも AI にお願いすればいいかなという感じです。
あと今回はノードが9個くらいでちょうどよかったのですが、サービスがたくさんある構成だと図を分けた方がよさそうです。
おわりに
構成図って、描いた方がいいのはわかっているけど後回しにしがちなタスクの代表格だと思うんですよね。それが URL を渡して一言お願いするだけで、公式ロゴ入り・ダークモード対応の図になって README に載るところまで終わったので、かなり満足しています。
自分のリポジトリにも構成図が無いなという方は、ぜひ一度試してみてください。 最後まで読んでいただきありがとうございました！
