ADS/commenting-visual-explainers
4
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
bc8a281e4c
commenting-visual-explainers/.claude/skills/creating-visual-explainers/SKILL.md
hiroki ito bc8a281e4c first commit 
Made-with: Cursor
2026-03-19 13:59:28 +09:00

17 KiB
Raw Blame History

name description
creating-visual-explainers Generates an illustrated HTML page about any topic and deploys it to surge.sh. Triggered by requests like "図解を作って", "図解を生成して", "このトピックを図解して", or "図解してデプロイして".

Creating Visual Explainers

任意のトピックについて、前提知識がなくても理解できる図解HTMLを生成し、surge.shに公開する。品質基準は「入社したての新卒社会人が読んでも腹落ちする明快さ」だが、この基準は出力には表示しない。

依存

  • references/base.html — 図解テンプレート（Tailwind CSS CDN・Lucide Icons CDN・ADS配色を含む「額縁」）
  • references/model-answer.html — 模範回答（品質基準・デザインパターンの実例）。base.htmlと同一の額縁を含む完全なHTMLファイル。widget 未含（デプロイ時に自動注入されるため）

ワークフロー

Step 0: 前提確認

  1. references/base.html が存在するか確認する。存在しない場合、以下を伝えて終了:

テンプレートファイルが見つかりません。スキルのフォルダ構成が壊れている可能性があります。運営に連絡してください。

  1. プロジェクトルート直下の fb-tool-url.txt が存在するか確認する。存在しない場合、以下を伝えて終了:

FBツールのセットアップがまだ完了していません。 先にチャット欄で「セットアップして」と伝えてください。

Step 1: 模範回答の読み込み

references/model-answer.html を読み、以下を把握する:

  • 完成品の品質水準
  • デザインパターン（色使い・余白・カード・フロー図などの視覚表現）
  • Tailwind CSSクラスの使い方
  • Lucide Iconsの使い方
  • コンテンツの構成・情報量・説明の深さ

模範回答がデザインガイドラインの代わりになる。パーツ一覧やルールではなく、実物から読み取る。

Step 2: テンプレートの読み込み

references/base.html を読み、額縁の構造を把握する:

  • <!-- CONTENT_START --> 〜 <!-- CONTENT_END --> のプレースホルダー位置
  • <!-- TITLE -->, <!-- DESCRIPTION --> のプレースホルダー
  • ADS配色のTailwind設定
  • 読み込み済みのCDN（Tailwind CSS・Lucide Icons）

Step 3: ウェブで情報収集

トピックについてウェブ検索を行い、正確かつ最新の情報を収集する。

検索は 2〜3回 に絞る。以下の観点でクエリを組み立てる:

  1. 正確な定義: トピックの公式な定義、公式ドキュメントの説明
  2. 最新動向: 直近の変更点、アップデート、現在のベストプラクティス
  3. 具体例: 実際の使われ方、初心者に伝わるたとえに使える事例

検索結果から以下を整理し、Step 4 の参考情報とする:

  • トピックの正確な定義（検索結果を優先。AIの学習データだけに頼らない）
  • 最近変わった点があれば、それを明記する
  • たとえ話に使えそうな事例や数字
  • 出典URL: 図解に採用した情報のソースURLを控えておく（Step 4 でインライン出典に使う）

Step 4: コンテンツ生成

Step 3 で収集した情報をもとに、図解HTMLを生成する。検索結果で得た定義・事実・具体例を優先的に採用する。

模範回答のデザインを参考にしつつ、Tailwindの語彙で自由にレイアウトを組む。模範回答のパターンに合うものはそのまま使い、合わないものはTailwindクラスでその場で作る。テンプレートの定義済みパーツに縛られない。

Step 5: ファイル作成

  1. output/ ディレクトリがなければ作成する
  2. トピックに関連する短い英単語のスラッグを決める（例: api-basics, git-rebase）
  3. references/base.html を output/{スラッグ}.html にコピーする
  4. コピーしたファイル内のプレースホルダーをすべて置換する:
    • <!-- TITLE --> → 図解のタイトル
    • <!-- DESCRIPTION --> → 内容を要約した1文
    • <!-- CONTENT_START --> 〜 <!-- CONTENT_END --> → Step 4で生成したコンテンツ
  5. ファイルを保存する（ブラウザで開くのは Step 6 のデプロイ後に行う。ローカルでは開かない）

Step 6: 公開

ファイル保存後、公開する前にまず Node.js の有無を確認する。

node --version

バージョン番号が表示された → そのまま「公開の実行」に進む。

command not found と表示された → references/node-install-guide.md の手順に従ってNode.jsのインストールを案内する。

公開の実行

以下のスクリプトを実行する（中身を読む必要はない）。

macOS / Git Bash（Windows）の場合:

bash .claude/skills/creating-visual-explainers/scripts/deploy-diagram.sh output/{スラッグ}.html [スラッグ]

Windows（PowerShell）で bash が使えない場合:

