An atlas of one repository

How the repository fits together

Reading time about 7 minutesRevision b33f303, 2026-10-15For: a new contributor

One template and one checker serve three skills, and a hook, a repository check and CI keep every page valid.

Keep in your head (only these)
  1. Every page starts as a copy of one template.
  2. One checker decides whether a page passes.
  3. A hook, check-repo and CI each run that checker.
Snapshot, not a live view.

Line references point at commit b33f303 of 2026-10-15. Check the current source before you act on anything here.

The parts and who calls whom

Pick a part
Current: runs todayDormant: built, but offTarget: adopted, not built
The repository as five layers. Three skills, the explainer, gather and atlas skills, copy one shared template. Below it, the upgrader swaps new blocks into old pages and re-checks them with the one checker. The hook and CI both run the checker, and CI then deploys the site. A parked root skill shim and a planned render flag are drawn as dashed pills. SkillsTemplateChecksGuardsSite html-explainerwrites the page explainer-gatherasks and collects explainer-atlasmaps a codebase root skill shimparked 2026-10-13 copies it builds on it adds atlas.js to it template.htmlthe one shell every page copies swaps in its blocks upgrade.mjsupdates old pages re-checks check.mjsthe one rulebook for a page would add --render flagplanned, not built runs it every turn runs it on shipped pages hookchecks at turn end CIruns check-repo deploys from main site buildcopies and deploys

html-explainer skill. Tells the agent to copy the template, write the answer first and run the checker. html-explainer/SKILL.md:16 html-explainer/SKILL.md:40

explainer-gather skill. Builds on the same template and adds answer fields and one collect bar. explainer-gather/SKILL.md:39 explainer-gather/SKILL.md:40

explainer-atlas skill. Starts from the template, adds atlas.css and atlas.js, then runs the anchor check. explainer-atlas/SKILL.md:33 explainer-atlas/SKILL.md:29

Root skill shim. Dormant. It was parked on 13 October 2026 because a root SKILL.md made installers treat the whole repository as one skill. root-skill-shim.md:2

template.html. The one shell. Its style starts at line 16, its reader script at line 1542, and its version mark sits at line 6. template.html:16 template.html:1542 template.html:6

upgrade.mjs. Replaces an old page's style and script with the template's, keeps a backup, and re-runs the checker. upgrade.mjs:97 upgrade.mjs:131

check.mjs. Reads a page and prints FAIL and warn lines. Exit 0 means no FAIL. check.mjs:67 check.mjs:594

The render flag. Target. The roadmap adopts a browser check for December, and the checker takes no such flag yet. ROADMAP.md:19 check.mjs:9

The hook. Notes the pages Claude saves and runs the checker on them when the turn ends. hooks.json:11 explainer-check:139

CI and check-repo. check-repo runs the checker on every shipped page and five repository checks. CI runs it on each push. check-repo.mjs:34 ci.yml:21

The site build. After check passes on main, it copies the shipped files into _site and deploys them. ci.yml:38 ci.yml:49

Take: three skills feed one template, and one checker sits under every guard. Dashed pills are parked or planned, not live.
  1. Where does the weight sit?Two files hold almost everything.
  2. What happens to one page?From the request to the day it is upgraded.
  3. What runs when you save a page?The hook, and CI after a push.
  4. Who catches what?Five failures, one owner each.
  5. How does it ship?Four steps, and what is not live.

Chapter 1 of 5, about 1 minute

Where does the weight sit?

Before this: three skills feed one template, and one checker sits under every guard.

The map shows the shape. Line counts show the weight. The template is the shell every page copies, and the checker holds every rule a page must pass.

2,444lines in template.html
594lines in check.mjs
182lines in the hook
49lines in ci.yml

Take from this: the template and the checker hold the weight. The hook and CI add no page rules, only a time to run the checker.

Show where each number and claim comes from

Remember: two files carry the weight, and everything else decides when to run them.

Chapter 2 of 5, about 2 minutes

What happens to one page?

Before this: the template and the checker hold the weight.

Follow one explainer page from the request to the day it is kept current. Each card names the files that do the work.

  1. AskedYou ask for an explainer.

    The skill lists the phrases that load it.

  2. CopiedThe template becomes the page.

    One file, with a version mark.

  3. Checkedcheck.mjs reads the page.

    A FAIL is fixed. A warning is advice.

  4. SavedThe hook sees the write.

    It checks the page when the turn ends.

  5. UpgradedThe template moves on.

    The upgrader swaps the blocks and keeps a backup.

  6. ShippedA kept example goes live.

    CI checks it, then the site copies it.

Take from this: a page meets the template once, the checker many times, and the upgrader when the design changes.

