| name | refresh-snapshots |
| description | Use to re-run the harness's snapshot/mirror flows so installed state matches version-controlled source — skill symlinks into ~/.claude, ~/.codex, ~/.gemini tool homes, git submodule pointers, and shell plugin checkouts. Use after restructuring skills, when links look stale or broken, or on a periodic freshness pass. Triggers: "refresh snapshots", "relink skills", "update submodules", "my installed skills are stale".
|
| metadata | {"owner":"tze","authors":["tze","Claude Fable 5"],"status":"active","last_reviewed":"2026-06-12"} |
| compatibility | Assumes ~/.dotfiles with bootstrap.sh and the ai-bootstrap submodule; flows are idempotent and safe to re-run. |
Refresh Snapshots
Several pieces of installed state are snapshots of version-controlled
source: symlink trees generated by bootstrap.sh, submodule checkouts
pinned to a recorded commit, plugin clones. They go stale silently when the
source moves. Every flow here is idempotent — re-running a fresh one is a
cheap no-op.
Health check without refreshing
To answer "is my harness healthy" without changing anything, run the
doctor — it executes every flow's verify check (broken links, submodule
drift, shell load, bd doctor, required binaries) as one pass/fail report:
bash <this-subskill>/scripts/harness_doctor.sh
Keep scripts/harness_doctor.sh in sync
when adding a flow to the catalog.
Workflow
- Read the flow catalog:
references/snapshot-flows.md — it
lists each snapshot, its refresh command, and its verification check.
- Run the refresh for the flows the task needs (or all of them on a
periodic pass), then run each flow's verification and report
refreshed/already-fresh/failed per flow.
- If a refresh changed git state (e.g. a submodule pointer moved), commit
it per the owning repo's conventions — pointer bumps in
~/.dotfiles
use the existing Update ai-bootstrap pointer message style.
- Write back (maintenance contract): if you discover a snapshot flow
not in the catalog — any script that copies or links version-controlled
content into a runtime location — append it to
references/snapshot-flows.md in the
same change.
Boundaries
- Refreshing a checkout to its recorded pointer (
git submodule update)
is always safe; advancing a pointer (--remote) changes behavior —
do it only when the task asks for updates, and report what moved.
- If a verification fails after refresh (broken links remain, a skill
vanished from a tool home), stop and diagnose before re-running — the
flows are idempotent, so a second blind run cannot fix a real failure.
- Some machines symlink tool homes wholesale (
~/.claude →
ai-bootstrap/.claude); others may copy. Confirm with ls -ld ~/.claude
before reasoning about which flow applies.
