Worked Example: The vault-sync Skill

The skill behind this site's weekly refresh (.claude/skills/vault-sync/SKILL.md). Every week an automated Claude Code session invokes it to check whether Anthropic shipped new courses, tracks, exams, or terminology — and if so, to propagate the changes all the way from research to redeploy.

The refresh loop it encodes

1. Diff the world against the vault — fetch the Academy catalog, the partner certification pages, anthropic.com/learn, and release notes; compare against index.md and the certifications overview note. The vault is the state; the web is the target.
2. Update the source of truth first — new knowledge lands as vault notes (with - **Term** — definition bullets so flashcards regenerate automatically), never directly in app code. Broad, net-new topics get the Co-STORM deep-note path — a docs-grounded roundtable of opposing subagents — instead of one-pass drafting; narrow edits stay one-pass.
3. Propagate mechanically — tracks config, exam blueprints, then node scripts/build-content.mjs regenerates every JSON the site consumes. New exams get question banks via skill-storm-questions.
4. Ship conditionally — commit + vercel --prod only when something actually changed; a no-op week produces a "no changes" report and zero deploys.

Design lessons worth stealing

• Idempotence — running it twice in a row must be safe. The "diff first, act second" structure guarantees that.
• Layered content model — vault (markdown, human-editable) → generated JSON (machine artifact, committed for reproducible builds) → UI. Each layer only reads the one above.
• Automation-first wording — the skill is written so an unattended session can follow it: explicit URLs, explicit commands, explicit stop condition.

Key terms

• Vault-first update — the rule that knowledge changes land in the vault before any derived artifact.
• Conditional ship — commit/deploy gated on a real diff, so automation never produces empty commits.
• Idempotent automation — a job that can re-run without corrupting state or duplicating work.

The canonical copy lives at .claude/skills/vault-sync/SKILL.md; the schedule that fires it weekly is described in how-this-site-works.