Ship teach-artifact, the artifact-tools skill that teaches instead of recaps

Context

The story behind this plan — what prompted the work and why it matters now.

The artifact-tools plugin already separates its publishing engine from its framing. The three recap commands (eng-recap, team-recap, product-doc) are short files of 60 to 68 lines each; all the real machinery lives in one shared 276-line reference, references/recap-core.md, which owns source resolution, the blocking secret-scanning gate, the page-build rules, and the record that lets a re-run republish to the same link. Each command declares only five things: its audience, its section list, its favicon, its inbox filename stem, and its republish key.

That structure is why this work is small. teach-artifact reuses recap-core unchanged and supplies a different frame, so version 1 ships zero new source-gathering code.

The gap it fills is real and was measured, not assumed. Two skills in the kit already teach — social-media-tools:write-guide writes long-form Markdown into a guides/ folder, and social-media-tools:share-explanation produces a social-card image — but neither publishes a shareable page. The four skills that do publish pages all either recap a change or reproduce a document verbatim. A teaching page is the one combination nothing produces.

The main risk is overlap with team-recap. A teaching page about a session and a team recap of that session can drift into the same document. The mitigation is that the section spine must be teaching-shaped, and step 1 gives that spine its own file so it can be reviewed on its own terms. The stop condition is explicit: if the first real page reads as a team-recap variant, the skill has not earned its slot and should be reconsidered as a fourth recap command instead.

Five choices were settled with the plan's author during the planning interview on 2026-08-07, and are recorded here so a later reader can tell a decision from an assumption. Two of them were the proposal's open questions, answered rather than carried forward: the skill reuses references/recap-core.md directly instead of forking a teach-core.md, because tests/plugins/test-recap-command-dedupe.sh exists precisely to stop the duplication a fork would reintroduce — 168 lines once diverged badly enough that a scrub-gate fix landed in one file out of three; and the section spine is fixed for both sources rather than picked per source, because a fixed heading list is what makes the anti-overlap assertion in step 3 possible at all.

The remaining three shape what actually gets written. The skill opts into recap-core's 20-file diff-hunk budget in pull-request mode, as eng-recap does and the other two commands deliberately do not, because teaching how something works needs the real signatures and error paths that commit messages never carry. The mental-model section earns a diagram by default, inverting recap-core's rule that a diagram is earned only where something changed — a page teaching a system that did not change this week is exactly the page most in need of one. And every diagram carries a prose sentence alongside its caption, because recap-core's documented fallback ships diagram blocks as plain text whenever the browser pane is unavailable, so content living only inside an image is content that can disappear.

Two consequences were discovered by reading the tests rather than the source. The plugin's guard at tests/plugins/test-artifact-tools.sh hard-codes the four current skill names in its validation loop, and continuous integration runs it — so a fifth skill added without touching that file ships completely untested. And because the plan touches a second plugin's README, that plugin needs its own version bump; any edit under a plugin directory does.

This plan sets workflow: never. The renderer would otherwise offer to fan the work out across parallel agents, because it counts seven files across three top-level directories — but the steps are strictly sequential. The tests cannot be written before the skill exists, and the documentation cannot describe a shape that is not settled.