Updating skills and the CLI¤
Two different things get updated, with two different commands. Mixing them up is the most common confusion:
| You want to update… | Command |
|---|---|
| The skills you installed | humblskills update |
The humblskills binary itself |
humblskills upgrade |
Updating installed skills¤
humblskills update # pick from the list of skills that drifted
humblskills update --check # print what would change, change nothing
humblskills update --all --yes # update everything, no prompts (CI-friendly)
humblskills update smart-commit # just one skill
Run with no arguments on a normal terminal and you get a picker listing every skill whose installed copy differs from what its registry now publishes. Nothing is written until you confirm.
A skill counts as drifted when its version or its registry content hash has changed. The humblSKILLS repo's own commit SHA is deliberately not used — it moves on every commit, which would flag every skill as stale after each CLI release.
update re-checks each skill against the registry it was installed from, so
a mixed public + private setup updates correctly.
Your customizations survive¤
By default update keeps the files a skill declares in metadata.preserve —
memory files, curated notes, raw sources. This is what makes a "smart" skill's
accumulated knowledge survive an upgrade. See
Preserving user content for the full contract.
To throw your local changes away and take exactly what the registry ships:
--force is the one update mode that destroys content, so it now lists the
user-owned files it would overwrite and asks you to confirm. In a pipe, in CI,
or with --json there is nobody to ask, so it stops instead of guessing:
$ humblskills update --force smart-commit --json
humblskills: update --force: overwrites user-owned files: smart-commit
(references/log.md, references/decisions.md) — re-run with --yes to confirm
The same gate covers install --force, sync --force, sync --prune and
uninstall. In the TUI, f on the update list and the force reinstall
toggle in the install modal reach the same behaviour, so neither surface can do
something the other can't.
Adding a platform to skills you already have¤
Installed a new agent (Codex, say) and want your existing skills on it too? Add
it to your profile's default_platforms, then:
humblskills update --platforms # add missing platforms + apply any drift
humblskills update --check --platforms # preview, change nothing
Every platform target is a symlink into one canonical store, so covering a new
platform is a symlink plus a manifest entry. When the skill is already current
nothing is downloaded and no file in the store is touched — the summary says
linked rather than installed to make that explicit:
$ humblskills update --check --platforms
1 skill to act on:
smart-commit link only (+codex, no content change)
If a skill is drifted, the refresh and the new platform happen in one pass, so
you don't need two commands. Skills that declare a platforms allow-list are
only offered the platforms they support.
When a skill gets renamed¤
Skills occasionally get renamed upstream (for example, the use-* family was
renamed to smart-*). You don't have to do anything special — update follows
the rename instead of skipping it:
The picker and the update summary show the rename explicitly, as
use-smart-commit → smart-commit, so you can see what's happening before you
confirm.
What happens:
- The new skill is installed under its new name.
- Your preserved files are carried across from the old install — memory, notes, and raw sources move with the skill.
- The old installation is retired.
humblskills update <new-name> also reaches an install still recorded under the
old name, so you can update by the name you now know the skill by.
Renames are never guessed
A rename is only followed when a registry skill explicitly claims the old
name via previous_names in its frontmatter. A name that is still published
in its own right is never treated as a rename target, and a name claimed by
two skills is ignored rather than resolved by guessing. If a skill simply
disappeared from the registry, update leaves your copy alone — there is
nothing to upgrade to.
Upgrading the CLI¤
humblskills upgrade # profile channel (stable if unset)
humblskills upgrade --channel beta # this run only; does not write the profile
humblskills upgrade --dry-run
humblskills profile get channel
humblskills profile set channel beta
The upgrade checks GitHub releases (stable → /releases/latest only; beta →
the higher semver of latest stable vs latest prerelease), verifies the
checksum, and replaces the running binary in place. Beta is “always the newest
version”: v2.52.0 beats v2.52.0-pre.3; v2.52.1-pre.1 beats v2.52.0.
The same resolver feeds the CLI update notice and the TUI Dashboard banner.
When a newer release exists, doctor, start (and the non-TTY command table),
version, list, search, and profile show print this line on stderr:
Homebrew-managed installs get brew upgrade humblskills,
brew upgrade humblskills-pre, or
brew uninstall humblskills-pre && brew install humblskills when beta’s
winner is a graduated stable. --json and --quiet suppress the notice;
being current is silent. The interactive dashboard (humblskills /
humblskills start) shows a Newer version available banner above the
search bar and tile grid — not only in Profile. The latest tag is cached
under selfupdate/latest-<channel>.json (12 hours).
The channel is the same profile.json field Homebrew uses. Change it from the
existing Profile TUI (humblskills → Profile → install channel) or
profile set — there is no second settings surface.
If you installed via Homebrew, upgrade detects that and delegates. The
formula follows beta’s winner, not the channel name:
brew upgrade humblskills # stable winner, already on humblskills
brew upgrade humblskills-pre # beta winner is still a pre
brew uninstall humblskills-pre && brew install humblskills # beta winner is a graduated stable
upgrade runs those commands itself after confirming, so Homebrew's own
bookkeeping stays correct. It falls back to telling you to run brew by hand
only when brew isn't on PATH.