Mermaidでうまく図解できなかったので、図解を作るエージェントスキルを書いた
Algomatic のエンジニアが、LLM に直接 Mermaid を描画させるのではなく、情報設計を先行する「図解ブリーフ」プロセスを組み込んだエージェントスキルを開発・共有した事例。
キーポイント
従来の LLM 活用における課題の特定
単純に Mermaid を描画させる指示では、ノードの過多や意図しない矢印など、情報設計が欠落した不適切な図解が生成されることが多いと指摘。
情報設計先行のアプローチの実装
描画前に「目的」「読者」「主メッセージ」などを整理するステップを設け、LLM に指示を出すことで質の高い図解案を作成するスキルを開発。
外部記憶としての図の役割と負荷
図は外部記憶として機能するが、設計が悪い場合は逆に認知負荷を高めるため、適切な情報設計プロセスの重要性を理論的背景から説明。
概念整理に特化したエージェントスキルの設計
「zukai-creator」は画像生成や装飾ではなく、テキストから要素・関係性を抽出し構造を整えることに焦点を当てた概念図解の設計支援ツールです。
範囲を絞ることで出力品質を高める
数値グラフや完成イラストなどのスコープ外項目を明確に排除することで、スキルの責務が広がりすぎず、図解前の構造整理という目的に集中しています。
図解は入れれば必ず効くわけではない
図解は外部記憶として機能しますが、設計が悪いと認知負荷となり逆効果になるため、役割定義から検証までの体系的なプロセスが必要です。
Agent Skills の階層的な情報開示（Progressive Disclosure）
エージェントはまず名前でスキルを発見し、必要に応じて詳細手順や参照ファイルを段階的に読み込む設計により、不要な情報を避けて効率的にタスクを実行できる。
影響分析・編集コメントを表示
影響分析
この記事は、単なるツールの紹介に留まらず、AI エージェント開発における「思考の構造化」の重要性を浮き彫りにしています。現場で即座に適用可能なスキル提供を通じて、LLM の出力品質を向上させるための具体的なプラクティスを示しており、開発者や技術リーダーにとって実用的な知見となります。
編集コメント
LLM に図を描かせる際、プロンプトの工夫だけでなく「情報設計」を先行させるという視点は、AI エージェント開発において非常に示唆に富んでいます。
想定読者：AI エージェント用のスキルを自作したい人、記事やドキュメントの図解づくりを AI に任せたい人
実装：skills/zukai-creator/SKILL.md
こんにちは。Algomatic でソフトウェアエンジニアをしている Go（@53able）です。
最近は、自作したエージェントスキルを Slack で共有して、社内の人に触ってもらうことを続けています。大きな取り組みというより、日々の小さな配布です。それでも、自分の作ったスキルが誰かの作業の型になったり、少しでも手間を減らしたりするなら、けっこう意味があるなと感じています。
今回は、テキストから図解案を作るエージェントスキル zukai-creator を作った話です。
私は長くフロントエンドエンジニアをしてきました。UI を作る仕事では、実装そのものだけでなく、状態、データの流れ、ユーザーの理解をどう整理するかをよく考えます。最近は AI を前提にした開発が増え、フロントエンドだけを見ていればよい場面は減りました。既存の得意領域を軸にしつつ、バックエンド、ドキュメント、設計、運用まで身軽に動く必要があります。
その中で地味に困っていたのが、説明用の図解です。
以前は、LLM（大規模言語モデル）に「Mermaid で図解して」と頼むだけで済ませることが多くありました。簡単なフローならそれで十分です。ただ、少し複雑な説明になると、次のような問題が出ました。
- ノードが増えすぎて、読む順番がわからない
- 矢印の向きやラベルが、意図した説明とずれる
- 本文の要約にはなっているが、理解を助ける図にはなっていない
- 結局、人間側が構造を考え直す必要がある
問題は Mermaid そのものではありませんでした。図にする前の情報設計を飛ばして、いきなり描画形式を指定していたことが問題でした。
そこで、図解を作る前に「目的」「読者」「主メッセージ」「要素」「関係性」「グループ」を整理するアプローチでスキルを作りました。
この記事中の図解も、zukai-creator で作った図解ブリーフをもとに作成しています。たとえば、冒頭の問題意識を図にすると次のようになります。
image従来の Mermaid 直指定と zukai-creator の違い
図：zukai-creator の図解ブリーフに沿って作成したラフ図解
この記事では、なぜこのスキルを作ったのか、どう設計したのか、図解づくりの考え方にどんな研究背景があるのかを書きます。
- 作ったもの
- Agent Skills の形式に合わせる
- インストール方法
- 図解は「昔からあるから正しい」わけではない
- 図解の作り方に関する研究背景
図解は、入れれば必ず効くわけではない
- 余計な探索を減らす
- 図は外部記憶になるが、設計が悪いと負荷になる
- 図解の入れすぎにも注意する
- zukai-creator の全体設計
Step 1: 図解の役割を定義する
- Step 2: ソースを図解の部品に分解する
- Step 3: 図解パターンを選ぶ
- Step 4: 低忠実度のラフを作る
- Step 5: 理解のためにスタイリングする
- Step 6: 図解ブリーフを検証する
- Step 7: レビューと改訂を行う
- 出力フォーマットを固定した理由
- 作ってみて感じたこと
- まとめ
- 参考
作ったもの
zukai-creator は、テキスト・メモ・記事・スライド原稿などを読み、概念図解の設計案を作るためのエージェントスキルです。
スキルの説明は次のように定義しています。
name: zukai-creator
description: テキスト・メモ・記事・スライド・説明文から、要素・関係性・グループ・ラベルを抽出し、図解パターンとスタイリングルールを選んでわかりやすい日本語の概念図解を作る。図解・概念図・説明図・スライド用ビジュアル・ビジュアル要約を作るときに使う。定量データのグラフ、本格的なインフォグラフィック制作、画像生成、装飾的なイラストには使わない。
対象にしているのは、数値グラフや完成イラストではなく、概念を整理する図です。
想定用途は次のようなものです。
- 記事の説明図
- スライド用の概念図
- ドキュメント内のプロセス図
- ホワイトボードのラフ案
- 施策や業務フローの構造整理
- レビュー前の図解ブリーフ作成
逆に、次のものはスコープ外です。
- 定量データのグラフ作成
- 完成イラストの生成
- 装飾中心のビジュアル制作
- 画像生成 AI 向けの最終プロンプトだけを作る作業
範囲を絞ったのは、スキルの責務を広げすぎると出力がぼやけるからです。zukai-creator の役割は、きれいな画像を一発生成することではありません。図解にする前の構造を整えることです。
Agent Skills の形式に合わせる
同じ作業を LLM に何度も任せるなら、長いプロンプトを毎回調整するより、手順や参照資料をまとめて管理したくなります。Agent Skills は、そのための軽量フォーマットです。もともとは Anthropic が開発し、現在はオープンな標準として公開されています。
基本は、SKILL.md を中心にしたフォルダです。「いつ使うか」「どう進めるか」を書き、必要なら参照ファイル、テンプレート、スクリプトも同じディレクトリに置きます。普通のプロンプト集というより、エージェントに渡す小さな作業パッケージに近いです。
必ず JSON 形式で返してください。translation フィールドのみ。他のフィールド (technical_terms 等)は一切追加しないこと — 余計なフィールドを書こうとして本文翻訳がトークン上限で打ち切られる事故を防ぐため:
{"translation": "翻訳全文"}
zukai-creator も、この形式に合わせました。Git で管理しやすく、チーム内で配布したり、別のエージェント環境に持ち込んだりしやすいからです。
公式仕様では、スキルは少なくとも SKILL.md を含むディレクトリとして定義されます。
zukai-creator/
├── SKILL.md
├── scripts/
├── references/
└── assets/
SKILL.md には YAML frontmatter と Markdown 本文を書きます。必須フィールドは name と description です。特に description は、エージェントが「このタスクでスキルを使うべきか」を判断するための入口になります。
今回の構成は次の通りです。
- SKILL.md: スキルのメタデータと実行手順
- references/pattern-catalog.md: 図解パターンの選択基準
- references/review-checklist.md: 最終レビュー用のチェックリスト
- assets/diagram-brief-template.json: 図解ブリーフのテンプレート
- scripts/check-diagram-brief.py: JSON ブリーフの検証スクリプト
ここはディレクトリ構成を読めば十分なので、図解にはしません。図解は理解を助けるためのものです。コードブロックや箇条書きで足りる箇所まで図にすると、読む流れを止めてしまいます。これは今回のスキルを作っていて、自分でも何度か踏みかけた罠でした。
Agent Skills で特に参考になったのは、progressive disclosure という考え方です。エージェントは最初から全ファイルを読むのではなく、まず name と description だけでスキルを発見します。必要になったら SKILL.md を読み、さらに必要なときだけ references/ や assets/、scripts/ を参照します。
そのため、SKILL.md にすべてを詰め込むのは避けました。毎回必要な手順は本文に置き、パターンカタログやチェックリストは別ファイルに分けています。
Agent Skills のベストプラクティスでも、長い参照資料は別ファイルに分け、必要なときに読む構成が推奨されています。
インストール方法
zukai-creator は、53able/skills リポジトリからインストールできます。手元で試すだけなら、個別インストールから始めるのがよいと思います。以下は Agent Skills CLI の追加形式に沿った例です。公開時点の README や CLI の仕様に合わせて確認してください。
特定のスキルだけ入れる場合は、次のコマンドです。
npx skills add 53able/skills --skill zukai-creator必ず JSON 形式で返してください。translation フィールドのみ。他のフィールド (technical_terms 等) は一切追加しないこと — 余計なフィールドを書こうとして本文翻訳がトークン上限で打ち切られる事故を防ぐため:
{"translation": "zukai-creator も、この形式に合わせました。Git で管理しやすく、チーム内で配布したり、別のエージェント環境に持ち込んだりしやすいからです。
公式仕様では、スキルは少なくとも SKILL.md を含むディレクトリとして定義されます。
zukai-creator/
├── SKILL.md
├── scripts/
├── references/
└── assets/
SKILL.md には YAML frontmatter と Markdown 本文を書きます。必須フィールドは name と description です。特に description は、エージェントが「このタスクでスキルを使うべきか」を判断するための入口になります。
今回の構成は次の通りです。
- SKILL.md: スキルのメタデータと実行手順
- references/pattern-catalog.md: 図解パターンの選択基準
- references/review-checklist.md: 最終レビュー用のチェックリスト
- assets/diagram-brief-template.json: 図解ブリーフのテンプレート
- scripts/check-diagram-brief.py: JSON ブリーフの検証スクリプト
ここはディレクトリ構成を読めば十分なので、図解にはしません。図解は理解を助けるためのものです。コードブロックや箇条書きで足りる箇所まで図にすると、読む流れを止めてしまいます。これは今回のスキルを作っていて、自分でも何度か踏みかけた罠でした。
Agent Skills で特に参考になったのは、progressive disclosure という考え方です。エージェントは最初から全ファイルを読むのではなく、まず name と description だけでスキルを発見します。必要になったら SKILL.md を読み、さらに必要なときだけ references/ や assets/、scripts/ を参照します。
そのため、SKILL.md にすべてを詰め込むのは避けました。毎回必要な手順は本文に置き、パターンカタログやチェックリストは別ファイルに分けています。
Agent Skills のベストプラクティスでも、長い参照資料は別ファイルに分け、必要なときに読む構成が推奨されています。
インストール方法
zukai-creator は、53able/skills リポジトリからインストールできます。手元で試すだけなら、個別インストールから始めるのがよいと思います。以下は Agent Skills CLI の追加形式に沿った例です。公開時点の README や CLI の仕様に合わせて確認してください。
特定のスキルだけ入れる場合は、次のコマンドです。
npx skills add 53able/skills --skill zukai-creator
```"}
Cursor など、対応クライアント向けにグローバルインストールする場合は -g と -a を付けます。
npx skills add 53able/skills --skill zukai-creator -g -a cursor
サブディレクトリを直接指定して入れることもできます。
npx skills add https://github.com/53able/skills/tree/main/skills/zukai-creator -g
インストール後は、対応クライアントでエージェントに「この文章を図解して」「記事用の図解案を作って」のように依頼します。スキルの description に合うタスクだと判断されると、zukai-creator が読み込まれます。
## 図解は「昔からあるから正しい」わけではない
図解自体は昔からあります。ただ、ここで歴史を持ち出したい理由は「昔からあるから正しい」と言うためではありません。そう書くと、かなり雑な権威づけになってしまいます。
図解は、用途に応じて形を変えながら使われてきた外部表現です。その流れを知っておくと、AI に図を作らせるときも、「見た目」だけでなく「何を外に出して考えやすくするのか」に目が向きます。
Michael Friendly の [「A Brief History of Data Visualization」（2006）](https://datavis.ca/papers/hbook.pdf) では、データ可視化の源流として、幾何図、天体位置の表、地図、航海のための座標表現などが挙げられています。図は装飾ではなく、位置、量、変化、関係を扱うための道具として発展してきました。
18 世紀末には William Playfair が、折れ線グラフや棒グラフなど、現在でも使われる統計グラフの形式を広めました。これは zukai-creator が直接扱う概念図とは違いますが、「情報をどんな形にすれば比較・理解しやすいか」という問題意識は共通しています。
出典: William Playfair, The Commercial and Political Atlas, 1786. 画像は [Wikimedia Commons](https://commons.wikimedia.org/wiki/File/1786_Playfair_-_Exports_and_Imports_of_Scotland_to_and_from_different_parts_for_one_Year_from_Christmas_1780_to_Christmas_1781.jpg) より。
さらに、図解は推論の道具としても扱われてきました。Johnson-Laird の [「Peirce, logic diagrams, and the elementary operations of reasoning」（2002）](http://modeltheory.org/papers/2002peirce.pdf) は、Charles Sanders Peirce の論理図を取り上げ、図が思考や推論の操作と関係していることを論じています。
出典: Poccil, Alpha Graphs, graphical representation of propositional logic, Charles Sanders Peirce. 画像は [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:PeirceAlphaGraphs.svg) より。ライセンスは CC BY-SA 3.0 / GFDL。
かなり乱暴に並べると、次のような流れです。厳密な歴史整理ではなく、図解が**「考えるための外部表現」**として使われてきたことを見るための補助線です。
図解が外部表現として使われてきた流れ
zukai-creator は、**歴史的な図解手法を再現するスキルではありません**。ただ、図を「思考を助ける外部表現」として扱う点では、この流れとつながっています。
## 図解の作り方に関する研究背景
zukai-creator の手順は、好みだけで決めたものではありません。図解やマルチメディア学習に関する研究で扱われてきた論点を参考にしながら、エージェントが実行しやすいチェック項目へ置き換えています。少し硬い話ですが、スキルの設計理由を説明するうえで外せませんでした。
ただし、**研究知見は万能ルールではありません**。多くの研究は「特定の条件では、この表現の方が学習や課題遂行に効いた」という形で示されます。この記事では、それらをそのまま規則として写すのではなく、スキル設計の判断材料として扱っています。
## 図解は、入れれば必ず効くわけではない
Davenport らの [「When do diagrams enhance learning?」（2008）](https://oli.cmu.edu/wp-content/uploads/2012/05/Davenport_2008_Framework_For_Designing_Relevant_Representations.pdf) は、図解の効果を考えるうえで、次の3点が重要だと整理しています。
- 学習目標は何か
- 図が重要な情報を目立たせているか
- 読み手の認知処理や事前知識に合っているか
同論文では、図解を含む教材が低成績群の学生の転移課題で効果を示した一方で、一見関連している図でも効果が出ない例があったことも説明されています。
この話は、zukai-creator の最初のステップに関係します。最初に目的・読者・主メッセージを決め、そこから図解パターンを選ぶようにしたのは、「とりあえず図を入れる」を避けるためです。図があるだけで親切に見えることはありますが、**読み手の理解に効いているかは別問題**です。
## 余計な探索を減らす
Mayer と Moreno の [「Nine Ways to Reduce Cognitive Load in Multimedia Learning」（2003）](https://carpentries.github.io/instructor-training/files/papers/mayer-reduce-cognitive-load-2003.pdf) は、マルチメディア学習（multimedia learning）では人間の処理容量が限られていることを前提に、認知負荷（cognitive load）を下げる設計原則を整理しています。
図解づくりに関係が深いのは、特に次の原則です。
- coherence: 面白くても不要な情報は削る
- signaling: 重要な情報に注意を向ける手がかりを入れる
- spatial contiguity: 対応する文字と図形は近くに置く
- segmenting: 複雑な内容は小さな単位に分ける
zukai-creator で「コネクタのラベルは線や矢印の近くに置く」「密になりすぎたら複数の図に分ける」「アイコンや装飾は構造が成立してから追加する」としているのは、この考え方があるからです。
**読者に余計な探索をさせないこと。** これは見た目の好みではなく、認知負荷の問題です。
## 図は外部記憶になるが、設計が悪いと負荷になる
Larkin と Simon の [「Why a Diagram is (Sometimes) Worth Ten Thousand Words」（1987）](https://onlinelibrary.wiley.com/doi/10.1111/j.1551-6708.1987.tb00863.x) は、図が有効な理由を、計算効率や探索効率の観点から説明した古典的な論文です。図は、関連する情報を空間的に近く配置できるため、文章だけの場合よりも推論や探索を効率化できる場合があります。
一方で、Huang, Eades, Hong の [「Measuring effectiveness of graph visualizations: A cognitive load perspective」（2009）](https://nschwartz.yourweb.csuchico.edu/huang%20eades%20&%20hong%202009.pdf) は、グラフ可視化（graph visualization）において、視覚的な複雑さ、データの複雑さ、タスクの複雑さが認知負荷に影響することを扱っています。同論文では、正答率や時間だけではなく、主観的なメンタル・エフォート（mental effort）も含めて可視化の有効性を評価する必要があると述べています。
これは、**ラフ構成とレビューのステップ**に関係します。要素数が多すぎる図、線が交差する図、同じ意味なのに形や色が揺れる図は、読み手に余計な負荷をかけます。
研究知見をスキル上のルールと対応づけると、次のようになります。
研究知見
スキル上のルール
図解は目的と読み手に依存する
目的・読者・主メッセージを最初に定義する
関連する情報を近くに配置すると探索負荷が低下します
コネクタのラベルは線や矢印の近くに配置してください
不要な情報は認知負荷を増大させます
アイコンや装飾は構造が成立してから追加しましょう
複雑すぎる図は処理負荷を向上させます
密な図は分割するか、詳細を表へ移しましょう
表現は読み手の事前知識に左右されます
不確かな点は未解決の問いとして列挙してください
可視化はタスクに対して評価すべきです
レビュー時に「一文で何を語る図か」を確認しましょう
この表からもわかる通り、スキルの中心は**「Mermaid をうまく書くこと」ではありません**。先に図解が理解を助ける条件を満たし、その後で Mermaid として出すか、SVG/HTML 化の指示、スライド向けガイダンス、デザインツール用プロンプトへ渡します。
## 図解の入れすぎにも注意する
図解を作るスキルの記事なので、記事中にも図解を入れています。ただし、**入れすぎると逆効果**です。ここは自戒も込めています。
本文だけで十分に伝わる箇所、コードブロックや箇条書きの方が読みやすい箇所まで図にすると、読者は図を解読する負担を追加で背負います。zukai-creator でも、図が密になりすぎたら分割するだけでなく、詳細を表へ移す方針を入れています。
図解は**「文章の代替」ではなく、「理解の詰まりをほどく補助」**として使うくらいがちょうどよいと思っています。フロントエンドで UI を作るときも、説明を全部 UI に詰め込めばよいわけではありません。図解も同じだと思います。
## zukai-creator の全体設計
zukai-creator の手順は、次の 7 ステップで構成しています。
 zukai-creator の 7 ステップ
この流れにしたのは、図解作成を**「デザイン作業」ではなく「情報設計作業」**として扱いたかったからです。
## Step 1: 図解の役割を定義する
最初に、**媒体、目的、読者、主メッセージ**を確認します。
同じ内容でも、スライド用の図と、記事中の図と、SNS 投稿用の図では作り方が変わります。スライドなら一瞬で理解できる必要があります。記事中の図なら、本文を補助する位置づけになります。ドキュメントなら、後から見返して誤読されないことが重要です。
また、この段階で**「観察」と「解釈」**を分けます。元の文章に書かれていることは観察です。そこから推測した因果関係や意図は解釈です。図解ではこの 2 つが混ざりやすいため、スキル側で明示的に分けるようにしました。
## Step 2: ソースを図解の部品に分解する
次に、入力テキストを図解の部品に分解します。
抽出するのは、主に次の 3 種類です。
- 要素：人、チーム、製品、概念、状態、ドキュメント、ステップ、入力、出力など
- 関係性：提案する、変換する、依存する、比較する、含む、分岐する、統合するなど
- グループ：フェーズ、カテゴリ、所有者、レイヤー、境界など
ここで大事なのは、重要なテキストを単なるラベルとして扱わず、**図形で囲める「要素」に変換すること**です。
長い文章をそのままキャンバスに置くと、図ではなく「配置された文章」になります。まず概念を短いラベルにして、要素として扱います。
## ステップ 3：図解パターンを選ぶ
要素と関係性を取り出したら、図解パターンを選びます。
スキルには references/pattern-catalog.md を同梱し、次のような選択規則を持たせています。
- 時間、手順、変化が主題なら、直列またはタイムライン
- 原因、結果、影響が主題なら、矢印、合流、分岐
- 分類、構成、内訳が主題なら、階層、包含、テーブル
- 違い、選択、優先度が主題なら、対比、マトリクス、テーブル
- 相互作用、取引、会話が主題なら、双方向コネクター
最初から見栄えのする型を選ぶのではなく、**主メッセージに合う型**を選びます。
たとえば、何でもマトリクスにすると整理されたように見えます。しかし、時間変化を説明したいならタイムラインの方が自然です。原因と結果を説明したいなら、矢印の向きが重要になります。
**図解パターンは装飾ではなく、読み方のルールです。**
## ステップ 4：低忠実度のラフを作る
完成図に入る前に、まず低忠実度のラフを作ります。
この段階では、**見た目を作り込みません**。矩形、円、矢印、短いラベルで十分です。
スキルでは、次のようなルールを入れています。
- 図形の意味を先に決める
- コネクターのラベルは線や矢印の近くに置く
- グループ化の方法は一つに絞る
- 密になりすぎたら、複数の図に分ける
これは、**図解の品質を早い段階で確認するため**です。見た目を整えた後に構造の間違いへ気づくと、修正コストが高くなります。
## ステップ 5：理解のためにスタイリングする
zukai-creator では、スタイルを**「意味を伝えるためのルール」**として扱います。
たとえば、次のようなルールです。
- 同じ意味には同じ形を使う
- 同じ種類の関係には同じ線を使う
- フォントの太さは最大 2 種類に抑える
- 暗い塗りの上に白文字を置く場合はコントラストを確認する
- アイコンや絵文字は、構造が成立してから追加する
装飾によって視線を誘導することはできます。ただし、**意味がない強調は読み手を迷わせます**。
「重要だから太字」なのか、「カテゴリが違うから色が違う」のか、「プロセスだから角丸矩形」なのか。**意味づけを決めてから見た目を作ります。**
## ステップ 6：図解ブリーフを検証する
このスキルでは、**JSON 形式の図解ブリーフ**も扱えるようにしています。
同梱しているテンプレートには、概略として次の項目があります。
{
"purpose": "",
"audience": "",
"message": "",
"source_summary": "",
"elements": [],
"relationships": [],
"groups": [],
"candidate_patterns": [],
"selected_pattern": "",
"style_rules": {},
"open_questions": []
}
さらに、scripts/check-diagram-brief.py でブリーフを検証する設計にしました。これは**完全な JSON Schema 検証ではなく、最小限の構造チェック**です。欠落フィールド、空フィールド、無効な要素参照、重複した要素 ID などを見ます。
必ず JSON 形式で返してください。`translation` フィールドのみ。**他のフィールド (technical_terms 等)は一切追加しないこと** — 余計なフィールドを書こうとして本文翻訳がトークン上限で打ち切られる事故を防ぐため:
{"translation": "翻訳全文"}
図解は人間の目で見る成果物ですが、**途中のブリーフは機械的に検証できます**。ここを分けておくと、エージェントの出力を次のツールへ渡しやすくなります。
## Step 7: レビューと改訂を行う
最後に、レビュー用チェックリストを読み、図解を見直します。
チェック項目は大きく分けて、次の4つです。
- 意味：主メッセージが一文で言えるか
- 認知負荷（Cognitive Load）：要素数、線の交差、グループ表現が過剰でないか
- 表記：ラベルの粒度、文字サイズ、白抜き文字の視認性に問題がないか
- 制作プロセス：ラフ案や別パターンを検討したか
特に重視しているのは、**「この図は一文で何を語っているか」**という問いです。答えが意図した主メッセージとずれているなら、色や余白を直す前に構造を直します。
## 出力フォーマットを固定した理由
スキルの出力は、基本的に次の構成にしています。
- 図解の目的
- 主メッセージ
- 抽出した要素
- 関係性
- 採用する型
- ラフ構成
- スタイリングルール（スタイリング規則）
- 確認事項
この形にしたのは、**完成図だけではレビューしにくいから**です。
**図解の良し悪しは、完成した見た目だけでは判断できません。** なぜその型を選んだのか、どの要素を主役にしたのか、どの関係性を捨てたのかが見えないと、修正指示も曖昧になります。
**出力に設計意図を含めることで、人間がレビューしやすくなります。** また、Mermaid として整えたり、SVG/HTML化の指示、スライド向けガイダンス、デザインツール用プロンプトへ渡したりしやすくなります。
## 作ってみて感じたこと
エージェントスキルを書くときは、**「良い出力例」だけでなく、「やらないこと」を書く**のが効きます。
zukai-creator でも、エラーハンドリングとして次の方針を明示しています。
- 主張が多すぎる場合は、1 枚に詰め込まず図を分割する
- 関係性が不明確な場合は、矢印なしの要素マップにする
- 定量比較が中心なら、図解ではなくチャートのワークフローに切り替える
- 完成イラストを求められた場合も、まず図解ブリーフを作る
AI に任せる範囲を広げるほど、出力は便利になります。一方で、**責務が曖昧になるほど、失敗したときの原因は見えにくくなります**。
このスキルでは、**「概念図解の情報設計」**に責務を絞りました。画像生成や高度なデザイン制作まで一つのスキルに抱え込むと、たぶん破綻します。必要なら、後段の別ワークフローへ渡す方が扱いやすいです。
## まとめ
zukai-creator は、**テキストをいきなり絵にするスキルではありません**。
入力された情報を読み、図解に必要な部品へ分解し、主メッセージに合う型を選び、ラフ構成とスタイリングルールまで落とし込むためのスキルです。
図解づくりで大事なのは、**きれいな見た目よりも、読み手が迷わない構造**です。そのために、今回のスキルでは次の点を重視しました。
- 媒体、読者、主メッセージを先に決める
- 要素、関係性、グループを分けて抽出する
- 図解パターンを目的から選ぶ
- 低忠実度のラフで構造を確認する
- スタイルを意味づけのルールとして扱う
- ブリーフとチェックリストでレビュー可能にする
**エージェントスキルは、単にプロンプトを長くしたものではありません。** 作業の順序、判断基準、スコープ外の扱い、検証方法をまとめた、小さなワークフローです。
図解のように**「なんとなく作れてしまう」作業ほど、手順化の効果が出やすい**と感じました。AI時代の開発では、実装力だけでなく、こうした作業の型を小さく作って渡せることも大事になりそうです。
## 参考
- Agent Skills 公式サイト
https://agentskills.io/
- Agent Skills Specification
https://agentskills.io/specification
- Agent Skills Best practices for skill creators
https://agentskills.io/skill-creation/best-practices
- Larkin, J. H., & Simon, H. A. 「Why a Diagram is (Sometimes) Worth Ten Thousand Words.」 Cognitive Science, 1987.
https://onlinelibrary.wiley.com/doi/10.1111/j.1551-6708.1987.tb00863.x
- Davenport, J. L., Yaron, D., Klahr, D., & Koedinger, K. 「When do diagrams enhance learning? A framework for designing relevant representations.」 ICLS, 2008.
https://oli.cmu.edu/wp-content/uploads/2012/05/Davenport_2008_Framework_For_Designing_Relevant_Representations.pdf
- Mayer, R. E., & Moreno, R. 「Nine Ways to Reduce Cognitive Load in Multimedia Learning.」 Educational Psychologist, 2003.
https://carpentries.github.io/instructor-training/files/papers/mayer-reduce-cognitive-load-2003.pdf
- Huang, W., Eades, P., & Hong, S.-H. 「Measuring effectiveness of graph visualizations: A cognitive load perspective.」 Information Visualization, 2009.
https://nschwartz.yourweb.csuchico.edu/huang%20eades%20&%20hong%202009.pdf
- Friendly, M. 「A Brief History of Data Visualization.」 2006.
https://datavis.ca/papers/hbook.pdf
- Johnson-Laird, P. N. 「Peirce, logic diagrams, and the elementary operations of reasoning.」Thinking and Reasoning, 2002.
http://modeltheory.org/papers/2002peirce.pdf
- William Playfair の棒グラフ画像，Wikimedia Commons
https://commons.wikimedia.org/wiki/File:1786_Playfair-Exports_and_Imports_of_Scotland_to_and_from_different_parts_for_one_Year_from_Christmas_1780_to_Christmas_1781.jpg
- Peirce Alpha Graphs 画像，Wikimedia Commons
https://commons.wikimedia.org/wiki/File:PeirceAlphaGraphs.svg
- 53able/skills リポジトリ
https://github.com/53able/skills
- 53able/skills: zukai-creator の SKILL.md
https://github.com/53able/skills/blob/main/skills/zukai-creator/SKILL.md
- 53able/skills: 図解パターン・カタログ (diagram pattern catalog)
https://github.com/53able/skills/blob/main/skills/zukai-creator/references/pattern-catalog.md
- 53able/skills: 図解レビュー・チェックリスト (diagram review checklist)
https://github.com/53able/skills/blob/main/skills/zukai-creator/references/review-checklist.md
- 53able/skills: 図解ブリーフテンプレート (diagram brief template)
https://github.com/53able/skills/blob/main/skills/zukai-creator/assets/diagram-brief-template.json
- 53able/skills: 図解ブリーフ検証スクリプト (diagram brief validation script)
https://github.com/53able/skills/blob/main/skills/zukai-creator/scripts/check-diagram-brief.py原文を表示
想定読者: AIエージェント用のスキルを自作したい人、記事やドキュメントの図解づくりをAIに任せたい人
実装: skills/zukai-creator/SKILL.md
こんにちは。AlgomaticでソフトウェアエンジニアをしているGo（@53able）です。
最近は、自作したエージェントスキルをSlackで共有して、社内の人に触ってもらうことを続けています。大きな取り組みというより、日々の小さな配布です。それでも、自分の作ったスキルが誰かの作業の型になったり、少しでも手間を減らしたりするなら、けっこう意味があるなと感じています。
今回は、テキストから図解案を作るエージェントスキル zukai-creator を作った話です。
私は長くフロントエンドエンジニアをしてきました。UIを作る仕事では、実装そのものだけでなく、状態、データの流れ、ユーザーの理解をどう整理するかをよく考えます。最近はAIを前提にした開発が増え、フロントエンドだけを見ていればよい場面は減りました。既存の得意領域を軸にしつつ、バックエンド、ドキュメント、設計、運用まで身軽に動く必要があります。
その中で地味に困っていたのが、説明用の図解です。
以前は、LLMに「Mermaidで図解して」と頼むだけで済ませることが多くありました。簡単なフローならそれで十分です。ただ、少し複雑な説明になると、次のような問題が出ました。
- ノードが増えすぎて、読む順番がわからない
- 矢印の向きやラベルが、意図した説明とずれる
- 本文の要約にはなっているが、理解を助ける図にはなっていない
- 結局、人間側が構造を考え直す必要がある
問題は Mermaid そのものではありませんでした。図にする前の情報設計を飛ばして、いきなり描画形式を指定していたことが問題でした。
そこで、図解を作る前に「目的」「読者」「主メッセージ」「要素」「関係性」「グループ」を整理するアプローチでスキルを作りました。
この記事中の図解も、zukai-creator で作った図解ブリーフをもとに作成しています。たとえば、冒頭の問題意識を図にすると次のようになります。
図: zukai-creator の図解ブリーフに沿って作成したラフ図解
この記事では、なぜこのスキルを作ったのか、どう設計したのか、図解づくりの考え方にどんな研究背景があるのかを書きます。
- 作ったもの
- Agent Skills の形式に合わせる
- インストール方法
- 図解は「昔からあるから正しい」わけではない
- 図解の作り方に関する研究背景
図解は、入れれば必ず効くわけではない
- 余計な探索を減らす
- 図は外部記憶になるが、設計が悪いと負荷になる
- 図解の入れすぎにも注意する
- zukai-creator の全体設計
Step 1: 図解の役割を定義する
- Step 2: ソースを図解の部品に分解する
- Step 3: 図解パターンを選ぶ
- Step 4: 低忠実度のラフを作る
- Step 5: 理解のためにスタイリングする
- Step 6: 図解ブリーフを検証する
- Step 7: レビューと改訂を行う
- 出力フォーマットを固定した理由
- 作ってみて感じたこと
- まとめ
- 参考
作ったもの
zukai-creator は、テキスト・メモ・記事・スライド原稿などを読み、概念図解の設計案を作るためのエージェントスキルです。
スキルの説明は次のように定義しています。
name: zukai-creator
description: テキスト・メモ・記事・スライド・説明文から、要素・関係性・グループ・ラベルを抽出し、図解パターンとスタイリングルールを選んでわかりやすい日本語の概念図解を作る。図解・概念図・説明図・スライド用ビジュアル・ビジュアル要約を作るときに使う。定量データのグラフ、本格的なインフォグラフィック制作、画像生成、装飾的なイラストには使わない。
対象にしているのは、数値グラフや完成イラストではなく、概念を整理する図です。
想定用途は次のようなものです。
- 記事の説明図
- スライド用の概念図
- ドキュメント内のプロセス図
- ホワイトボードのラフ案
- 施策や業務フローの構造整理
- レビュー前の図解ブリーフ作成
逆に、次のものはスコープ外です。
- 定量データのグラフ作成
- 完成イラストの生成
- 装飾中心のビジュアル制作
- 画像生成AI向けの最終プロンプトだけを作る作業
範囲を絞ったのは、スキルの責務を広げすぎると出力がぼやけるからです。zukai-creator の役割は、きれいな画像を一発生成することではありません。図解にする前の構造を整えることです。
Agent Skills の形式に合わせる
同じ作業をLLMに何度も任せるなら、長いプロンプトを毎回調整するより、手順や参照資料をまとめて管理したくなります。Agent Skills は、そのための軽量フォーマットです。もともとは Anthropic が開発し、現在はオープンな標準として公開されています。
基本は、SKILL.md を中心にしたフォルダです。「いつ使うか」「どう進めるか」を書き、必要なら参照ファイル、テンプレート、スクリプトも同じディレクトリに置きます。普通のプロンプト集というより、エージェントに渡す小さな作業パッケージに近いです。
zukai-creator も、この形式に合わせました。Gitで管理しやすく、チーム内で配布したり、別のエージェント環境に持ち込んだりしやすいからです。公式仕様では、スキルは少なくとも SKILL.md を含むディレクトリとして定義されます。
zukai-creator/
├── SKILL.md
├── scripts/
├── references/
└── assets/SKILL.md には YAML frontmatter と Markdown 本文を書きます。必須フィールドは name と description です。特に description は、エージェントが「このタスクでスキルを使うべきか」を判断するための入口になります。
今回の構成は次の通りです。
- SKILL.md: スキルのメタデータと実行手順
- references/pattern-catalog.md: 図解パターンの選択基準
- references/review-checklist.md: 最終レビュー用のチェックリスト
- assets/diagram-brief-template.json: 図解ブリーフのテンプレート
- scripts/check-diagram-brief.py: JSONブリーフの検証スクリプト
ここはディレクトリ構成を読めば十分なので、図解にはしません。図解は理解を助けるためのものです。コードブロックや箇条書きで足りる箇所まで図にすると、読む流れを止めてしまいます。これは今回のスキルを作っていて、自分でも何度か踏みかけた罠でした。
Agent Skills で特に参考になったのは、progressive disclosure という考え方です。エージェントは最初から全ファイルを読むのではなく、まず name と description だけでスキルを発見します。必要になったら SKILL.md を読み、さらに必要なときだけ references/ や assets/、scripts/ を参照します。
そのため、SKILL.md にすべてを詰め込むのは避けました。毎回必要な手順は本文に置き、パターンカタログやチェックリストは別ファイルに分けています。Agent Skills のベストプラクティスでも、長い参照資料は別ファイルに分け、必要なときに読む構成が推奨されています。
インストール方法
zukai-creator は、53able/skills リポジトリからインストールできます。手元で試すだけなら、個別インストールから始めるのがよいと思います。以下は Agent Skills CLI の追加形式に沿った例です。公開時点の README や CLI の仕様に合わせて確認してください。
特定のスキルだけ入れる場合は、次のコマンドです。
npx skills add 53able/skills --skill zukai-creatorCursor など、対応クライアント向けにグローバルインストールする場合は -g と -a を付けます。
npx skills add 53able/skills --skill zukai-creator -g -a cursorサブディレクトリを直接指定して入れることもできます。
npx skills add https://github.com/53able/skills/tree/main/skills/zukai-creator -gインストール後は、対応クライアントでエージェントに「この文章を図解して」「記事用の図解案を作って」のように依頼します。スキルの description に合うタスクだと判断されると、zukai-creator が読み込まれます。
図解は「昔からあるから正しい」わけではない
図解自体は昔からあります。ただ、ここで歴史を持ち出したい理由は「昔からあるから正しい」と言うためではありません。そう書くと、かなり雑な権威づけになってしまいます。
図解は、用途に応じて形を変えながら使われてきた外部表現です。その流れを知っておくと、AIに図を作らせるときも、「見た目」だけでなく「何を外に出して考えやすくするのか」に目が向きます。
Michael Friendly の 「A Brief History of Data Visualization」（2006） では、データ可視化の源流として、幾何図、天体位置の表、地図、航海のための座標表現などが挙げられています。図は装飾ではなく、位置、量、変化、関係を扱うための道具として発展してきました。
18世紀末には William Playfair が、折れ線グラフや棒グラフなど、現在でも使われる統計グラフの形式を広めました。これは zukai-creator が直接扱う概念図とは違いますが、「情報をどんな形にすれば比較・理解しやすいか」という問題意識は共通しています。
出典: William Playfair, The Commercial and Political Atlas, 1786. 画像は Wikimedia Commons より。
さらに、図解は推論の道具としても扱われてきました。Johnson-Laird の 「Peirce, logic diagrams, and the elementary operations of reasoning」（2002） は、Charles Sanders Peirce の論理図を取り上げ、図が思考や推論の操作と関係していることを論じています。
出典: Poccil, Alpha Graphs, graphical representation of propositional logic, Charles Sanders Peirce. 画像は Wikimedia Commons より。ライセンスは CC BY-SA 3.0 / GFDL。
かなり乱暴に並べると、次のような流れです。厳密な歴史整理ではなく、図解が「考えるための外部表現」として使われてきたことを見るための補助線です。
zukai-creator は、歴史的な図解手法を再現するスキルではありません。ただ、図を「思考を助ける外部表現」として扱う点では、この流れとつながっています。
図解の作り方に関する研究背景
zukai-creator の手順は、好みだけで決めたものではありません。図解やマルチメディア学習に関する研究で扱われてきた論点を参考にしながら、エージェントが実行しやすいチェック項目へ置き換えています。少し硬い話ですが、スキルの設計理由を説明するうえで外せませんでした。
ただし、研究知見は万能ルールではありません。多くの研究は「特定の条件では、この表現の方が学習や課題遂行に効いた」という形で示されます。この記事では、それらをそのまま規則として写すのではなく、スキル設計の判断材料として扱っています。
図解は、入れれば必ず効くわけではない
Davenport らの 「When do diagrams enhance learning?」（2008） は、図解の効果を考えるうえで、次の3点が重要だと整理しています。
- 学習目標は何か
- 図が重要な情報を目立たせているか
- 読み手の認知処理や事前知識に合っているか
同論文では、図解を含む教材が低成績群の学生の転移課題で効果を示した一方で、一見関連している図でも効果が出ない例があったことも説明されています。
この話は、zukai-creator の最初のステップに関係します。最初に目的・読者・主メッセージを決め、そこから図解パターンを選ぶようにしたのは、「とりあえず図を入れる」を避けるためです。図があるだけで親切に見えることはありますが、読み手の理解に効いているかは別問題です。
余計な探索を減らす
Mayer と Moreno の 「Nine Ways to Reduce Cognitive Load in Multimedia Learning」（2003） は、マルチメディア学習では人間の処理容量が限られていることを前提に、認知負荷を下げる設計原則を整理しています。
図解づくりに関係が深いのは、特に次の原則です。
- coherence: 面白くても不要な情報は削る
- signaling: 重要な情報に注意を向ける手がかりを入れる
- spatial contiguity: 対応する文字と図形は近くに置く
- segmenting: 複雑な内容は小さな単位に分ける
zukai-creator で「コネクタのラベルは線や矢印の近くに置く」「密になりすぎたら複数の図に分ける」「アイコンや装飾は構造が成立してから追加する」としているのは、この考え方があるからです。
読者に余計な探索をさせないこと。 これは見た目の好みではなく、認知負荷の問題です。
図は外部記憶になるが、設計が悪いと負荷になる
Larkin と Simon の 「Why a Diagram is (Sometimes) Worth Ten Thousand Words」（1987） は、図が有効な理由を、計算効率や探索効率の観点から説明した古典的な論文です。図は、関連する情報を空間的に近く配置できるため、文章だけの場合よりも推論や探索を効率化できる場合があります。
一方で、Huang, Eades, Hong の 「Measuring effectiveness of graph visualizations: A cognitive load perspective」（2009） は、グラフ可視化において、視覚的な複雑さ、データの複雑さ、タスクの複雑さが認知負荷に影響することを扱っています。同論文では、正答率や時間だけではなく、主観的な mental effort も含めて可視化の有効性を評価する必要があると述べています。
これは、ラフ構成とレビューのステップに関係します。要素数が多すぎる図、線が交差する図、同じ意味なのに形や色が揺れる図は、読み手に余計な負荷をかけます。
研究知見をスキル上のルールと対応づけると、次のようになります。
研究知見
スキル上のルール
図解は目的と読み手に依存する
目的・読者・主メッセージを最初に定義する
関連する情報を近くに置くと探索負荷が下がる
コネクタのラベルは線や矢印の近くに置く
不要な情報は認知負荷を増やす
アイコン・装飾は構造が成立してから追加する
複雑すぎる図は処理負荷を上げる
密な図は分割するか、詳細を表へ移す
表現は読み手の事前知識に左右される
不確かな点は未解決の問いとして列挙する
可視化はタスクに対して評価すべき
レビュー時に「一文で何を語る図か」を確認する
この表からもわかる通り、スキルの中心は「Mermaidをうまく書くこと」ではありません。先に図解が理解を助ける条件を満たし、その後で Mermaid として出すか、SVG/HTML化の指示、スライド向けガイダンス、デザインツール用プロンプトへ渡します。
図解の入れすぎにも注意する
図解を作るスキルの記事なので、記事中にも図解を入れています。ただし、入れすぎると逆効果です。ここは自戒も込めています。
本文だけで十分に伝わる箇所、コードブロックや箇条書きの方が読みやすい箇所まで図にすると、読者は図を解読する負担を追加で背負います。zukai-creator でも、図が密になりすぎたら分割するだけでなく、詳細を表へ移す方針を入れています。
図解は「文章の代替」ではなく、「理解の詰まりをほどく補助」として使うくらいがちょうどよいと思っています。フロントエンドでUIを作るときも、説明を全部UIに詰め込めばよいわけではありません。図解も同じだと思います。
zukai-creator の全体設計
zukai-creator の手順は、次の7ステップで構成しています。
この流れにしたのは、図解作成を「デザイン作業」ではなく「情報設計作業」として扱いたかったからです。
Step 1: 図解の役割を定義する
最初に、媒体、目的、読者、主メッセージを確認します。
同じ内容でも、スライド用の図と、記事中の図と、SNS投稿用の図では作り方が変わります。スライドなら一瞬で理解できる必要があります。記事中の図なら、本文を補助する位置づけになります。ドキュメントなら、後から見返して誤読されないことが重要です。
また、この段階で「観察」と「解釈」を分けます。元の文章に書かれていることは観察です。そこから推測した因果関係や意図は解釈です。図解ではこの2つが混ざりやすいため、スキル側で明示的に分けるようにしました。
Step 2: ソースを図解の部品に分解する
次に、入力テキストを図解の部品に分解します。
抽出するのは、主に次の3種類です。
- 要素: 人、チーム、製品、概念、状態、ドキュメント、ステップ、入力、出力など
- 関係性: 提案する、変換する、依存する、比較する、含む、分岐する、統合するなど
- グループ: フェーズ、カテゴリ、所有者、レイヤー、境界など
ここで大事なのは、重要なテキストを単なるラベルとして扱わず、図形で囲める「要素」に変換することです。
長い文章をそのままキャンバスに置くと、図ではなく「配置された文章」になります。まず概念を短いラベルにして、要素として扱います。
Step 3: 図解パターンを選ぶ
要素と関係性を取り出したら、図解パターンを選びます。
スキルには references/pattern-catalog.md を同梱し、次のような選択規則を持たせています。
- 時間、手順、変化が主題なら、直列またはタイムライン
- 原因、結果、影響が主題なら、矢印、合流、分岐
- 分類、構成、内訳が主題なら、階層、包含、テーブル
- 違い、選択、優先度が主題なら、対比、マトリクス、テーブル
- 相互作用、取引、会話が主題なら、双方向コネクター
最初から見栄えのする型を選ぶのではなく、主メッセージに合う型を選びます。
たとえば、何でもマトリクスにすると整理されたように見えます。しかし、時間変化を説明したいならタイムラインの方が自然です。原因と結果を説明したいなら、矢印の向きが重要になります。
図解パターンは装飾ではなく、読み方のルールです。
Step 4: 低忠実度のラフを作る
完成図に入る前に、まず低忠実度のラフを作ります。
この段階では、見た目を作り込みません。矩形、円、矢印、短いラベルで十分です。
スキルでは、次のようなルールを入れています。
- 図形の意味を先に決める
- コネクターのラベルは線や矢印の近くに置く
- グループ化の方法は一つに絞る
- 密になりすぎたら、複数の図に分ける
これは、図解の品質を早い段階で確認するためです。見た目を整えた後に構造の間違いへ気づくと、修正コストが高くなります。
Step 5: 理解のためにスタイリングする
zukai-creator では、スタイルを「意味を伝えるためのルール」として扱います。
たとえば、次のようなルールです。
- 同じ意味には同じ形を使う
- 同じ種類の関係には同じ線を使う
- フォントの太さは最大2種類に抑える
- 暗い塗りの上に白文字を置く場合はコントラストを確認する
- アイコンや絵文字は、構造が成立してから追加する
装飾によって視線を誘導することはできます。ただし、意味がない強調は読み手を迷わせます。
「重要だから太字」なのか、「カテゴリが違うから色が違う」のか、「プロセスだから角丸矩形」なのか。意味づけを決めてから見た目を作ります。
Step 6: 図解ブリーフを検証する
このスキルでは、JSON形式の図解ブリーフも扱えるようにしています。
同梱しているテンプレートには、概略として次の項目があります。
{
"purpose": "",
"audience": "",
"message": "",
"source_summary": "",
"elements": [],
"relationships": [],
"groups": [],
"candidate_patterns": [],
"selected_pattern": "",
"style_rules": {},
"open_questions": []
}
さらに、scripts/check-diagram-brief.py でブリーフを検証する設計にしました。これは完全なJSON Schema検証ではなく、最小限の構造チェックです。欠落フィールド、空フィールド、無効な要素参照、重複した要素IDなどを見ます。
図解は人間の目で見る成果物ですが、途中のブリーフは機械的に検証できます。ここを分けておくと、エージェントの出力を次のツールへ渡しやすくなります。
Step 7: レビューと改訂を行う
最後に、レビュー用チェックリストを読み、図解を見直します。
チェック項目は大きく分けて、次の4つです。
- 意味: 主メッセージが一文で言えるか
- 認知負荷: 要素数、線の交差、グループ表現が過剰でないか
- 表記: ラベルの粒度、文字サイズ、白抜き文字の視認性に問題がないか
- 制作プロセス: ラフ案や別パターンを検討したか
特に重視しているのは、「この図は一文で何を語っているか」という問いです。答えが意図した主メッセージとずれているなら、色や余白を直す前に構造を直します。
出力フォーマットを固定した理由
スキルの出力は、基本的に次の構成にしています。
- 図解の目的
- 主メッセージ
- 抽出した要素
- 関係性
- 採用する型
- ラフ構成
- スタイリングルール
- 確認事項
この形にしたのは、完成図だけではレビューしにくいからです。
図解の良し悪しは、完成した見た目だけでは判断できません。 なぜその型を選んだのか、どの要素を主役にしたのか、どの関係性を捨てたのかが見えないと、修正指示も曖昧になります。
出力に設計意図を含めることで、人間がレビューしやすくなります。 また、Mermaidとして整えたり、SVG/HTML化の指示、スライド向けガイダンス、デザインツール用プロンプトへ渡したりしやすくなります。
作ってみて感じたこと
エージェントスキルを書くときは、「良い出力例」だけでなく、「やらないこと」を書くのが効きます。
zukai-creator でも、エラーハンドリングとして次の方針を明示しています。
- 主張が多すぎる場合は、1枚に詰め込まず図を分割する
- 関係性が不明確な場合は、矢印なしの要素マップにする
- 定量比較が中心なら、図解ではなくチャートのワークフローに切り替える
- 完成イラストを求められた場合も、まず図解ブリーフを作る
AIに任せる範囲を広げるほど、出力は便利になります。一方で、責務が曖昧になるほど、失敗したときの原因は見えにくくなります。
このスキルでは、「概念図解の情報設計」に責務を絞りました。画像生成や高度なデザイン制作まで一つのスキルに抱え込むと、たぶん破綻します。必要なら、後段の別ワークフローへ渡す方が扱いやすいです。
まとめ
zukai-creator は、テキストをいきなり絵にするスキルではありません。
入力された情報を読み、図解に必要な部品へ分解し、主メッセージに合う型を選び、ラフ構成とスタイリングルールまで落とし込むためのスキルです。
図解づくりで大事なのは、きれいな見た目よりも、読み手が迷わない構造です。そのために、今回のスキルでは次の点を重視しました。
- 媒体、読者、主メッセージを先に決める
- 要素、関係性、グループを分けて抽出する
- 図解パターンを目的から選ぶ
- 低忠実度のラフで構造を確認する
- スタイルを意味づけのルールとして扱う
- ブリーフとチェックリストでレビュー可能にする
エージェントスキルは、単にプロンプトを長くしたものではありません。 作業の順序、判断基準、スコープ外の扱い、検証方法をまとめた、小さなワークフローです。
図解のように「なんとなく作れてしまう」作業ほど、手順化の効果が出やすいと感じました。AI時代の開発では、実装力だけでなく、こうした作業の型を小さく作って渡せることも大事になりそうです。
参考
- Agent Skills 公式サイト
https://agentskills.io/
- Agent Skills Specification
https://agentskills.io/specification
- Agent Skills Best practices for skill creators
https://agentskills.io/skill-creation/best-practices
- Larkin, J. H., & Simon, H. A. 「Why a Diagram is (Sometimes) Worth Ten Thousand Words.」 Cognitive Science, 1987.
https://onlinelibrary.wiley.com/doi/10.1111/j.1551-6708.1987.tb00863.x
- Davenport, J. L., Yaron, D., Klahr, D., & Koedinger, K. 「When do diagrams enhance learning? A framework for designing relevant representations.」 ICLS, 2008.
https://oli.cmu.edu/wp-content/uploads/2012/05/Davenport_2008_Framework_For_Designing_Relevant_Representations.pdf
- Mayer, R. E., & Moreno, R. 「Nine Ways to Reduce Cognitive Load in Multimedia Learning.」 Educational Psychologist, 2003.
https://carpentries.github.io/instructor-training/files/papers/mayer-reduce-cognitive-load-2003.pdf
- Huang, W., Eades, P., & Hong, S.-H. 「Measuring effectiveness of graph visualizations: A cognitive load perspective.」 Information Visualization, 2009.
https://nschwartz.yourweb.csuchico.edu/huang%20eades%20&%20hong%202009.pdf
- Friendly, M. 「A Brief History of Data Visualization.」 2006.
https://datavis.ca/papers/hbook.pdf
- Johnson-Laird, P. N. 「Peirce, logic diagrams, and the elementary operations of reasoning.」 Thinking and Reasoning, 2002.
http://modeltheory.org/papers/2002peirce.pdf
- William Playfair の棒グラフ画像, Wikimedia Commons
https://commons.wikimedia.org/wiki/File:1786_Playfair-Exports_and_Imports_of_Scotland_to_and_from_different_parts_for_one_Year_from_Christmas_1780_to_Christmas_1781.jpg
- Peirce Alpha Graphs 画像, Wikimedia Commons
https://commons.wikimedia.org/wiki/File:PeirceAlphaGraphs.svg
- 53able/skills リポジトリ
https://github.com/53able/skills
- 53able/skills: zukai-creator の SKILL.md
https://github.com/53able/skills/blob/main/skills/zukai-creator/SKILL.md
- 53able/skills: 図解パターン・カタログ
https://github.com/53able/skills/blob/main/skills/zukai-creator/references/pattern-catalog.md
- 53able/skills: 図解レビュー・チェックリスト
https://github.com/53able/skills/blob/main/skills/zukai-creator/references/review-checklist.md
- 53able/skills: 図解ブリーフテンプレート
https://github.com/53able/skills/blob/main/skills/zukai-creator/assets/diagram-brief-template.json
- 53able/skills: 図解ブリーフ検証スクリプト
https://github.com/53able/skills/blob/main/skills/zukai-creator/scripts/check-diagram-brief.py
関連記事
今日のまとめ
AI日報で今日の重要ニュースをまとめ読み