/commit: Conventional Commits, changesets e changelogs para o seu agente
Uma skill de agente que escreve Conventional Commits no dialeto do seu repositório, cria changesets automaticamente e transforma changelogs em notas de versão que qualquer pessoa entende.
Commits que se encaixam
Todo repositório tem o seu próprio dialeto. A skill lê os tipos, escopos e o idioma que o seu já usa — a partir da configuração do commitlint, do histórico do git e do layout do workspace — e guarda o resultado em cache para nunca precisar deduzir tudo de novo.
fix(ui-button): default missing label and expose aria-disabled
Changesets automáticos
Se o repositório versiona com changesets, toda mudança publicável ganha o seu no mesmo commit: nomes de pacote certos vindos do mapa do workspace, nível de versão vindo do tipo do commit, texto voltado a quem consome. Pacotes ignorados e privados ficam de fora.
Changelogs para pessoas
Transforme qualquer versão em notas em linguagem simples, agrupadas por impacto e em qualquer idioma, sob uma regra rígida: toda linha vem de uma entrada real. Nada é inventado para soar simpático.
Instalação
Dois caminhos: a CLI de skills, para qualquer agente, ou o plugin do Claude Code. Escolha um — os dois instalam a mesma skill.
Qualquer agente: a CLI de skills
Um comando pelo ecossistema aberto de agent skills. Ele detecta os agentes que você tem e conecta a skill em cada um deles.
# Instalar neste projeto (Claude Code, Cursor, Codex, +70 agentes)
npx skills add EduardoLopes/commit-skill
# Ou globalmente — disponível em todos os projetos
npx skills add EduardoLopes/commit-skill --global
# Ver o que tem dentro antes de instalar
npx skills add EduardoLopes/commit-skill --listClaude Code: o plugin
Só funciona no Claude Code, mas se atualiza sozinho a partir do git e tem
comandos com namespace — então /commit continua funcionando mesmo quando
outra skill na máquina reivindica o mesmo nome.
# Registre o marketplace e instale
/plugin marketplace add EduardoLopes/commit-skill
/plugin install commit@commit-skill
# Buscar o catálogo mais recente do git — sem reinstalar
/plugin marketplace update commit-skillPara dar a skill a um time inteiro sem nenhuma configuração, comite isto no
.claude/settings.json do repositório. Cada pessoa ganha o /commit na
próxima vez que abrir o agente, já apontado para as suas convenções.
{
"extraKnownMarketplaces": {
"commit-skill": {
"source": { "source": "github", "repo": "EduardoLopes/commit-skill" }
}
},
"enabledPlugins": { "commit@commit-skill": true }
}Requisitos
Node 18+ para o instalador, git e qualquer agente de código suportado
(Claude Code, Cursor, Codex, …). Para os recursos de changeset, o
repositório precisa de um gerenciador de pacotes — o /commit init
cuida do resto, instalando o changesets v3 quando o runtime permite (Node
22.11+, pnpm 10+, npm 10.9+ ou yarn 4.5+) e caindo para o v2 caso contrário.
Primeiros passos
Prepare no stage o que você quer entregar e deixe a skill fazer a leitura:
# Analisar o que está no stage e comitar
/commit
# Validar uma mensagem que você já escreveu (caminho rápido)
/commit -m "feat(auth): add passwordless login"
# Várias mudanças sem relação? Divida em commits atômicos
/commit --split
# Subir tudo e comitar, pulando o changeset desta vez
/commit --all --no-changeset
# Só me mostre a mensagem, não comite
/commit --dry-runNa primeira execução em um repositório, a skill detecta as suas convenções, mostra o que encontrou e oferece guardar tudo em cache. Aperte Enter para aceitar — todas as execuções seguintes pulam a detecção.
Comandos
| Comando | O que faz |
|---|---|
/commit | Analisa o que está no stage, escreve um Conventional Commit, cria o changeset se o repositório precisar e comita. |
/commit init | Prepara o repositório para changesets e conventional commits: instala o @changesets/cli, ajusta a config, adiciona scripts e guarda as convenções. Migra uma configuração v2 existente para v3. |
/commit changeset | Cria ou verifica arquivos de changeset para mudanças pendentes, sem comitar nada. A verificação roda changeset status --since <base>. |
/commit changelog [versão] | Gera, reescreve ou traduz um changelog ou notas de versão independentes, para uma versão ou intervalo. |
Flags do commit
| Flag | O que faz |
|---|---|
-m "mensagem" | Valida e formata uma mensagem que você fornece — pula a análise de arquivos. |
--split | Divide assuntos sem relação em vários commits atômicos, em ordem de dependência. |
--all | Sobe tudo para o stage antes de analisar (o padrão é só o que já está no stage). |
--no-changeset | Pula o tratamento de changeset neste commit. |
--dry-run | Mostra a mensagem e a prévia do changeset sem comitar. |
Flags do changelog
| Flag | O que faz |
|---|---|
--plain | Reescreve as entradas para quem não é técnico, agrupadas por impacto: Novidades / Melhorias / Correções. |
--lang <código> | Escreve a saída em outro idioma (pt-BR, es, …). Combina com --plain. |
--notes [arquivo] | Gera um documento de notas de versão independente, sem editar nenhum CHANGELOG. |
Como funciona
Todo repositório tem o seu próprio dialeto de Conventional Commits. A skill deduz esse dialeto uma vez e guarda onde toda sessão futura consegue enxergar.
A detecção segue esta ordem de prioridade:
- Configuração de ferramentas.
type-enumescope-enumdo commitlint, commitizen,CONTRIBUTING.md. Isso é lei — se existir, vence. - Histórico do git. Os últimos 200 assuntos revelam os tipos realmente em uso, a regra que gera os escopos e o idioma em que o time escreve.
- Layout do workspace. Workspaces do pnpm e do npm, configuração do turbo e do nx, para mapear caminhos em nomes de pacote.
<!-- commit-conventions:start -->
## Commit conventions (cached by /commit)
- **Format**: Conventional Commits 1.0.0,
descriptions in English, lowercase
imperative, subject ≤ 72 chars
- **Types**: feat, fix, docs, refactor,
perf, test, build, ci, chore
- **Scope rule**: path under packages/
minus the ui/ segment
- **Versioning**: changesets; patch =
fix, minor = feat, major = breaking
<!-- commit-conventions:end -->O cache fica no CLAUDE.md, então ele é comitado, revisável e compartilhado.
Edite à vontade — a skill lê o que você escreveu. Apague o bloco e ela detecta
tudo de novo.
Exemplos
Saídas reais da suíte de testes da skill: uma correção em monorepo, a preparação de um repositório e notas de versão voltadas ao cliente.
Uma correção, seu commit e seu changeset
$ /commit
Analyzing staged changes… 1 file in packages/ui-button
fix(ui-button): default missing label and expose aria-disabled
Created .changeset/ui-button-aria-disabled.md (@acme/ui-button: patch)
and staged it with the commit.---
"@acme/ui-button": patch
---
Buttons no longer render the text "undefined" when created without a
label, and now expose `aria-disabled` so assistive technology announces
the disabled state correctly.O changeset nomeia o pacote real, tira o patch do tipo do commit e é escrito
para quem consome o pacote — não para quem revisa o diff.
Preparando um repositório
$ /commit init
✓ Installed @changesets/cli
✓ Scaffolded .changeset/config.json (baseBranch: main)
✓ Added scripts: changeset, version-packages, release
✓ Detected conventions from 200 commits — free-form history found,
adopting Conventional Commits 1.0.0 going forward
✓ Cached conventions in CLAUDE.md
✓ Committed: build: set up changesets and conventional commitsNotas de versão que qualquer pessoa entende
## 3.2.0
### Minor Changes
- a41f2c9: feat(uploader): add chunked multipart upload with resumable
state persisted to IndexedDB
- 77c01ab: feat(gallery): virtualize grid rendering via IntersectionObserver
### Patch Changes
- 09d11fe: fix(exif): guard against null GPSInfo IFD when parsing orientation
- bb3e802: refactor(store): migrate selectors to memoized createSelector# Photo App — Novidades da versão 3.2.0
## Novidades
- **Envios que continuam de onde pararam.** Se a internet cair ou você
fechar a página no meio de um envio, ele retoma de onde parou.
- **Galeria mais rápida com muitas fotos.** A galeria carrega apenas as
fotos visíveis na tela, conforme você rola a página.
## Correções
- **Fotos sem dados de localização não causam mais erro.**Repare no que sumiu: a entrada interna refactor(store). Mudanças sem efeito
visível para quem usa são descartadas, nunca maquiadas como melhorias.
Casos de uso
Todo /commit verifica se os arquivos no stage tocam um pacote publicado.
Se tocarem, o changeset é criado e adicionado no mesmo commit — nomes de
pacote certos vindos do mapa do workspace, nível de versão vindo do tipo do
commit, ignore, linked e fixed respeitados. PRs de release deixam de
ser arqueologia.
Histórico cheio de "WIP" e "corrigi o bug"? Rode /commit init: ele
prepara os changesets, adota Conventional Commits daqui para a frente e
guarda as convenções no CLAUDE.md, para que o agente de cada pessoa do
time escreva no mesmo estilo desde o primeiro dia — sem cerimônia de
commitlint, embora, se você tiver commitlint, a configuração dele vença.
/commit changelog 3.2.0 --plain --lang pt-BR --notes gera um documento
independente que dá para colar em um e-mail ou no Slack: agrupado por
novidades, melhorias e correções, com breaking changes destacadas junto do
que a pessoa precisa fazer, e zero afirmação inventada. Nomes de produto
ficam; IndexedDB sai.
/commit --split agrupa as mudanças pendentes nos menores commits
autocontidos possíveis — tipos diferentes, escopos sem relação, pedaços
reversíveis de forma independente — anuncia o plano e comita em ordem de
dependência, com um changeset por grupo. Uma função e seu teste ficam
juntos; uma correção de documentação de passagem não pega carona na sua
feature.
Perguntas frequentes
Não. Sem o .changeset/config.json, a skill é um escritor de commits ciente
das convenções. Se o seu repositório publica pacotes, ela vai mencionar o
/commit init uma vez — e nunca mais insistir.
Sem problema. Para mudanças que tocam um pacote publicado mas não devem
gerar release — testes, tooling, refactors internos — a skill adiciona um
changeset vazio (changeset add --empty), então o changeset status --since main
passa sem inventar nota de versão.
A detecção percebe o histórico em formato livre e pergunta se você quer adotar Conventional Commits daqui para a frente. Se você disser que não, o estilo que já existe é o que vai para o cache — a skill se adapta ao repositório, e não o contrário.
A skill reporta o erro exato e para. Ela nunca reexecuta um hook que falhou
às cegas, nunca contorna com --no-verify e nunca sobe correções
parcialmente — ciclos de stash e restore de hook podem destruir trabalho que
não está no stage.
Não. Nada de Co-Authored-By, nada de “Generated with…” — a menos que as
convenções do seu próprio repositório exijam um trailer.
Toda linha precisa vir de uma entrada de changelog, changeset ou commit real. Se uma entrada for críptica demais para traduzir com confiança, a skill lê o commit que ela referencia; se ainda assim não ficar claro, ela mantém o texto técnico e sinaliza, em vez de inventar uma história simpática.