Publish and version skills
Publishing is the act of turning a draft into a version that enters the organization's catalog and reaches users. This page covers the versioning rules, the idempotency of publishing, rollback and archiving, and how clients sync. To create the skill, see Create in Skill Studio; to package it from outside, Import via ZIP.
The version is the manifest's version field
The published version is exactly the manifest's version field — a semver string (e.g. 1.0.0, 2.3.1). There's no system-generated number: you control the version by editing the manifest.
In Skill Studio, when you publish you also provide a changelog — mandatory — describing what changed in this version. The manifest banner blocks publishing while the manifest is invalid.
Publishing happens inside a skill group. If no group is specified, the operation is refused (group_required). See Skill groups.
Idempotency and the "bump on change" rule
Publishing is idempotent per (version, content) pair:
| Situation | Result |
|---|---|
Same version + same content | No-op. The already-published version is confirmed (the response is marked idempotent). |
Same version + different content | 422. You need to bump the version in the manifest. |
New version | Publishes normally: the current version is deprecated and the new one is promoted. |
Re-publishing the same version with different content is refused with a 422 on purpose — published versions are immutable. Increment the version (e.g. 1.0.0 → 1.0.1) before publishing the change.
Promotion, deprecation, and rollback
- Promotion. Publishing a new version makes it the active version; the previous one is deprecated (it leaves circulation for new sessions but stays in the history).
- Rollback. In Version History (in the skill editor), you create a new version from an older one. Rollback doesn't "delete" versions — it promotes the old content as a new entry on the timeline.
- Archive. Archiving the skill removes it from users: it stops being synced and disappears from the lists. Use it when a skill is discontinued.
How clients receive the new version
Publishing invalidates the organization's policy. The chain of effects:
- The next request that evaluates policy re-fetches the updated catalog.
- At the start of each session, clients (Desktop, TUI, VS Code) sync the skills you have access to into
~/.imaginne/skills/, and remove the ones you've lost access to.
In other words: the user gets the new version when starting a new session after publishing — not in the middle of an ongoing conversation. On Desktop, there's a skill sync notification. See Notifications.
Publishing puts the skill in the catalog, but who decides who receives it are the profiles. A skill published without an associated profile reaches no user. See Skill governance.
Publishing from Desktop or the TUI
You can also publish a local skill straight from the surfaces, without assembling a ZIP:
- Desktop — the
/publish-skillcommand (or the publish modal): pick a local skill, preview the manifest, choose a group (required), and Publish. Afterward, "Open in /app" opens the skill in the console. - Terminal (TUI) —
/skill publish <key> --group <slug|id> [--mode local_plain|local_protected]. First, validate with/skill validate [path|key]and discover the groups with/skill groups.
In both cases, the same versioning and idempotency rules described above apply. See the command reference in TUI commands and Desktop shortcuts.
Recommended flow
- Edit the skill and increment the
versionif you changed the content. - Check the manifest banner (green).
- Write the changelog.
- Publish to the right group.
- Make sure the skill is assigned to a profile.
- Users receive it in their next session.
See also
Was this page helpful?
Report a problem on this pageDo not send passwords, keys, tokens, or customer data.