Communitygithub.com

HTML エクスプレイナー

エージェントが「HTML エクスプレイナー」ページの計画、作成、または編集を行い、具体的な出力が使えるコピーまたはスクリプトになるようにするための手順を示します。このスキルに含まれるファイル、ページの見た目を経て、新しい課題がこの技術を必要とするときに使用します。

HTML エクスプレイナー とは?

このスキルは、AIエージェントが「HTML エクスプレイナー」と呼ばれる、特殊なHTMLページ(スイムレーン図を用いた説明ページ)を作成・編集するための完全なガイドです。ユーザーはブラウザでこれらのページを読み、Cmd+クリックでVS Codeに直接飛びます。このスキルは、テンプレート、デザインリファレンス、ライティングルール、図のルールを定義し、エージェントが一貫性のある、最小限かつユーザーの質問に正確に答えるページを生成できるようにします。対応プラットフォームは、このスキルファイル(SKILL.md)を読み込める任意のAIエージェント(Claude Code、Cursor、Codexなど)です。このスキルを使用することで、エージェントは「問題の説明」「機能の実装手順」「システムの仕組み」など、リクエストの種類に応じて適切なセクション構造を自動的に選択し、スイムレーンのみを使用した図を作成し、ファイル間のリンクを適切に設定し、最終的なページがすべてのチェック(ダークテーマ、ブルーピルリンク、図のレンダリングエラーなしなど)をパスすることを保証します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/frhn-xo/html-explainer/tree/HEAD/skills/html-explainer

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

HTML エクスプレイナー ページ

ユーザーはこれらのページをブラウザで読み、Cmd+クリックでVS Codeに直接飛びます。ユーザーは段落から読むよりもスイムレーンからフローをはるかに速く理解でき、各ページがユーザーが尋ねたことに答え、それ以上ではないことを望んでいます。

このスキルのファイル

  • assets/template.html: すべてのページの開始点。コピーして使用し、ゼロからページを作成しないでください。
  • references/DESIGN.md: すべてのページが従うデザイン。常にダークフォームで、すべてのリンクはブルーピルです(references/page.md、「見た目」)。テンプレートにない色や要素が必要なページがある場合に読んでください。
  • references/page.md: ファイル名と場所、サイドバー、ファイルリンク、タスクセクション、リンクされたページセクション、マスターページとエクスプレイナーページ。ページを作成したり構造を変更したりするときに読んでください。
  • references/writing.md: 問題セクションと散文。テキストを書く前に読んでください。
  • references/diagrams.md: スイムレーンの見た目と確認方法。図を描いたり編集したりする前に読んでください。
  • references/playable.md、assets/player.js、assets/player.css: 再生可能なスイムレーン。ユーザーが「再生可能」と言ったとき、またはdiv.playerを含むページを編集するときに読んでください。

見た目

すべてのページはreferences/DESIGN.mdに従い、常にダークに保たれ、すべてのリンクはブルーピルで、クリック可能であることが目立ちます:ファイルの場合は下線、他のページの場合は↗、同じページのセクションの場合はどちらでもなし(references/page.md、「見た目:DESIGN.md、常にダーク」および「3種類のリンク」)。テンプレートはこれを既に行っています。すべての図は、読者がサイズ変更、ズーム、ドラッグできるパネルに配置されます(references/diagrams.md、「図のブロック」)。

ページを最小限に保つ

ページには、ユーザーが要求したものだけが含まれます。余分なセクション、表、メモはすべて、答えを見つけるために読み飛ばさなければならないものです。

  • セクション: リクエストに必要なものだけ。1つのスイムレーンとその周りの短い段落で構成されるセクションもあります。ユーザーが要求していないセクション(要約、目録、「理由」セクション、過去の決定の記録)は絶対に追加しないでください。
  • 表: ユーザーが要求した場合のみ。代わりに段落とスイムレーンを書いてください。
  • 図の下: 何もありません。ファイルリスト、メモ、「描かれていません」という行もありません。図を読むために文章が必要な場合は、その前の段落に配置します。

リクエストに応じたセクション

質問に合わせてページを調整します:

  • 「問題は何ですか」、デバッグ、バグ修正: 最初に問題セクション(references/writing.md)を置き、バグのスイムレーン(マスターページの場合は再生可能なもの、references/playable.md)を配置します。その後、説明に必要な追加のスイムレーンを続けます。

  • タスクが議論された後の機能実装またはバグ修正: 問題セクションのすぐ下にタスクセクション(references/page.md、「タスクセクション」)を配置します。ユーザーがまだ問題を解決している間はタスクはまだないため、タスクセクションはありません。

  • 「これはどのように動作しますか」、「このプロジェクトは何についてですか」: 問題セクションもタスクセクションもありません。フローのスイムレーンと、必要に応じて短い段落を配置します。

  • 「このようなものをどのように構築しますか」: 1つのセクション:通常のスイムレーン、追加できる追加機能、および進め方について。

  • 他のページとリンクされたページ(マスターとそのエクスプレイナー、またはユーザーがリンクを要求したページ): 最下部にリンクされたページセクション(references/page.md、「リンクされたページセクション」)を配置します。

その他:最も少ないセクションで質問に答えてください。

図:スイムレーンのみ

