AIエージェントに調べてもらった内容を、図とスクリーンショット中心のHTML資料で受け取り、そのページから追加の質問もできる visual-explain というスキルを作りました。使ってみてかなり便利だったのでまとめておきます。

何に困っていたか

AI駆動開発を進める中で、エージェントに仕様や仕組みを調べてもらい、レポートとしてまとめてもらうことがよくあります。そのときに気になっていたことが2つありました。

1つ目は、レポートに対して深掘りの質問をすると、元のレポートがターミナルの上の方に流れてしまうことです。レポートを見ながら質問したいのに、質問を重ねるほど元の内容が遠くなっていきます。

2つ目は、テキストだけだと認知負荷が高いことです。処理の流れや状態の変化のように、複数の事柄の関係を理解したい内容ほど、文章と表だけで追うのは大変でした。

visual-explainとは

仕様・変更内容・仕組み・調整案などを、図とスクリーンショットを中心にしたHTML資料にまとめて、ブラウザで開けるように配信するスキルです。Claude CodeとCodex CLIで使えます。

flowchart TD A["エージェントに依頼"] --> B["調査して図解のHTML資料を作成"] B --> C["ブラウザで資料を読む"] C --> D["ページから追加の質問"] D --> E["回答が届き、必要なら資料も直る"] E --> C

導入は以下のコマンドです。

npx skills add fukata/skills -g -a claude-code -a codex -s visual-explain
bash ~/.agents/skills/visual-explain/setup.sh

導入後は、次のような依頼をすると自動的に使われます。

申請から承認までの状態遷移を図で見せて。
注文の確定から発送の手配までどう流れるの？
このブランチで改修したAPIについて認識合わせするための資料を作成して。

図を頼んでいなくても、複数の事柄の関係を問う質問や、回答が長くなる質問には、文章の回答に資料のURLが添えられます。

図とスクリーンショットで理解しやすくなった

以下は、このブログの記事が公開されるまでの流れを説明してもらった資料です。

visual-explainで生成した資料。要点と全体像の図が並んでいる

ターミナルで見ていたときはテキストだけだったものが、図やスクリーンショットを含めた形で見られるようになり、視覚的にかなり理解しやすくなりました。

自分がよく使うのは、複雑な仕様を理解したい場面です。仕様そのものだけでなく、なぜそのようになっているのか、周辺の内容も含めて理解したいときに使っています。

資料は事前知識の無い人が読む前提で作られるので、前提や用語の説明から始まり、全体像の図、個別の図、根拠となるコードの場所という順に並びます。情報の羅列にならないように、資料を渡す前に検査スクリプトで機械的にチェックする仕組みも入れています。

資料のページから追加の質問ができる

個人的に一番便利だと感じているのがこの機能です。

単発のレポートだと、追加で質問したいことが出てきたときに、ターミナルに戻って質問することになります。visual-explainでは、配信されたページの右下にある「質問する」から、資料を開いたまま質問できます。

資料を開いたまま、ページ右側の質問欄から追加の質問をして回答が表示されている

回答は、資料を作ったエージェントが、資料を作ったときのセッションを引き継いで書きます。資料の説明が足りないと分かった場合は、資料の本文も直して最新版に切り替えてくれます。上のスクリーンショットでも、右側に回答が表示されると同時に、左側の資料に質問の内容を踏まえた補足が追記されています。

生成された資料を見ながら、出てきた疑問をその場で追加質問する、という使い方をよくしています。レポートが流れていくこともなく、読んでいる資料がそのまま育っていく感覚です。

AskUserQuestionにも資料のページで答えられる

このスキルは、エージェント側から質問される場面でも使われます。Claude CodeではAskUserQuestion、Codex CLIではrequest_user_inputの質問が対象です。

エージェントが選択肢を提示して判断を求めてくるとき、背景が複雑だとターミナルの短い説明だけでは選びにくいことがあります。visual-explainを入れておくと、質問が資料のページに表示され、質問ごとに選ぶための図入りの資料も作られます。複雑な背景を持った質問でも、内容を理解したうえで選ぶことができます。

以下は、この記事を書いている途中に、エージェントから節の見出しをどうするか聞かれたときの画面です。

エージェントからの質問が資料のページに表示されている。左側に選択肢の説明、右側の欄で選択肢を選んで「この答えを送る」を押す

右側の欄で選択肢を選んで「この答えを送る」を押すと、答えが元のセッションに戻り、エージェントの作業がそのまま続きます。ターミナルに戻って選び直す必要はありません。

答えを送った後の画面。「答えを送りました。Claude Code の作業が続いています。」と表示されている

左側は、最初は選択肢だけのページで、数分すると選ぶための図入りの資料に差し替わります。選ぶ前に、下の質問欄から選択肢について追加で質問することもできます。

AIを一番詳しい人に見立てて何回でも聞ける

これまでは、自分が知りたいことや困っていることがあると、社内で一番詳しい人に聞かないといけない状況でした。

それが、AIを一番詳しい人に見立てて、自分が知りたい情報を何回でも質問できる状況になりました。相手の時間を気にする必要がなく、分かるまで聞けます。しかも図解された資料を見ながら、認知負荷が低い状態で聞けるというのは非常に便利です。

まとめ

エージェントのレポートを図解のHTML資料で受け取り、ページからそのまま追加質問できるvisual-explainというスキルを作りました。

テキストだけのレポートをターミナルで追いかけていた頃と比べると、複雑な仕様の理解がかなり楽になりました。AIを一番詳しい人に見立てて、認知負荷が低い状態で何回でも聞けるというのが、このスキルで一番気に入っているところです。

スキルは fukata/skills で公開しているので、興味があれば試してみてください。