Publicar e versionar skills
Publicar é o ato de transformar um rascunho em uma versão que entra no catálogo da organização e chega aos usuários. Esta página cobre as regras de versionamento, a idempotência da publicação, rollback e arquivamento, e como os clientes sincronizam. Para criar a skill, veja Criar no Skill Studio; para empacotar de fora, Importar via ZIP.
A versão é o campo version do manifesto
A versão publicada é exatamente o campo version do manifesto — uma string semver (ex.: 1.0.0, 2.3.1). Não há um número gerado pelo sistema: você controla a versão editando o manifesto.
No Skill Studio, ao publicar você também informa um changelog — obrigatório — descrevendo o que mudou nesta versão. O banner de manifesto bloqueia a publicação enquanto o manifesto estiver inválido.
A publicação acontece dentro de um grupo de skills. Se nenhum grupo for indicado, a operação é recusada (group_required). Veja Grupos de skills.
Idempotência e a regra "bump ao mudar"
A publicação é idempotente por par (versão, conteúdo):
| Situação | Resultado |
|---|---|
Mesma version + mesmo conteúdo | No-op. A versão já publicada é confirmada (a resposta marca idempotent). |
Mesma version + conteúdo diferente | 422. Você precisa fazer bump da version no manifesto. |
version nova | Publica normalmente: a versão atual é depreciada e a nova é promovida. |
Republicar a mesma versão com conteúdo diferente é recusado com 422 de propósito — versões publicadas são imutáveis. Incremente a version (ex.: 1.0.0 → 1.0.1) antes de publicar a mudança.
Promoção, depreciação e rollback
- Promoção. Publicar uma versão nova a torna a versão ativa; a anterior é depreciada (sai de circulação para novas sessões, mas continua no histórico).
- Rollback. Em Version History (no editor da skill), você cria uma nova versão a partir de uma antiga. O rollback não "apaga" versões — ele promove o conteúdo antigo como uma nova entrada na linha do tempo.
- Archive. Arquivar a skill a remove dos usuários: ela deixa de ser sincronizada e some das listas. Use quando uma skill é descontinuada.
Como os clientes recebem a nova versão
Publicar invalida a política da organização. O efeito em cadeia:
- A próxima requisição que avalia política rebusca o catálogo atualizado.
- No início de cada sessão, os clientes (Desktop, TUI, VS Code) sincronizam as skills a que você tem acesso para
~/.imaginne/skills/, e removem as que você perdeu acesso.
Ou seja: o usuário recebe a versão nova ao iniciar uma nova sessão após a publicação — não no meio de uma conversa em andamento. No Desktop, há uma notificação de sync de skills. Veja Notificações.
Publicar coloca a skill no catálogo, mas quem decide quem a recebe são os perfis. Uma skill publicada sem perfil associado não chega a nenhum usuário. Veja Governança de skills.
Publicar do Desktop ou da TUI
Você também pode publicar uma skill local direto das superfícies, sem montar um ZIP:
- Desktop — o comando
/publish-skill(ou o modal de publicação): escolha uma skill local, pré-visualize o manifesto, escolha um grupo (obrigatório) e Publique. Depois, "Open in /app" abre a skill no console. - Terminal (TUI) —
/skill publish <key> --group <slug|id> [--mode local_plain|local_protected]. Antes, valide com/skill validate [path|key]e descubra os grupos com/skill groups.
Em ambos os casos, valem as mesmas regras de versionamento e idempotência descritas acima. Veja a referência de comandos em Comandos da TUI e Atalhos do Desktop.
Fluxo recomendado
- Edite a skill e incremente a
versionse mudou o conteúdo. - Confira o banner de manifesto (verde).
- Escreva o changelog.
- Publique no grupo correto.
- Garanta que a skill está atribuída a um perfil.
- Os usuários recebem na próxima sessão.
Veja também
Esta página ajudou?
Reportar um problema nesta páginaNão envie senhas, chaves, tokens ou dados de clientes.