Deprecating & unpublishing

Retiring a skill, yanking a bad version, admin-only unpublish, and how consumers see the change.

Skills evolve, and sometimes you need to steer people away from an old skill or a bad release. SkillHub gives you three tools with clearly different blast radii: deprecate a skill, yank a version, and unpublish a version.

Tool	Scope	Removes bytes?	Who
Deprecate	Whole skill	No — installs keep working	Publisher
Yank	One version	No — installs keep working	Publisher
Unpublish	One version	Yes — permanent	Admin, time-limited

Deprecate a whole skill

Deprecating marks the entire skill as discouraged, usually because there's a better replacement. It doesn't delete anything — installed versions keep working, and consumers see the deprecation as a signal to move on.

skillhub deprecate @studio/design-systems/old-skill "Use tokens-workflow instead"

{
  "ok": true,
  "data": { "action": "deprecated", "ref": "@studio/design-systems/old-skill", "message": "Use tokens-workflow instead" }
}

Yank a specific version

Appending @<version> to the ref yanks that one version instead of deprecating the whole skill. Yank a version when a specific release is broken but the skill itself is fine:

skillhub deprecate @studio/design-systems/tokens-workflow@1.0.0 "Bad release"

{
  "ok": true,
  "data": { "action": "yanked", "ref": "@studio/design-systems/tokens-workflow", "version": "1.0.0", "reason": "Bad release", "yankedAt": "…" }
}

The same command does both jobs — the presence of @<version> is what decides between deprecating the skill and yanking a version.

Unpublish a version

Unpublish permanently removes a published version. Because published versions are meant to be immutable, this is deliberately restricted:

skillhub unpublish @studio/design-systems/tokens-workflow@1.2.3

Unpublish is admin-only and time-limited — you can only remove a version within a short window after it was published. Outside that window, deprecate or yank instead.

Unpublish always targets an exact skill@version. There's no way to unpublish a whole skill or an arbitrary-age version — that's what deprecate is for.

How consumers see it

People who have your skill installed learn about all of this through skillhub outdated, which surfaces deprecation, yank, and rename status per installed skill:

skillhub outdated

Each reported skill carries deprecated, renamedTo, and yanked fields alongside the usual current / wanted / latest versions, so consumers can see exactly why they should move.

Renames leave a redirect

If you rename a skill, the old name keeps working through a redirect alias — old refs still resolve. skillhub outdated reports the new name in renamedTo so installed consumers can follow the move on their own schedule.