Communitygithub.com

Conventional Commits e Releases

Use ao fazer commits, escrever mensagens de commit, abrir um PR que será mesclado por squash, ou configurar versionamento/changelogs automatizados. Palavras-chave — conventional commits, release-please, semver, feat/fix/chore, breaking change, changelog.

O que é Conventional Commits e Releases?

Esta skill padroniza a escrita de mensagens de commit e a configuração de CI para que seu projeto gere versões e changelogs automaticamente com base no formato Conventional Commits. Ela define os tipos `feat` (nova funcionalidade), `fix` (correção), `docs`, `chore`, `refactor`, `test` e `ci/build`, e especifica como cada tipo impacta o versionamento semântico (minor, patch, major). A skill também cobre boas práticas como usar o modo imperativo na descrição, adicionar `!` para breaking changes e (quando aplicável) incluir escopo opcional. Para repositórios que fazem squash merge, a skill enfatiza que o título do PR é o commit que publica — portanto, ele precisa ser um commit convencional válido. Além disso, ela proíbe qualquer atribuição de IA (como `Co-authored-by` para Claude ou Anhthropic) tanto no corpo do PR quanto nos commits, com validação bloqueante em CI. A principal ferramenta de enforcement é o `amannn/action-semantic-pull-request`, que valida o título do PR de forma bloqueante; já os corpos dos commits no branch não são lintados porque o squash merge os descarta. A skill documenta explicitamente as racionalizações comuns (ex.: 'chore serve para isso') e os red flags (ex.: commit sem prefixo de tipo) que devem ser evitados. Em suma, ela unifica a disciplina de commits pequenos com a correção mecânica de versionamento, garantindo que o changelog e a versão final estejam sempre corretos sem intervenção manual.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/conventional-commits-and-releases
Ver original→Navegar por todas as habilidades

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentação

O que Conventional Commits e Releases faz?

Visão Geral

As mensagens de commit são uma interface legível por máquina, não apenas prosa. O versionamento automatizado e a geração de changelogs as analisam; uma mensagem malformada produz uma versão pública errada ou um release quebrado. Disciplina no pequeno (uma mensagem bem-formada) gera correção no grande (changelog preciso, bump de versão correto) de graça.

O Formato

<tipo>(<escopo>): <descrição>

TipoEfeito / uso
featNova funcionalidade — bump minor
fixCorreção de bug — bump patch
docsApenas documentação
choreManutenção, dependências, configuração
refactorMudança de código sem alterar comportamento
testApenas testes
ci / buildMudanças em pipeline / sistema de build
  • Modo imperativo: "adiciona X", não "adicionei X" ou "adiciona-se X".
  • Breaking changes: feat!: ou um rodapé BREAKING CHANGE: — dispara um bump major.
  • Escopo opcional, mas encorajado: feat(auth):, fix(db):.

Detalhes Importantes

  • A ligação tipo↔versão significa que um feat digitado errado como fix publica uma versão errada. Escolha o tipo deliberadamente: "adiciona" = nova funcionalidade, "atualiza" = melhoria em algo existente, "corrige" = bug.
  • Squash-merge: o título do PR se torna o commit que é publicado. Ele deve ser um commit convencional válido, senão o release estará errado.
  • Voz humana. Nenhuma atribuição de IA/assistente, nenhum trailer Co-authored-by, nenhum rodapé "gerado por". Os commits parecem que foram escritos por um humano.

Racionalizações Comuns

DesculpaRealidade
"A mensagem realmente não importa"Ela direciona o changelog e o número da versão. Ela importa mecanicamente.
"chore serve para essa funcionalidade"chore não vai alterar a versão; os usuários não receberão sua funcionalidade em um release. Use o tipo correto.
"Depois eu corrijo o título do PR"No squash-merge o título é final no momento da mesclagem. Corrija antes.
"Um trailer Co-authored-by não faz mal"A regra do projeto proíbe atribuição de IA. Sem exceções.

Sinais Vermelhos — PARE

  • Uma mensagem de commit sem prefixo de tipo
  • Usar chore/docs para algo que adiciona ou corrige comportamento visível ao usuário
  • Um título de PR para squash que não é um commit convencional válido
  • Qualquer atribuição de IA ou linha Co-authored-by

Enforcement:

  • Título do PR — validado na CI, bloqueante (amannn/action-semantic-pull-request). No squash-merge o título é o commit que publica, então esta é a validação que importa.
  • Atribuição de IA — um job bloqueante No AI Attribution rejeita trailers Co-authored-by mencionando Claude/Anthropic e rodapés Generated with [Claude…], tanto nos commits do branch como no corpo do PR (o corpo se torna o corpo do commit squash). Trailers Co-authored-by humanos não são afetados.
  • Corpos dos commits do branch — deliberadamente não lintados. O squash-merge os descarta, então eles nunca chegam ao changelog. Se você migrar para merge commits, adicione commitlint.

Gap conhecido: se um commit tiver como autor uma conta de agente, o GitHub compõe um trailer Co-authored-by no momento do squash — após a verificação do PR ter executado. A validação acima não consegue vê-lo. Não commite como uma identidade de agente.

Justificativa completa: Artigo III da constituição, incluído em engineering-constitution/references/engineering-constitution.md.

