Conventional Commits Skill para OpenClaw

OpenClaw Conventional Commits Skill — Visão Geral

O skill Conventional Commits traz mensagens de commit estruturadas e em conformidade com a especificação para o seu fluxo de trabalho OpenClaw. Em vez de escrever mensagens de commit do zero ou tentar lembrar a especificação Conventional Commits, simplesmente peça ao seu agente OpenClaw para gerar ou validar mensagens baseadas nas suas mudanças preparadas.

Conventional Commits é uma convenção leve sobre mensagens de commit que fornece um histórico claro e legível por máquinas. Ela alimenta changelogs automáticos, versionamento semântico e ferramentas de publicação em milhares de projetos open source e empresariais. Com este skill OpenClaw, você obtém todos esses benefícios sem a carga cognitiva.

Fluxo de trabalho típico:

1. Prepare suas mudanças com git add.
2. Peça ao OpenClaw para escrever uma mensagem de commit.
3. O agente analisa o diff, determina o tipo correto (feat, fix, docs, etc.) e propõe uma mensagem corretamente formatada — pronta para commitar.

Pré-requisitos para o Conventional Commits Skill

Antes de instalar o skill Conventional Commits, certifique-se de ter:

• OpenClaw instalado e em execução (v1.0+)
• Git instalado (v2.20+) — download oficial
• Um repositório de projeto inicializado com git init
• clawhub CLI instalado para gerenciamento de skills

Verifique sua configuração:

# Verificar versão do OpenClaw
openclaw --version

# Verificar versão do Git
git --version

# Confirmar que está dentro de um repositório Git
git status

Como Instalar o Conventional Commits Skill

Instale o skill Conventional Commits com um único comando:

npx clawhub@latest install conventional-commits

Para verificar a instalação:

clawhub list

Você deve ver conventional-commits na lista de skills instalados. O skill funciona imediatamente — sem necessidade de chaves de API ou serviços externos.

Configuração do Conventional Commits Skill

Este skill requer configuração mínima. Ele lê suas mudanças Git preparadas e formata mensagens de acordo com a especificação Conventional Commits. No entanto, você pode personalizar seu comportamento para corresponder às convenções da sua equipe.

Tipos de Commit

O skill reconhece os tipos padrão Conventional Commits:

| Tipo | Quando Usar | |------|------------| | feat | Uma nova funcionalidade para o usuário | | fix | Uma correção de bug | | docs | Mudanças apenas em documentação | | style | Formatação, ponto e vírgula faltando (sem mudança lógica) | | refactor | Reestruturação de código sem funcionalidade ou correção | | perf | Melhorias de desempenho | | test | Adicionar ou atualizar testes | | chore | Processo de build, atualizações de dependências, ferramentas | | ci | Mudanças na configuração CI/CD |

Commits com Escopo

O skill suporta mensagens de commit com escopo para monorepos e projetos maiores:

feat(auth): add OAuth2 login flow
fix(api): handle null response from payment endpoint
docs(readme): update installation instructions

Você pode definir escopos permitidos na configuração do seu projeto para manter consistência entre colaboradores.

Exemplos de Uso do Conventional Commits Skill

1. Gerar uma Mensagem de Commit a partir de Mudanças Preparadas

Você: "Escreva uma mensagem de commit para minhas mudanças preparadas."

O agente inspeciona git diff --staged, identifica que você adicionou um novo endpoint de API e retorna:

feat(api): add user profile endpoint

Implement GET /api/users/:id/profile with authentication
middleware and response caching.

Você pode aceitar, editar ou pedir ao agente para regenerar com um tom ou escopo diferente.

2. Validar uma Mensagem de Commit Existente

Você: "Verifique se esta mensagem de commit segue a convenção: 'Updated the login page'"

O agente analisa a mensagem e responde com feedback específico:

• Prefixo de tipo ausente — deve começar com feat:, fix: ou outro tipo válido
• Usa tempo passado ("Updated") — a convenção recomenda modo imperativo ("update")
• Correção sugerida: fix(auth): update login page layout

3. Validar Commits Recentes em Lote

Você: "Valide as últimas 10 mensagens de commit nesta branch."

O agente percorre seu histórico recente e sinaliza commits que não seguem a convenção, fornecendo alternativas corrigidas para cada um. Isso é útil antes de fazer merge de uma branch de feature na main.

4. Gerar um Commit de Mudança Quebrada

Você: "Commite isso como uma mudança quebrada — removemos a API v1."

O agente formata um commit de mudança quebrada apropriado:

feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: All /api/v1/* routes have been removed.
Consumers must migrate to /api/v2/* before upgrading.

Tanto o sufixo ! quanto o footer BREAKING CHANGE estão incluídos, garantindo compatibilidade com ferramentas como semantic-release e standard-version.

Segurança e Melhores Práticas

O skill Conventional Commits é um dos skills mais seguros do ecossistema OpenClaw — opera puramente em formatação e validação de texto, sem chamadas de API externas ou operações de escrita além do seu repositório Git local.

Siga estas diretrizes para a melhor experiência:

• Revise antes de commitar. Sempre leia a mensagem gerada antes de aceitá-la. O agente infere a intenção dos diffs, mas você conhece melhor o contexto.
• Use escopos consistentes. Defina uma lista de escopos permitidos para seu projeto e compartilhe com sua equipe para prevenir desvio de escopos.
• Combine com validação CI. Ferramentas como commitlint podem impor Conventional Commits no seu pipeline CI, capturando commits manuais que pulam o skill.
• Habilite hooks pre-commit. Use husky ou lefthook para executar validação de mensagens de commit automaticamente.

Solução de Erros Comuns

"Not a git repository"

O skill requer que você esteja dentro de um diretório inicializado com Git.

# Inicializar um novo repositório
git init

# Ou navegar para seu projeto existente
cd /path/to/your/project

"No staged changes found"

O skill precisa de mudanças preparadas para gerar uma mensagem de commit significativa.

# Preparar arquivos específicos
git add src/feature.ts

# Ou preparar todas as mudanças
git add -A

"Unable to determine commit type"

Pode ocorrer quando o diff é muito grande ou toca muitos arquivos não relacionados. Tente preparar conjuntos de mudanças menores e focados, ou especifique o tipo manualmente:

Você: "Escreva uma mensagem de commit do tipo refactor para essas mudanças."