Canonical file: Documents/Projects/admin/scheduled-tasks/SKILL-VERSIONING.md. This page mirrors it.

The core idea

The version number is not the fix. A machine-readable marker (frontmatter) + one writer + a hash check is the fix.

1. Frontmatter on every SKILL.md

---
name: daily-briefing
version: 10.1.0
updated: 2026-06-13
canonical: Documents/Claude/Scheduled/daily-briefing/SKILL.md
source_of_truth: notion://<page-id>
sha256: <hash of body below frontmatter>
---

Changelog stays at the bottom as the human story, not the version source.

2. Semver bumps

• MAJOR: changes what the run does/outputs (retire a channel, switch a lane).
• MINOR: new capability, backward compatible (competitor auto-negate rule).
• PATCH: wording, fixes, ID/path corrections.

3. Hash is the truth

In sync only if body sha256 matches. Stale if version/updated is behind canonical. Never trust the number alone.

4. registry.json is the manifest

One row per skill: canonical_path, source_of_truth, current_version, sha256, updated, mirrors[]. Current = highest version, ties by updated, canonical_path is authority. Mirrors are read-only generated copies.

5. One writer per skill

Edit only the canonical copy. All other copies are generated, never hand-edited.

6. Edit checklist

1. Edit canonical only. 2. Back up (.bak-YYYY-MM-DD-pre-<change>). 3. Bump version, set updated, recompute sha256. 4. Add changelog line. 5. Update registry.json row. 6. Resync mirrors (overwrite, not merge).

7. Drift detection and healing

Guard on a schedule (fold into the daily run): hash each mirror vs canonical. Purely behind: auto-overwrite + log. Body diverged (second writer): do NOT auto-heal, flag with a diff for Sam, port unique facts, then overwrite. Log result to run report or QA queue.