図には2種類のみがあります:

  1. スイムレーン: アクターまたはシステムごとに1つのボックス、そのボックス内にステップ、作業が移動するときにボックスを横切る矢印を持つフローチャート(references/diagrams.md)。
  2. 再生可能なスイムレーン: 同じスイムレーンにリセット/戻る/次へ/再生ボタン、1回の押下につき1つの矢印、その下にキャプションが付いたもの(references/playable.md)。「再生可能」、「再生可能なスイムレーン」、「再生可能な図」、「再生可能なbefore/after」はすべてこれを意味します。「スイムレーン」単独は通常のものを意味します。

図に関するその他のリクエスト(「Mermaid図」、「フローを描いて」、「この図」)はすべてスイムレーンに変換されます。

ワークフロー

  1. これはマスターページのエクスプレイナーですか? リクエスト内の特徴的なフレーズをチケットのフォルダー内でgrep検索します(ユーザーがアイテムのテキストのみを貼り付け、マスターの名前を指定しない場合でも)。一致した場合、新しいページはそのマスターのエクスプレイナーです:マスターのファイル名プレフィックスを使用し、同じ変更で双方向にリンクします(references/page.md)。
  2. ファイルを作成します(references/page.md、「ファイル」)、assets/template.htmlからコピーします。{{…}}プレースホルダーを埋め、localStorageキーtoc-open-CHANGE-MEをそのページに固有のものに変更します。
  3. セクションを決定します(「リクエストに応じたセクション」から)、それらのみを書きます。
  4. スイムレーンを描きます(references/diagrams.md)。レンダリングする前に、対象コード内のすべてのループ、分岐、失敗パス、早期リターンをリストアップし、それぞれが描かれていることを確認します。
  5. すべてのファイル参照に#L<行>でリンクします。 各パスが存在し、ターゲット行がテキストで主張されている内容と実際に一致することを確認します。
  6. 以下のチェックを実行し、ページのリンク(下記)とともにチャットで報告します。コードが行うことで図から省略されているものがあれば、その返信でそれを述べてください。

完了と言う前のチェック

  • ページにはリクエストに必要なセクションのみが含まれていること:問題を説明する場合を除いて問題セクションなし、タスクが議論された場合を除いてタスクセクションなし、要求された場合を除いて表なし、図の下に何もなし。
  • ページが人の発言や希望を説明する場合、その最初の文はユーザーが使う言葉で、その人が何を望んでいるかを述べていること(references/writing.md、「誰かの意図を説明する」)。
  • ページがテンプレートの見た目を保っていること:常にダーク、すべての色はreferences/DESIGN.mdから、すべてのリンクは1つのマークが付いたブルーピル、prefers-color-schemeのライトテーマは追加されていないこと(references/page.md、「見た目」)。
  • 凡例は色ではなく意味を名付けていること(「ochre = …」ではなく「問題が発生する箇所」)。ページに独自の色のリストがないこと(references/page.md)。
  • すべての図はスイムレーンであること:ページにsequenceDiagram、stateDiagram、classDiagram、またはその他の図タイプがないこと。
  • mermaid-cliですべての図をレンダリングし、PNGを確認すること(references/diagrams.md、「レンダリングして確認」)。ページはMermaid構文エラーなしで読み込まれなければならない。
  • 送信、書き込み、呼び出し、または読み取りを行うすべてのボックスは、そのテキスト内でどこに対して行うかを示し、その矢印はそのシステムのボックスで終わっていること。別のシステムへのすべての呼び出しは矢印が出て、次のステップがその応答を使用する場合は戻りの矢印もあること。
  • スイムレーンのレーン:ソース内で[" "]とghostをgrep検索すること。これらが存在してはならない。PNG内で、どのレーンボックスも自身のステップに必要な幅や高さよりも広くまたは高くなってはならない。
  • 再生可能なスイムレーン:ブラウザで最初から最後までステップ実行し、戻って確認すること。
  • すべてのサイドバーのhrefとdata-hrefがページ上のidに解決され、すべてのファイルリンクのパスがページからの相対パスとして存在すること。
  • エクスプレイナーページ:マスターがトピックについて議論する箇所でそれにリンクし、エクスプレイナーの先頭がマスターにリンクを返していること。
  • リンクされたページ:各ページがリンクされたページセクションで他のページをリストアップし、そのセクションがページの最後にあり、その中のすべてのリンクが既存のファイルを開くこと。
  • タスクのステータスを変更した後:1回のgrepで各タスクのチェックボックスクラスとラベルを並べてリスト表示し、すべての完了タスクが同じに見えること(references/page.md)。
  • 自動化によって開かれたブラウザタブは通常バックグラウンドにある(document.visibilityState === "hidden")ため、スクロールイベントはそこで発生しません。各scrollIntoView()の後にmarkActive()を呼び出してスクロールスパイをテストし、壊れていると結論付けないでください。

チャットでページに言及する

チャットの返信でHTMLページに言及する場合は常に、ユーザーがブラウザのアドレスバーにそのまま貼り付けられる2行を、各行を独立した行として提供してください:

file:///Users///_/.html

/Users///_/.html

最初の行は完全なfile:/// URL、2行目はディスク上の絶対パスです。各行には他に何も含めないでください:散文、バッククォート、マークダウンリンク、箇条書き、>ブロック引用は一切なし。必要に応じて、上に行に短いラベルを付けてもかまいません(「これをブラウザに貼り付けてください:」)。特定のセクションを示す場合は、idが存在することを確認した後、URLにセクションの#idを追加します。チャット内のコードファイルは通常の相対リンクのままにします。

理由: 相対リンクはVS CodeでHTMLソースを開き、file:///リンクはブラウザでレンダリングされたページを開きます。文中に埋め込まれたりマークダウンでラップされたURLは手作業で取り出す必要があります。

関連スキル