Skills: Gerenciamento de Versão e Atualizações
Última atualização: 2026-08-31
Uma Skill não está pronta quando escrita — ela evolui. Gerenciamento de versão torna a evolução rastreável, reversível e coordenada.
1. Versionamento Semântico
(1) Regras de Numeração de Versão
TEXT
📖 Somente leitura
MAJOR.MINOR.PATCH
MAJOR: Mudanças incompatíveis (mudança de formato de saída, mudança de vinculação de ferramenta)
MINOR: Adições compatíveis (nova dimensão de revisão, novo trigger)
PATCH: Correções compatíveis (otimização de prompt, atualização de exemplo)
(2) Exemplos de Mudança de Versão
| Mudança | Atualização de Versão | Motivo |
|---|---|---|
| Adicionar dimensão de revisão de segurança | 1.0.0 → 1.1.0 | Adição compatível |
| Corrigir ambiguidade do prompt | 1.1.0 → 1.1.1 | Correção compatível |
| Mudar formato de saída para JSON | 1.1.1 → 2.0.0 | Mudança incompatível |
| Adicionar trigger Git | 2.0.0 → 2.1.0 | Adição compatível |
2. Changelog
(1) Formato do CHANGELOG
MARKDOWN
# Changelog
## [2.1.0] - 2026-08-20
### Adicionado
- Adicionado trigger Git diff
- Adicionado opção de saída em diagrama Mermaid
### Alterado
- Otimizado prompt de revisão, reduzido output alucinado
### Corrigido
- Corrigido erro de parsing de bloco de código aninhado
## [2.0.0] - 2026-08-01
### Quebra de Compatibilidade
- Formato de saída mudou de texto simples para Markdown estruturado
- Nome de variável mudou de `file` para `target_file`
### Migração
- Atualizar referências de variáveis: `{{file}}` → `{{target_file}}`
- Parsing de saída precisa se adaptar ao novo formato (veja guia de migração)
(2) Guia de Migração
Mudanças incompatíveis devem incluir um guia de migração:
MARKDOWN
## Guia de Migração: v1 → v2
### Mudanças de Variáveis
- `{{file}}` → `{{target_file}}`
- `{{level}}` → `{{severity_level}}`
### Mudanças de Formato de Saída
- v1 texto simples → v2 Markdown estruturado
- Marcadores de severidade: `[CRITICAL]` → `🔴`
### Mudanças de Vinculação de Ferramentas
- Nova dependência: Grep (para busca de contexto)
3. Estratégia de Compatibilidade Retroativa
(1) Princípios de Compatibilidade
TEXT
📖 Somente leitura
Três Princípios de Compatibilidade
├── Formato de saída: Novos campos não afetam campos antigos
├── Sistema de variáveis: Novas variáveis têm padrões; variáveis antigas permanecem utilizáveis
└── Triggers: Novos triggers não quebram os existentes
(2) Processo de Depreciação
TEXT
📖 Somente leitura
Processo de Depreciação (abrangendo 3 versões)
1. v1.1.0: Marcar como depreciado, ainda utilizável, emitir aviso
2. v1.2.0: Desabilitado por padrão, requer ativação explícita
3. v2.0.0: Completamente removido
(3) Camada de Compatibilidade
MARKDOWN
## Design de Camada de Compatibilidade
Suportar nomes de variáveis antigos e novos:
{{#if target_file}}
Arquivo alvo: {{target_file}}
{{#else if file}}
⚠️ Variável `file` está depreciada, por favor use `target_file`
Arquivo alvo: {{file}}
{{/if}}
4. Sincronização de Atualizações de Equipe
(1) Estratégia de Atualização
| Estratégia | Descrição | Ideal Para |
|---|---|---|
| Auto-atualização | Versões PATCH aplicadas automaticamente | Pequenas correções |
| Notificar atualização | Versões MINOR notificam usuários | Novas funcionalidades |
| Atualização com aprovação | Versões MAJOR requerem confirmação humana | Mudanças incompatíveis |
(2) Fluxo de Sincronização
TEXT
📖 Somente leitura
Fluxo de Atualização de Skills da Equipe
1. Mantenedor publica nova versão + CHANGELOG
2. Notificar equipe (Slack/email/comentário PR)
3. Membros da equipe fazem git pull para obter atualizações
4. Versões MAJOR requerem revisão do guia de migração
5. Verificação de testes locais
6. Confirmar e commitar adaptações do projeto
(3) Fixação de Versão
YAML
# Projeto fixa versões de Skills
skills:
code-review:
version: "^1.5.0"
deploy:
version: "2.0.0"
❓ Perguntas Frequentes
P: Toda mudança requer bump de versão? R: Ajustes de prompt (como melhorias de redação) não precisam. Mudanças que afetam formato de saída, variáveis ou vinculações de ferramentas sim. P: E se membros da equipe não atualizaram? R: Adicionar verificações de versão de Skill no CI; versões desatualizadas causam falha no build com prompt de atualização. P: Como reverter para uma versão antiga? R:
git checkout v1.5.0 -- .claude/skills/code-review.md, ou encontrar o arquivo da versão antiga pelo CHANGELOG.
📖 Resumo
- Versionamento semântico: MAJOR incompatível, MINOR adições, PATCH correções
- Changelog: Adicionado / Alterado / Corrigido / Quebra de Compatibilidade + guia de migração
- Compatibilidade retroativa: Novas adições não afetam existentes; depreciação abrange 3 versões; camadas de compatibilidade
- Sincronização de equipe: PATCH automático, MINOR notificar, MAJOR aprovação
📝 Exercícios
- Básico (⭐): Adicione números de versão e CHANGELOG às suas Skills criadas.
- Intermediário (⭐⭐): Projete uma atualização incompatível com guia de migração e camada de compatibilidade.
- Avançado (⭐⭐⭐): Projete um mecanismo de sincronização de versão de equipe com fixação de versão, verificação automática e fluxos de aprovação de upgrade.
