「骨格コピー工場」というスキルの中身
html-diagram-explainer は、「◯◯をHTML図解で」の一言から、白背景・1ファイル完結のHTML図解を、機械検査つきで作り出すスキル。この図解は、そのスキル自身が「どう動くか」「1回の依頼で何が生まれるか」を丸裸にする——つまりこの図解自身が、このスキルの成果物の実例でもある。
0この図の読み方
核心を見る
なぜ毎回同じ品質で仕上がるのか、一行の理由をつかむ。
木を見る
スキル自身のフォルダと、1回の依頼が生む出力を見る。
流れを見る
P0〜P5、依頼から完成まで誰が何をするかを見る。
時間を見る
実際の依頼1件が、何時何分にどう動いたかを見る。
注意を見る
壊しやすいポイントとFAQで事故を避ける。
1先に結論: 仕組みの要点は5つ
SKILL.mdはトリガー語（起動条件）だけを持つ入口。実際の手順はMASTER_PROMPT.mdのP0〜P5に一本化されている。
承認済みの見た目（assets/design-skeleton.html）をscaffold（作業フォルダを自動で建てるスクリプト）が複製。AIは中身の文章とSVGだけ差し替える。
骨格複製とpreflight（納品前の自動点検）は気分に左右されないPython処理。AIの判断は「読む・選ぶ・書く」だけに絞る。
diagram.html/source-map.md/prompt.mdが1つの案件フォルダに揃う。既存フォルダには上書きしない安全設計。
外部参照・トークン改変・必須ブロック欠落を機械検査。1件でもFAILが残る図解は「完成」と報告できない。
2このスキルが無い場合 / ある場合
無い場合: その都度AIにお願いする
「いい感じの図解HTMLを」と頼むたびにAIがCSSを再発明するので、余白・色・情報量が回ごとに違い、当たり外れが出る。
スキル無しの依頼/ ├── AIが白紙からCSSを書く 毎回ゼロから ├── 出来栄えは運まかせ 品質バラつき └── 検査は人間の目視だけ 見落とし
固定化
ある場合: html-diagram-explainer経由
scaffoldが骨格を複製し、AIは中身に集中し、preflightが検査する。誰が・何回頼んでも同じ水準になる。
スキル経由の依頼/ ├── scaffold_diagram.py 骨格を複製 ├── AIは中身だけ差し替え 内容に集中 ├── preflight_diagram_check.py FAIL 0まで自動点検 └── 3点セットとして保存 再現・引き継ぎ可能
3スキル自身の中身と、1回の依頼が生む出力
html-diagram-explainer/ の実体
html-diagram-explainer/ ├── SKILL.md 起動ポインタ（トリガー語だけ） ├── MASTER_PROMPT.md 唯一の実行正本（P0〜P5） ├── README.md 人間向け配布説明 ├── AGENTS.md / GEMINI.md 他AI向け導線 ├── assets/design-skeleton.html デザイン骨格（コピー元） ├── references/ 形式選定・目視QA・外部AI起動文 ├── scripts/ scaffold・preflight └── output/ ├── archive/ 案件ごとの3点セット └── reusable/ 完成見本・昇格版
この図解も、まさにこの構造で出た
output/archive/2026-07-27_mechanism-and-output/ ├── diagram.html 今読んでいるこのHTML自身 ├── source-map.md 読んだ正本と判断理由 └── prompt.md 次回同じ図解を再現する入力
この図解は「html-diagram-explainerの仕組みを図解して」という依頼で、まさにhtml-diagram-explainer自身を使って作られている。
4P0〜P5: 依頼から完成までの6工程
骨格生成（scaffold_diagram.py）
案件フォルダ・diagram.html（骨格のコピー）・source-map.md・prompt.md の3点セットを自動で作る。
対象読解: 一次情報を読み、要点を10行以内に固める
図解する対象の実ファイルを実際にReadする。推測やWeb知識では埋めない。
形式選定: パターン集から5種類以上を選ぶ
references/html-diagram-patterns.md を見て、階層ツリー・比較・タイムラインなどを組み合わせる。
実装: 骨格の中身だけ差し替える
共通CSS・トークンは触らず、各セクションの文章とヒーローのSVGを内容に合わせて描き直す。
機械QA（preflight_diagram_check.py）
外部参照ゼロ・トークン無改変・必須ブロック・形式数・印刷CSSを検査。FAIL 0まで自己修正（最大3周）。
目視確認と報告
ブラウザで開いてチェックリストを確認し、パスとpreflight結果を添えて完了報告する。
5実働タイムライン（この図解1件が生まれた実際の流れ）
上から下へ時間が流れる。オレンジ=あなた（まーく）がやること、緑=自動（スクリプト）、青=AIの判断。
PHASE A — 受付から骨格まで
担当: scaffold（スキャフォールド＝作業フォルダを自動で建てる仕組み） ／ 所要: 数秒
最初の一言
対象フォルダのパスと一言だけ。読者や粒度を指定しなくても、既定値のまま最後まで進む。
scaffold_diagram.py --slug mechanism-and-output
output/archive/2026-07-27_mechanism-and-output/ が建ち、骨格コピーの diagram.html と空の source-map.md / prompt.md が揃う。
PHASE B — AIが読み、中身を作る
担当: AIの判断 ／ 所要: 数十分
一次情報を実際にRead
SKILL.md / MASTER_PROMPT.md / README.md / AGENTS.md / references/3本 / scripts/2本 / 過去の成果物2件を読み、要点10行以内に固める。推測やWeb知識では埋めない。
形式を選び、12セクションの中身を差し替える
ガイド・要点・比較・ツリー・フロー・タイムライン・スイムレーン・循環・マトリクスなど、この図解に必要な形を選び、ヒーローのSVGも描き直す。
PHASE C — 点検と納品
担当: preflight（プリフライト＝納品前の自動点検） ＋ AI ／ 所要: 数分
preflight_diagram_check.py --require-tree --require-timeline
外部参照・トークン改変・必須ブロック欠落・ツリー欠落・タイムライン欠落を検査。FAILが出たらAIが直して再検査。
見せられるもの: ブラウザで開ける完成図解＋preflight結果 ／ やること: 見て一言返すだけ（OKか、直してほしい点）
最初の一言
「html化してほしい」
完成品を見て一言返す
P0〜P5（scaffold→読解→選定→実装→QA→報告）
自動処理（scaffold・preflight）
6誰が何をするか（分担レーン）
（まーく）
7作るたびに良くなる循環
依頼は一言でいい
「◯◯をHTML図解で」だけで、骨格・保存先・検査項目はすべてスキル側が既定値を持っている。
-explainer
複製
差し替え
検査
還流
指摘は正本に蓄積
「ここが惜しい」はdesign-skeleton.html・preflight_diagram_check.py・MASTER_PROMPT.mdのいずれかに反映され、次回から全AIが自動で守る。
8骨格は1系統だけ（structure型 vs flow型）
9preflightは何を機械でカバーするか（目安）
preflightは機械で検査できる項目（構文・外部参照・トークン一致など）を担当し、目視QAは「読みやすいか」の最後の20%だけに絞られている。数値は目安。
10よくある事故 3つ
SKILL.mdは起動の合図にすぎない。実際の手順は必ずMASTER_PROMPT.mdのP0〜P5を読んでから動く。
「簡単だから」と白紙から書いたり、色・影の正本を触ると、preflightがトークン不一致でFAILにする。
目視だけだと外部参照・印刷崩れ・ブロック欠落を見落とす。FAIL 0とTEMPLATE→FILLEDの切り替えまでが制作。
11よくある質問
なぜscaffoldとpreflightをAIにやらせず、スクリプトにしている？
骨格の複製やトークン一致チェックのような「毎回同じ手順」はAIの解釈でブレやすい。決定的な処理はスクリプトに固定し、AIは文章とSVGの判断だけに集中させている。
design-skeleton.html は書き換えていい？
基本禁止。オーナー（まーく）のデザイン指摘を恒久的に反映すると決めた時だけ、旧版を退避してから書き換える。
この図解自体は、次はどう扱われる？
output/archive/2026-07-27_mechanism-and-output/に保存済み。「これが正解」と言われたらoutput/reusable/へコピーして完成見本に昇格する。
12今日からできる一歩
次に何かを図解したい時も、必ずscaffoldから始める
「◯◯をHTML図解で」と一言頼めば、scripts/scaffold_diagram.pyが骨格と3点セットを自動生成し、この図解とまったく同じ手順（P0〜P5）で完走する。
13編集しやすいポイント
- フォルダツリー（§3）: スキル自身の実フォルダが変わったら、
pre.treeのここだけ書き換える - タイムライン（§5）: 別の依頼を図解する時は、
tl-quoteの発話と時刻ラベルを今回の内容に差し替える - マトリクス（§8）: structure/flow以外の骨格系統が増えたら行を追加する
- ヒーローの絵:
.hero-visual内のSVGを案件内容に合わせて描き直す - 任意ブロック（meter・faq など）: 合わなければ
<section>ごと削除する
14更新履歴
| 日付 | 変更内容 | 理由 |
|---|---|---|
| 2026-07-27 | html-diagram-explainerの仕組み・出力内容の図解を作成 | まーくからの「このスキルの仕組みと出力内容をhtmlにまとめてほしい」という依頼に対応 |