Skill Local Overlay

Purpose: stop losing local modifications when marketplace/connector/builtin skills upgrade. In-place edits to those layers are wiped by the next platform update. This skill wraps every change in snapshot → ledger → replay.

Asset Layer Classification (do this first)

1. [Deterministic] Identify which layer the skill lives in:
   - Agent-created (frontmatter agent_created: true, user skills dir): owned locally → edit directly, no overlay needed.
   - Marketplace-installed: overwritten on reinstall/upgrade → overlay required.
   - Connector skills: overwritten when the connector updates → overlay required.
   - Builtin / plugin cache (versioned directories): overwritten on every plugin upgrade → overlay required.

Workflow

1. [Deterministic] Snapshot: before touching anything, copy the original file(s) into the overlay directory with the upstream version recorded: <overlay-root>/<skill-name>/<upstream-version>/<filename>.orig. Standard overlay root: ~/.workbuddy/skills-overlays/.
2. [Deterministic] Ledger entry: append one entry to <overlay-root>/<skill-name>/ledger.md:
   - date, upstream version, file path, what changed and why, snapshot location.
   - One entry per change. No batching multiple edits into one vague entry.
3. [Deterministic] Apply the patch to the live file. Keep patches minimal and additive where possible (small sed-able edits, not full-file rewrites) so they survive upstream drift.
4. [LLM] Replay after upgrade: when the upstream version changes, diff the new upstream file against the snapshot. Re-apply each ledger entry that still applies; report entries that no longer apply cleanly (upstream restructured) for a human decision.
5. [Deterministic] Verify after replay: re-run the diff; confirm every replayed patch is present in the live file; update the ledger with the new upstream version.

Hard Rules

• Never edit a marketplace/connector/builtin skill without a snapshot + ledger entry first.
• Never delete snapshots or ledger history.
• Replay must be idempotent: applying the same patch twice must not duplicate content.
• Patches stay minimal; if a "patch" grows beyond ~50 lines of change, raise it as a fork decision instead of a patch.
• Ledger entries record WHY, not just WHAT.

Failure Handling

• Snapshot copy fails (permissions, path issues): stop, do not edit. Report the exact path and error.
• Upstream upgrade changes a file so a patch no longer applies: keep the live file unpatched, mark the ledger entry STALE, and surface the conflict — never force-merge blindly.
• Overlay directory missing at replay time: treat as fresh start, re-snapshot, recreate the ledger, and note the gap.

Output Format

Report: layer classification → snapshot path → ledger entry ID → patch summary. After replay: per-entry status table (APPLIED / STALE / CONFLICT) + new upstream version.