$fbUrl = Get-Content fb-tool-url.txt
$apiToken = Get-Content fb-api-token.txt
(Get-Content output/{スラッグ}.html -Raw) -replace '</body>', "<script src=`"$fbUrl/widget.js`" data-token=`"$apiToken`"></script></body>" | Set-Content "$env:TEMP\index.html"
npx --yes surge "$env:TEMP\index.html" --domain diagram-[スラッグ].surge.sh

スラッグにはトピックに関連する短い英単語を指定する（例: git-rebase, api-basics）。

初回の場合（Surge未登録）

ターミナルにメールアドレスとパスワードの入力を求められる。以下を伝える:

初回のみアカウント登録が必要です。 メールアドレスを入力して Enter → パスワードを決めて入力して Enter。 確認メールが届いたらリンクをクリックすれば登録完了です。 次回以降はこの手順は不要です。

エラーが出た場合

エラーメッセージをそのまま見せず、何が起きていて何をすれば解決するかを、専門用語を避けて平易に説明する。

よくあるエラーと対応:

  • npx: command not found — Node.js がまだ入っていない。references/node-install-guide.md の手順を案内する
  • surge: not found / surge関連エラー — npm install -g surge を実行してから再度試す
  • 認証エラー / Login required — npx surge login を実行してメールアドレスとパスワードを入力する
  • その他 — エラーの内容を読み、「何が問題で」「次に何をすればいいか」を平易に説明する

図解の削除

ユーザーが「この図解を削除して」と依頼した場合:

  1. deploy-history.log を読み、直近のデプロイURLを特定する
    • ログが存在しない場合 → ユーザーに削除したいURLを聞く
  2. npx surge teardown [ドメイン] を実行する
  3. 削除完了をユーザーに伝える

Step 7: 完了報告

公開に成功した場合

完成・公開完了: 【図解のタイトル】

（図解の内容を1〜2文で要約）

公開URL:
https://diagram-スラッグ.surge.sh

図解の主なポイント:
- （主要トピックを3〜5個）

この図解を削除したいとき:
チャット欄で「この図解を削除して」と伝えてください。

公開できなかった場合

完成: 【図解のタイトル】

（図解の内容を1〜2文で要約）

ファイルの保存先:
output/{スラッグ}.html（ブラウザにドラッグ＆ドロップすると表示できます）

図解の主なポイント:
- （主要トピックを3〜5個）

URLで共有したいとき:
チャット欄で「この図解を公開して」と伝えてください。

守ること（禁止事項）

  • React・shadcn/ui を使わない — 静的な図解にJSフレームワークは不要。AIの出力を制限し、モデルによる品質差も限定的にしてしまう
  • 絵文字を使わない — OS依存で表示が変わる。アイコンはLucide Iconsを使う
  • インタラクティブ要素を入れない — トグル、フェードイン、アニメーション、フォーム、クリックで開閉する要素は一切禁止
  • <style> タグを追加しない — スタイリングはTailwind CSSクラスで行う。インラインの style 属性も避ける
  • <script> を追加しない — テンプレートに含まれるもの以外のJavaScriptは禁止。widget.js の埋め込みはデプロイスクリプトが自動で行うため、SKILL の範囲外
  • 外部リソースを追加しない — テンプレートに含まれるCDN以外の外部読み込み（画像URL・フォント・追加CDN）は禁止
  • テンプレートの額縁構造を変更しない — <head>・CDN読み込み・meta タグはそのまま維持する
  • PDF印刷で消える表現を使わない — bg-clip-text text-transparent によるグラデーション文字はPDF出力時に透明のまま消える。テンプレートの print CSS でフォールバックを入れているが、グラデーション文字を使った場合はPDF出力で色が単色（#2563EB）に変わる点を意識すること