Remember: a page is copied from the template once, then checked and upgraded for as long as it lives.

Chapter 3 of 5, about 2 minutes

What runs when you save a page?

Before this: a page is checked many times, and the hook and CI do the repeating.

Two chains run the checker for you. The hook runs while Claude Code works. CI runs when you push.

The hook, inside one Claude Code turn

  1. Claude saves the page with Write or Edit. hooks.json:13
  2. The hook notes it if it looks like an explainer. explainer-check:54
  3. When the turn ends, the stop step asks the checker about each noted page. explainer-check:139
  4. check.mjs returns its FAIL lines. explainer-check:118
  5. A FAIL exits 2, so Claude fixes it. Three blocks at most. explainer-check:169 explainer-check:14

CI, after a push

  1. You push to main or open a pull request. ci.yml:3
  2. The check job runs check-repo on Node 18. ci.yml:19 ci.yml:21
  3. check-repo checks each shipped page, then five more things. check-repo.mjs:34
  4. On main only, and after check passes, the site job copies the shipped files into _site. ci.yml:24 ci.yml:38
  5. The Pages action deploys that folder. ci.yml:49

Take from this: both chains end at the same checker. They differ in when they run and who sees the result.

Remember: the hook runs the checker at the end of a turn, and CI runs it on every push.

Chapter 4 of 5, about 1 minute

Who catches what?

Before this: the hook and CI both end at the same checker.

No single check catches everything. Each failure below has one part that owns it.

Which part catches which failure
Failurecheck.mjsHookupgrade.mjscheck-repoanchors.mjs
A page breaks a ruleYesYesPartlyPartlyNo
Gallery out of syncNoNoNoYesNo
A skill path is staleNoNoNoYesNo
A page is out of dateNoNoYesNoNo
An atlas anchor is offPartlyNoNoNoYes

Take from this: the checker owns page rules and check-repo owns repository rules. Only anchors.mjs reads an atlas's line numbers.

Show where each owner does its work

Yes. check.mjs prints FAIL lines and sets the exit code at check.mjs:586. The hook blocks the turn with exit 2 at explainer-check:169. upgrade.mjs swaps the blocks at upgrade.mjs:106. check-repo compares the gallery at check-repo.mjs:42 and checks skill paths at check-repo.mjs:55. anchors.mjs counts anchors out of range at anchors.mjs:62.

Partly. upgrade.mjs re-checks only the page it upgraded, at upgrade.mjs:137. check-repo checks only the shipped pages, at check-repo.mjs:24. check.mjs checks that an anchor has both attributes, not that the line exists, at check.mjs:336.

Remember: each failure has one owner, so a pass from one check proves nothing about another.

Chapter 5 of 5, about 2 minutes

How does it ship, and what is not live?

Before this: each failure has one owner, and CI is the last guard before the site.

A release is a short, fixed path. Users get it through the marketplace, and the site redeploys from main on its own.

  1. Bump the version. plugin.json and the template's mark move together. plugin.json:4 check-repo.mjs:76
  2. Run check-repo. Then the strict plugin validation. CONTRIBUTING.md:72
  3. Merge, tag and release. To main, a vX.Y.Z tag, a GitHub release. CONTRIBUTING.md:73
  4. Let users update. The plugin lists three skills, and the marketplace delivers it. plugin.json:13 CONTRIBUTING.md:74

Take from this: a release is four steps. The site is not one of them, because it redeploys when main changes. ci.yml:25

Dormant: the root skill shim. Parked on 13 October 2026. It returns only if someone asks to clone the repository as one skill. root-skill-shim.md:9

Target: a render flag. The roadmap adopts a browser check for December. The checker takes no such flag yet. ROADMAP.md:19

Show the glossary and how this page was checked
Skill
A folder with a SKILL.md that an agent reads when a request matches.
Template
The one HTML file every page starts from.
Checker
The script that decides whether a page passes.
Hook
A script Claude Code runs on an event, such as the end of a turn.
Anchor
A file and line that backs a claim on this page.
Snapshot
This page is true at one commit and says so.

Every anchor was checked against commit b33f303 with the anchor script.

node skills/explainer-atlas/scripts/anchors.mjs skills/explainer-atlas/examples/atlas/index.html --repo . --rev b33f303

Remember: a release is four steps, and anything parked or planned is marked as such.

Recap

  1. Two files carry the weight, and everything else decides when to run them.
  2. A page is copied from the template once, then checked and upgraded for as long as it lives.
  3. The hook runs the checker at the end of a turn, and CI runs it on every push.
  4. Each failure has one owner, so a pass from one check proves nothing about another.
  5. A release is four steps, and anything parked or planned is marked as such.