sn-update

sn-update

Refresh installed sn-* skills from upstream

SenseNova-Skills.

---

Decide the scope

• No list given → every sn-* skill upstream.
• Specific skills named → only those. Don't expand.
• A named skill missing upstream → surface as error and stop.
• User said "force / 强制" → re-install even when up-to-date.

---

Decide the target agent

Check which directories exist:

| ~/.openclaw/skills/ | ~/.hermes/skills/ | Target |

|---|---|---|

| exists | absent | openclaw |

| absent | exists | hermes |

| exists | exists | ask the user — never silently dual-write |

| absent | absent | no install found, stop |

---

Sync the upstream repo

Persistent cache at ~/.cache/sn-update/repo/. Default URL:

https://github.com/OpenSenseNova/SenseNova-Skills.git. User may override

with a fork URL.

• First run: if you want to actually limit blob download, use partial

clone with --filter=blob:none --no-checkout, then sparse-checkout only

the selected skills/<name> paths before copying them. --filter=blob:none

alone does not keep the cache small if the full worktree is checked out;

that checkout will still download most or all needed blobs. It still

preserves history metadata for SHA queries.

• Subsequent runs: fetch + hard-reset to the upstream default branch, and

re-apply sparse-checkout for only the requested skills/<name> paths before

copying. If updating the whole sn-* bundle, expect most/all skill blobs to

be downloaded.

• URL changed: if cache's origin differs from the requested URL,

delete and re-clone.

---

Compare versions per skill (A → B → C)

For each skill, pick the highest-precedence signal present on both

sides (installed + upstream); equal → skip, differ → install.

Upstream "version" is the per-subtree commit SHA — using repo HEAD would

mark unrelated skills as stale every time:

git -C <cache> log -1 --format=%H -- skills/<skill-name>

• A — .sn-version marker: one-line file inside the installed skill

holding the SHA from its last install.

• B — .sn-release marker (fallback): one-line file holding the

upstream tag name. Compare against git describe --tags --abbrev=0.

• C — optional version: field in SKILL.md frontmatter: parse from

YAML on both sides, but only for forks or skills that explicitly add this

field. If either side lacks it, C does not apply.

• Nothing usable → treat as stale and install.

Always write .sn-version on install so future runs can use A.

---

Install with backup

For each skill flagged "install":

1. Move (not copy) any existing <agent-skills>/<skill-name>/ into a

single timestamped backup bucket shared by all skills in this run:

~/.<agent>/skills_backup/<UTC-timestamp>/<skill-name>/

(e.g. 2026-04-30T15-29-07Z).

1. Copy <cache>/skills/<skill-name>/ → <agent-skills>/<skill-name>/.

Never symlink (ln -s) from the cache. The cache lives under

~/.cache/ with permissions the agent runtime may not be able to

traverse, and some runtimes refuse to load skills resolved through

symlinks. Always do a real recursive copy so the installed tree is

self-contained and owned by the agent skills dir.

1. Write .sn-version with the upstream subtree SHA inside the new copy.

If the bucket ends up empty (all targets were fresh installs), remove it.

The backup tree is a sibling of skills/, never a .bak folder

inside it — most agent runtimes scan the whole skills/ directory and

would pick up stale duplicates.

---

Enforce backup retention

After every run, prune the per-agent backup root to at most 3 buckets.

Timestamps sort lexicographically; keep the newest 3, delete the rest.

Run this even when the current run produced no backup of its own.

---

Report to the user

Group by status, keep it short:

Updated (3): sn-ppt-standard, sn-image-base, sn-deep-research
Already up-to-date (5): sn-ppt-creative, sn-ppt-doctor, ...
Backup: ~/.openclaw/skills_backup/2026-04-30T15-29-07Z/

• Omit Backup: when nothing was backed up.
• Show SHA pairs (abc1234 → def5678) only if the user asks for detail.
• Errors get their own line — never bury them in a success summary.

---

Edge cases

• **Asks to delete sn- skills* — not this skill's job. Decline; point at

~/.<agent>/skills_backup/ if they want to roll back.

• User is in the dev repo and asks to "update sn skills" — they mean

push to their agent install. Proceed normally; this skill only touches

the cache and the agent install dirs, never the dev checkout.

• sn-update updating itself — fine; the new copy takes effect on

the next invocation.