コンテンツ生成の指針

  • 概論 → 各論 — いきなり詳細に入らない。全体像を見せてから個別の話に入る
  • 専門用語は初出で必ず解説 — 「API（Application Programming Interface＝ソフトウェア同士がやり取りするための窓口）」のように、括弧書きで平易に説明する
  • たとえ話で身近な体験に結びつける — レストランの注文、郵便配達、信号機など、技術を知らない人でもイメージできる例を使う
  • 簡潔にまとめすぎない — 理解に必要な情報量は削らない。腹落ちするまで丁寧に説明する
  • 図を早く見せる — 見出しから最初のビジュアルまでに、テキストは最大2段落（各2〜3行）。それ以上の説明が必要な場合は、図を先に見せてから図の後にテキストで補足する（図→説明の順）。「説明してから図を見せる」より「図を見せてから説明する」方が、同じ文量でも「読まされている感」がなくなる。テキストで述べたたとえ話（ゲーム、レストラン等）も、テキストだけで済まさずミニビジュアル化を検討する
  • 「見たことがあるもの」は説明するのではなく見せる — 図解の中で読者がすでに体験しているもの（アプリの画面、ツールのUI、Webサイト）に言及するとき、テキストで「〜という画面が表示されます」と書く代わりに、その画面自体をTailwind CSSで再現して配置する。「天気アプリの画面」なら天気アプリのモックアップを、「チャット画面」ならチャットUIを、「ターミナル」ならターミナルウィンドウを見せる。読者の「見たことある！」という記憶が発火する瞬間が、テキスト説明より圧倒的に理解を深める
  • ビジュアルには2つの役割がある — 図解に使うビジュアルは「構造を示す図」と「体験を再現する図」の2種類。どちらか一方ではなく、両方を組み合わせて使う:
    • 構造パターン（仕組みを頭で理解する図） — 知識の種類に応じて選ぶ:
      • 「Xとは何か」(定義) → アナロジー図: 身近なたとえの登場人物を配置し、矢印で関係を示す。主役を中央に大きく
      • 「Xはどう動くか」(プロセス) → ステップフロー: 番号つき横並び（モバイルは縦）。各ステップにアイコン＋一言。色はステップごとに変える
      • 「XとYの違い」(比較) → 左右対比: 2カラムで並べ、同じ観点を同じ行に揃える。✗/✓ や赤/緑で差を一目で伝える
      • 「Xの具体例」(事例) → カードグリッド: 2列のカードにアイコン＋タイトル＋説明。カード内で「表の顔」と「裏の仕組み」を分けると深みが出る
      • 「Xのすごさ」(数値) → 数字カード: 3カラムに大きな数字。text-3xl font-black で存在感を出し、色を各数字で変える
      • 「Xの構造・中身」(階層) → 入れ子ブロック: 外側の大きなブロック内に構成要素を配置。ボーダーや背景色の濃淡で階層を表現
      • 「Xの誤解」(訂正) → 誤解→正解カード: 赤ヘッダーに誤解、本文に緑で正解。✗と✓の対比
      • 「Xの変遷」(時系列) → タイムライン: 左にボーダーライン、各時点に年号・ラベル・要約。色のグラデーションで時代の変化を表現
    • 体験再現パターン（読者の「見たことある」記憶と結びつける図） — 読者が実際に触れたことのある画面をTailwind CSSで再現する。「あなたが見ているもの」「〜の画面では」「実際に使うとき」のような文脈が出てきたら、テキスト説明ではなくこちらを使う:
      • チャットUI — 吹き出し形式の対話画面。暗い背景＋ユーザー吹き出し（右寄せ）＋AI吹き出し（左寄せ）＋入力欄モック
      • エディタUI — タイトルバー（赤黄緑ボタン）＋サイドバー（ファイルツリー）＋コードペイン。AIチャットパネルを加えた3ペインも可
      • ターミナルUI — タイトルバー（赤黄緑ボタン）＋プロンプト（$）＋コマンド＋出力。コードブロックとの違いはウィンドウ枠がある点
      • ブラウザUI — タイトルバー（赤黄緑ボタン）＋アドレスバー＋ページ内容
      • アプリ画面 — 上記に当てはまらないアプリ（天気予報、地図、決済画面など）。角丸カード内にアイコン＋数値＋ラベルでミニ画面を再現
      • 共通ルール: 中身はリアルすぎず要点が伝わるミニマルな内容にする。特定ブランドのロゴや名称は使わず汎用的な表現にする。Tailwind CSSクラスのみで構成する
  • 冒頭にヒーロー＋一枚絵サマリー — タイトルで「何の図解か」を伝えたあと、そのままトピックの核心を1枚の図で見せる。ヒーローの説明文を図への導入（「ひとことで言えば──」のような引き）にし、図の直後に各論への橋渡し（「ここからひとつずつ解説していきます」）を置く。ヒーロー → 一言の答え → 図 → 各論が一本の流れになること。一枚絵サマリーの構成:
    • 一言の答え: トピックの核心を1文で太字表示（カード冒頭）。読者が「なるほど」と思える定義を先に読ませ、そのあとの図で視覚的に裏付ける
    • コア図解: 一言の答えを図にしたもの。アイコン＋矢印＋ラベルで表現
    • 身近な接点: 読者がすでに体験している具体例を、アイコン＋一言のピルで2〜4個並べる
  • 読者のレベルに言及しない — 「初心者向け」「入門」「未経験者でもわかる」のように読者を特定のレベルにラベリングする表現をタイトル・見出し・本文に入れない。「わかりやすく説明する」のは図解の品質であって、読者のレベルではない。たとえ話や専門用語の解説で自然に噛み砕けば、ラベルなしで誰にでも伝わる
  • ヒーローバッジはトピックカテゴリ — タイトル上のバッジには、トピックのカテゴリを入れる（テクノロジー、ビジネス、開発ツール、デザイン、マーケティングなど）。「初心者向け」「入門」など読者のレベルを示すラベルは入れない
  • インライン出典 — 検索結果から採用した事実・定義・数字のすぐ近くに、出典リンクをさりげなく添える。本文の読みやすさを損なわないよう text-xs text-ads-dim で小さく薄く表示し、リンクテキストはURLそのままではなく「出典: ○○公式ドキュメント」のようにページ内容がわかる名前にする。段落末やカード下部など、視線の流れを邪魔しない位置に置く
  • 日本語で — 英語メインのトピックでも、図解は日本語で書く