1つのリポジトリのアトラス
リポジトリの各部はどうつながっているか
3つのスキルが1つのテンプレートとチェッカーを共有し、フック、リポジトリの確認、CI がページの正しさを保ちます。
- どのページも、同じテンプレートのコピーから始まる。
- 合否を決めるのは、チェッカー1つです。
- フック、check-repo、CI がそれを実行する。
行番号は、2026年10月15日のコミット b33f303 を指しています。ここに書かれたことをもとに動く前に、現在のソースを確認してください。
部品と呼び出しの関係
部品を選ぶhtml-explainer スキル。テンプレートをコピーし、結論を先に書き、チェッカーを実行するよう指示します。html-explainer/SKILL.md:16 html-explainer/SKILL.md:40
explainer-gather スキル。同じテンプレートに、回答欄と収集バーを1つ足します。explainer-gather/SKILL.md:39 explainer-gather/SKILL.md:40
explainer-atlas スキル。テンプレートに atlas.css と atlas.js を足し、アンカーの確認を実行します。explainer-atlas/SKILL.md:33 explainer-atlas/SKILL.md:29
ルートスキルの shim。休止中です。ルートに SKILL.md があるとインストーラーが全体を1つのスキルと見なすため、2026年10月13日に保留にしました。root-skill-shim.md:2
template.html。共通の外枠です。スタイルは16行目、スクリプトは1542行目、バージョン表記は6行目にあります。template.html:16 template.html:1542 template.html:6
upgrade.mjs。古いページのスタイルとスクリプトをテンプレートのものに替え、バックアップを残し、チェッカーを再実行します。upgrade.mjs:97 upgrade.mjs:131
check.mjs。ページを読み、FAIL と warn の行を出力します。終了コード0なら FAIL はありません。check.mjs:67 check.mjs:594
render フラグ。目標です。ロードマップでは12月にブラウザでの確認を入れる予定ですが、チェッカーにはまだそのフラグがありません。ROADMAP.md:19 check.mjs:9
フック。 Claude が保存したページを控え、ターン終了時にチェッカーにかけます。hooks.json:11 explainer-check:139
CI と check-repo。 check-repo は、配布する全ページにチェッカーを実行し、リポジトリの確認を5つ加えます。CI は、プッシュのたびに実行します。check-repo.mjs:34 ci.yml:21
- 重心はどこにあるかほとんどは2つのファイルにあります。
- 1つのページには何が起きるのか依頼から、アップグレードされる日まで。
- ページを保存すると何が動くのかフックと、プッシュ後の CI。
- どの部品が何を見つけるのか5つの不具合に、担当は1つずつ。
- どうリリースするのか4つの手順と、まだ動いていないもの。
第1章 / 全5章、約1分
重心はどこにあるか
おさらい： 3つのスキルは1つのテンプレートを使い、見張り役はどれも同じチェッカーに頼ります。
図は全体の形を、行数は重さを示します。テンプレートはどのページもコピーする外枠で、チェッカーには、ページが通すべきルールがすべて入っています。
つまり：重心はテンプレートとチェッカーです。フックと CI は、ページのルールを足さず、チェッカーを動かす時期を決めるだけです。
各数字と主張の根拠を見る
- テンプレートのスタイルは template.html:16 から、スクリプトは template.html:1542から始まります。
- チェッカーは check.mjs:586でレポートを出力し、終了コードを設定します。
- フックが実行するチェッカーは explainer-check:16で指定されています。
- ワークフローは ci.yml:21で check-repo を実行します。
この章のポイント：重心は2つのファイルにあり、ほかは実行の時期を決めるだけです。
第2章 / 全5章、約2分
1つのページには何が起きるのか
おさらい：重心はテンプレートとチェッカーにあります。
説明ページ1枚を、依頼から更新までたどります。各カードに、その段階のファイルを載せています。
- 依頼説明ページを頼む。
呼び出す言い回しは、スキルに一覧がある。
- コピーテンプレートがページになる。
バージョン表記つきの1ファイル。
- 確認 check.mjs がページを読む。
FAIL は直す。警告は助言。
- 保存フックが書き込みを見る。
ターン終了時にページを確認する。
- アップグレードテンプレートが新しくなる。
ブロックを差し替え、バックアップを残す。
- リリース残したサンプルが公開される。
CI が確認し、サイトにコピーされる。
つまり：ページがテンプレートと出会うのは1回、チェッカーとは何度も、アップグレーダーとはデザイン変更のときです。
この章のポイント：ページはテンプレートから1回コピーされ、あとは使われ続けるかぎり、確認と更新を繰り返します。
第3章 / 全5章、約2分
保存すると何が動くのか
おさらい：何度も確認するのは、フックと CI です。
チェッカーを動かす流れは2つです。フックは Claude Code の作業中に、CI はプッシュ時に動きます。
フック：Claude Code の1ターン内
- Claude が Write か Edit で保存します。hooks.json:13
- 説明ページなら、フックが記録します。explainer-check:54
- 終了時、Stop の処理が記録したページをチェッカーにかけます。explainer-check:139
- check.mjs が FAIL の行を返します。explainer-check:118
- FAIL なら終了コード2で止まり、Claude が直します。最大3回です。explainer-check:169 explainer-check:14
CI（プッシュのあと）
- main へのプッシュか、プルリクエストで始まります。ci.yml:3
- check ジョブが Node 18 で check-repo を実行します。ci.yml:19 ci.yml:21
- check-repo は、配布する各ページとほか5項目を確認します。check-repo.mjs:34
- main で check が通ると、site ジョブが配布ファイルを _site にコピーします。ci.yml:24 ci.yml:38
- Pages のアクションがそのフォルダをデプロイします。ci.yml:49
つまり：どちらの終点も同じチェッカーです。違いは、動く時期と結果を見る人です。
この章のポイント：フックはターン終了時、CI はプッシュのたびに、チェッカーを動かします。
第4章 / 全5章、約1分
どの部品が何を見つけるのか
おさらい：フックと CI は、どちらも同じチェッカーにたどり着きます。
1つの確認で、すべてを見つけられるわけではありません。以下の不具合は、どれも担当の部品が1つです。
| 不具合 | check. | フック | upgrade. | check- | anchors. |
|---|---|---|---|---|---|
| ページがルールに違反する | はい | はい | 一部 | 一部 | いいえ |
| ギャラリーが同期していない | いいえ | いいえ | いいえ | はい | いいえ |
| スキルのパスが古い | いいえ | いいえ | いいえ | はい | いいえ |
| ページが古い | いいえ | いいえ | はい | いいえ | いいえ |
| アトラスのアンカーがずれている | 一部 | いいえ | いいえ | いいえ | はい |
つまり：ページのルールはチェッカーが、リポジトリのルールは check-repo が担当します。アトラスの行番号を読むのは anchors.mjs だけです。
担当ごとの該当箇所を見る
はい。 check.mjs が FAIL の行を出力し、終了コードを決めるのは check.mjs:586。フックが終了コード2でターンを止めるのは explainer-check:169。upgrade.mjs がブロックを差し替えるのは upgrade.mjs:106。check-repo がギャラリーを比べるのは check-repo.mjs:42 で、スキルのパスを確認するのは check-repo.mjs:55。anchors.mjs が範囲外のアンカーを数えるのは anchors.mjs:62。
一部。 upgrade.mjs が再確認するのは、アップグレードしたページだけです。該当箇所は upgrade.mjs:137。check-repo が確認するのは、配布するページだけです。該当箇所は check-repo.mjs:24。check.mjs が見るのは、アンカーの属性が2つそろっているかだけです。行が実在するかは見ません。該当箇所は check.mjs:336。
この章のポイント：不具合ごとに担当は1つなので、1つの確認が通っても、ほかの確認の保証にはなりません。
第5章 / 全5章、約2分
どうリリースされ、何がまだ動いていないのか
おさらい：不具合ごとに担当は1つで、サイトの手前で最後に見張るのが CI です。
リリースは、短く決まった道筋です。ユーザーはマーケットプレイスから受け取り、サイトは main から自動でデプロイし直されます。
- バージョンを上げる。 plugin.json とテンプレートの表記は、同時に変えます。plugin.json:4 check-repo.mjs:76
- check-repo を実行する。続けて、プラグインの厳格な検証です。CONTRIBUTING.md:72
- マージし、タグを付け、リリースする。 main へマージし、vX.Y.Z のタグと GitHub リリースを作ります。CONTRIBUTING.md:73
- ユーザーに更新してもらう。プラグインに3つのスキルを載せ、マーケットプレイスが届けます。plugin.json:13 CONTRIBUTING.md:74
つまり：リリースは4つの手順です。サイトは含まれません。main が変わるたびにデプロイし直されるからです。ci.yml:25
休止中：ルートスキルの shim。 2026年10月13日に保留にしました。リポジトリを1つのスキルとしてクローンしたい人が出たときだけ戻します。root-skill-shim.md:9
目標：render フラグ。ロードマップでは12月にブラウザでの確認を入れる予定ですが、チェッカーにはまだそのフラグがありません。ROADMAP.md:19
用語集と、このページの確認方法を見る
- スキル
- SKILL.md を含むフォルダ。依頼に合うとき、エージェントが読みます。
- テンプレート
- どのページもここから始まる、1つの HTML ファイル。
- チェッカー
- ページが合格かどうかを決めるスクリプト。
- フック
- ターンの終わりなどのイベントで、Claude Code が実行するスクリプト。
- アンカー
- このページの主張を裏づける、ファイルと行番号。
- スナップショット
- このページは、ある1つのコミット時点で正しく、そのことを明記しています。
全アンカーを、コミット b33f303 とアンカー用スクリプトで照合済みです。
node skills/explainer-atlas/scripts/anchors.mjs skills/explainer-atlas/examples/atlas/index.html --repo . --rev b33f303この章のポイント：リリースは4つの手順で、保留中や計画中のものは明記しています。
まとめ
- 重心は2つのファイルにあり、ほかは実行の時期を決めるだけです。
- ページはテンプレートから1回コピーされ、あとは使われ続けるかぎり、確認と更新を繰り返します。
- フックはターン終了時、CI はプッシュのたびに、チェッカーを動かします。
- 不具合ごとに担当は1つなので、1つの確認が通っても、ほかの確認の保証にはなりません。
- リリースは4つの手順で、保留中や計画中のものは明記しています。