菜单
調査・監査・技術選定比較・性能検証・実装結果について、ユーザーが「結果をHTMLで読みやすく整理して」「HTMLの説明資料・レポートとして残して」のように、後から読み返せる静的HTML成果物を求めたときに使う。説明を補助する表、限定的な図解・定量グラフ・折りたたみ・定型指摘フィルタにも対応する。内容の調査・整理を伴わないHTML断片への変換、UI案や配色の比較モック、スライド、単体の探索的グラフ、任意JavaScriptを要する対話ツールには使わない。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
コードベース全体、特定分野、ブランチ差分の改善候補を監査し、根拠付きで優先順位を付け、改善バックログとして残すときに使う。ユーザーが「$improve」「/improve」「コードベースを監査して」「改善候補を優先順位付きで出して」「改善バックログを作って」「このブランチで増えた問題を調べて」「改善バックログを再照合して」「リポジトリの次の方向性を考えて」と依頼した場合に使う。既知のバグ修正、直接の実装、通常のコードレビュー、設計済み作業の計画書作成、実装結果の受け入れ検証には使わない。
設計済みの作業を別エージェントへ渡すため、実装計画書や handoff プロンプトの作成を求められたときに使う。未確定要件の壁打ちや自分で実装する依頼では使わない。
他エージェントへのレビュー依頼、実装結果の受け入れ検証、レビュー結果の妥当性確認を求められたときに使う。PRレビューコメント対応や通常のセルフレビューでは使わない。
別のtmux paneで動いているAIエージェント（Claude Code / Codex / opencode等）へ指示やレビュー依頼を送信する、応答の完了を待って回収する、他paneのエージェントの出力や作業ログを読む、レビュー往復ループを回すときに使う。「%Nのpaneに送って」「隣のpaneのCodexにレビューを依頼して」「あのpaneが終わったら続きをやって」「右のpaneの作業を読んでまとめて」のような依頼で発動する。送る文面の作成自体（レビュー依頼文・handoffプロンプト）では使わず、agent-review-request / agent-handoff-plan に任せる。tmuxを介さないsubagent起動や並列化にも使わない。
Claude Code の /compact 前に、セッション状態の checkpoint を手動で保存するときに使う。「/compact-state」「compact 前に状態を保存して」「checkpoint を保存して」と依頼されたときに発動する。圧縮後の復旧作業、通常の進捗報告、plan 作成では使わない。
UI改善案、配色案、レイアウト案、情報密度の異なる案を、複数の静的HTMLモックとして比較・選択したいときに使う。「UI案をHTMLで比較して」「見た目を複数案出して」のような自然言語でも適用する。調査結果や技術比較を説明資料として残す依頼、単一案の実装、挙動・product logicだけの変更には使わない。
| name | build-technical-explainer |
| description | 調査・監査・技術選定比較・性能検証・実装結果について、ユーザーが「結果をHTMLで読みやすく整理して」「HTMLの説明資料・レポートとして残して」のように、後から読み返せる静的HTML成果物を求めたときに使う。説明を補助する表、限定的な図解・定量グラフ・折りたたみ・定型指摘フィルタにも対応する。内容の調査・整理を伴わないHTML断片への変換、UI案や配色の比較モック、スライド、単体の探索的グラフ、任意JavaScriptを要する対話ツールには使わない。 |
調査結果を構造化YAMLへ保存し、固定rendererで自己完結HTMLへ変換する。 YAMLを唯一の編集元とし、生成HTMLは直接編集しない。
ui-mock-proposalsに任せる。tmp/ai/explainers/<slug>/を使う。docs/などへ置く。document.visibilityは既定でprivateとし、匿名化を確認した資料だけshareableにする。skillディレクトリを<skill-dir>として、次を実行する。
ruby <skill-dir>/scripts/render_explainer.rb init <output-dir>/explainer.yaml
既存ファイルがある場合、initは上書きしない。
フィールドやblock形式が不足する場合だけreferences/format.mdを読む。
document.summaryには結論を先に書く。refsを付け、sourcesのIDと一致させる。checklist blockで明記する。related_artifactsに登録し、本文を複製しない。補助表現は、読み手の理解や探索コストを実際に下げる場合だけ使う。
details: 補足根拠や長いログを初期表示から退避する。主要な結論は隠さない。chart: YAMLにある確定済み数値を固定styleのline/barで比較する。この補助chartのために別のdataviz skillは併用しない。グラフ自体が主成果物、探索的、調整可能ならvisualization系へ任せる。diagram: 2〜8要素のflow/dependency/sequenceを説明する。自由配置や作図用途には使わない。findings: 監査指摘のような定型項目を、定義済みfacetで絞り込む。全文検索や任意条件式には使わない。任意HTMLや任意JavaScriptはYAMLに入れない。
JavaScriptはfindingsがある場合だけrenderer所有の固定scriptをCSP hash付きで埋め込み、通信・状態保存・product logicを持たせない。
ruby <skill-dir>/scripts/render_explainer.rb validate <output-dir>/explainer.yaml
ruby <skill-dir>/scripts/render_explainer.rb render <output-dir>/explainer.yaml <output-dir>/index.html
renderはschema、参照ID、公開時のローカル情報、危険なURLを再検証する。
生成後は共通validatorでCSP、許可外script、外部通信、状態保存、内部anchor、ID重複を静的検査する。
失敗した場合はYAMLを修正し、検証を迂回しない。
既存explainer.yamlだけを更新し、同じindex.htmlへ再renderする。
HTML側の手修正を見つけた場合はYAMLか固定templateへ戻して表現し、生成HTMLとの二重管理を増やさない。
UI mockで案が選ばれた場合は、判断節へ安定案ID、選択理由、実装制約を追記する。
related_artifacts.hrefは選択案の#proposal-<id>へ更新する。
renderer、starter、template、CSS、固定scriptを変更した場合は次を実行する。
<shared-dir>は<skill-dir>/../_shared/html-artifactsを指す。
ruby <skill-dir>/scripts/test_render_explainer.rb
ruby <shared-dir>/scripts/test_validate_html.rb
uv run --with pyyaml python <skill-creator-dir>/scripts/quick_validate.py <skill-dir>
ブラウザ目視は保守時にも必須にしない。ユーザーが明示した場合だけ行う。
新しいblockやdiagram kindは増やさず、実利用3件後に利用頻度と不足を確認する。特にsequenceは実績がなければ削除を再検討する。
scripts/render_explainer.rb: init、validate、renderを行う実行仕様。scripts/test_render_explainer.rb: 固定シナリオと異常系の回帰テスト。references/format.md: YAMLフィールドとblock形式。assets/starter.yaml: 初期YAML。assets/report.html.erb / assets/report.css: 固定HTML template。assets/report.js: findings専用の固定絞り込みscript。../_shared/html-artifacts/: UI mockと共有する成果物契約と基礎validator。