Individual skills in this repo

This repo contains 18 individual skills — each has its own dedicated page.

lguidolin/change-hygiene-and-code-craft

Use when writing or refactoring code, structuring a commit or PR, or deciding whether to abstract duplication. Symptoms — mixing reorg with logic changes, a PR doing several things at once, a file growing large, the second copy of similar code, or unsure whether to DRY something up.

lguidolin/cloud-delivery-aks

Use when deploying to Kubernetes or Azure Kubernetes Service (AKS), configuring cloud secrets, setting up progressive rollout/canary, per-PR ephemeral environments, or k8s health probes. Keywords — Kubernetes, AKS, Key Vault, Argo Rollouts, Flagger, canary, blue-green, liveness, readiness, PodDisruptionBudget, HPA, rollback, GHCR.

lguidolin/commit-history-rewrite

Use when an existing repository has messy commit history that needs to conform to conventional commits before adopting release-please, or when intermediate WIP/fixup/merge commits need to be cleaned up.

lguidolin/defense-in-depth-security

Use when handling untrusted input, secrets, authentication/authorization, or dependencies — or threat-modeling a new surface. Keywords — STRIDE, threat model, least privilege, secrets management, supply chain, dependency scanning, input validation, audit log, defense in depth.

lguidolin/designing-before-building

Use when starting a feature, fixing a non-trivial bug, or about to write implementation code — before any code exists. Symptoms you need this: "this is simple, I'll just code it", reaching for the editor before a design is approved, or an idea that hasn't been turned into a spec and plan.

lguidolin/engineering-constitution

Use when starting work in a project that follows the engineering constitution, orienting to its rules, or deciding which engineering practice applies to a task — spec writing, commits, testing, security, deploys, database, or UI work.

lguidolin/graphql-contract-testing

Use when writing a GraphQL query/mutation that the UI and a test will share, or building route/schema contract or smoke tests. Symptoms — copying a query into a test, a test asserting on query text, schema change that didn't break the UI build, or RLS/permission drift. Keywords — graphql-codegen, typed document, contract test, route smoke test.

lguidolin/init-repo-CI

Use when setting up a new repository with conventional commits, release-please, and CI automation, or when retrofitting an existing repository that lacks automated versioning and PR validation workflows.

lguidolin/interface-craft-and-accessibility

Use when building or styling UI — components, layouts, forms, design tokens — or making accessibility decisions. Keywords — a11y, WCAG, keyboard navigation, focus state, contrast, design system, minimalist UI, component reuse, ARIA, semantic HTML.

lguidolin/merge-gates-and-automation

Use when setting up or changing CI, pre-push hooks, or a task runner, or deciding what must pass before merge. Symptoms — tempted to put authoritative checks only in a local hook, skip CI, bypass with --no-verify, or unsure what gates a merge vs. runs locally.

lguidolin/observability-and-slos

Use when adding logging, metrics, tracing, health checks, SLOs, or alerting — or when building a service surface that needs to be operable and debuggable. Keywords — structured logs, OpenTelemetry, correlation id, RED metrics, liveness, readiness, SLI, SLO, error budget, alerting.

lguidolin/performance-and-scale

Use when working on hot paths, list endpoints, pagination, data-access in loops, or public interfaces/schemas. Symptoms — unbounded queries, N+1 access, no latency budget, optimizing without measuring, or changing an interface many consumers depend on. Keywords — pagination, N+1, Hyrum's Law, performance budget, bundle size.

lguidolin/postgres-postgraphile-rls-and-sql

Use when writing PostgreSQL, PostGraphile config, Row-Level Security policies, SQL schema files, or working on the Browser→App→PostGraphile→Postgres data path. Keywords — RLS, SECURITY DEFINER, search_path, pgSettings, grants, roles, GraphQL depth limit, query cost, statement_timeout, SQL file organization.

lguidolin/recording-decisions

Use when a design or architecture decision has been made and needs to be captured — writing a decision record or ADR, updating a decision index, noting a deferred idea, or superseding a past decision. Keywords — ADR, decision record, rationale, rejected alternatives, dependency index.

lguidolin/resilience-and-deploy-safety

Use when planning a deploy, designing a rollback, or responding to an incident or writing a postmortem. Keywords — deploy safety, rollback, immutable artifact, progressive delivery, canary, blast radius, incident response, blameless postmortem, error budget.

lguidolin/ship-it

Use when the user wants to ship work — push, PR, archive decision records, merge, and clean up. Handles the full lifecycle from committing final changes through post-merge cleanup including converting specs/plans to compact decision records.

lguidolin/tests-as-a-control

Use when writing or modifying tests, when a test breaks during a refactor, or when testing permission/role rules. Symptoms — tempted to edit a test to make it pass, testing only the happy path, a deny-test that started passing, flaky tests, or unsure what to assert.

lguidolin/zero-downtime-migrations

Use when changing a database schema where data must survive the change — adding/removing/renaming columns, constraints, indexes, or backfilling. Symptoms — a destructive migration bundled with a code deploy, a NOT NULL column with a backfill, a table-locking UPDATE, or a rename. Keywords — expand/contract, parallel change, backfill, NOT VALID, CREATE INDEX CONCURRENTLY, graphile-migrate.

Habilidades Relacionadas

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community