setup-pre-commit

Visão geral da skill setup-pre-commit

O que a setup-pre-commit faz

A skill setup-pre-commit ajuda um agente a adicionar uma barreira prática no momento do commit em um repositório JavaScript ou TypeScript usando husky, lint-staged, Prettier e, opcionalmente, scripts de typecheck e test. Em termos simples, ela conecta a formatação aos arquivos staged e pode bloquear commits problemáticos antes que entrem no repositório.

Para quem essa skill setup-pre-commit é mais indicada

Esta skill funciona melhor para equipes ou desenvolvedores solo que querem configurar pre-commit sem complicação em um repositório já existente e não querem montar manualmente a primeira configuração do Husky. Ela se encaixa especialmente bem quando você já tem um projeto baseado em Node e quer formatação no commit junto com checagens leves de qualidade.

O trabalho real que ela resolve

Na prática, a maioria das pessoas não quer apenas “instalar Husky”. Quer um repositório em que quem contribui consiga fazer commits com confiança, com um hook previsível que:

• formata os arquivos staged,
• executa scripts existentes de typecheck e test quando estiverem presentes,
• evita inventar tooling extra,
• respeita o package manager do repositório.

Esse é o valor prático da setup-pre-commit.

O que diferencia a setup-pre-commit de um prompt genérico

Um prompt genérico pode sugerir vários padrões possíveis de Git hooks. A setup-pre-commit skill é mais específica e mais útil para um caso muito comum: configurar exatamente o caminho Husky + lint-staged + Prettier, detectar o package manager, criar os arquivos corretos e evitar adicionar comandos de typecheck ou test que o repositório na verdade não suporta.

O que ela configura por padrão

Com base no código-fonte da skill, o resultado esperado inclui:

• inicialização do husky
• um arquivo .husky/pre-commit
• um .lintstagedrc
• um .prettierrc somente se ainda não existir configuração de Prettier
• comandos no hook para lint-staged, além de typecheck e test quando esses scripts já existirem

Repositórios com melhor encaixe — e onde ela não é a melhor opção

Melhor encaixe:

• repositórios Node.js
• apps frontend ou full-stack em TypeScript
• repositórios que já usam package.json
• projetos com scripts existentes de test e typecheck

Menos ideal:

• monorepos polyglot com orquestração própria de hooks
• repositórios que já usam outro gerenciador de hooks
• equipes que querem pipelines de commit muito rápidas, altamente seletivas ou específicas por linguagem além do padrão
• projetos em que rodar testes a cada commit é lento demais

Como usar a skill setup-pre-commit

Contexto de instalação da skill setup-pre-commit

Se você estiver usando o sistema de Skills, adicione a skill a partir do repositório de origem:

npx skills add mattpocock/skills --skill setup-pre-commit

Depois, invoque a skill quando quiser que o agente modifique o repositório atual, e não quando quiser apenas uma explicação abstrata sobre Git hooks.

Quais entradas a skill precisa do seu repositório

A qualidade do uso de setup-pre-commit depende do contexto do repositório. Antes de chamá-la, garanta que o agente consiga inspecionar:

• package.json
• algum lockfile, como package-lock.json, pnpm-lock.yaml, yarn.lock ou bun.lockb
• arquivos de configuração Prettier já existentes
• configuração atual de .husky/ ou de Git hooks
• se existem scripts de typecheck e test

Sem esse contexto, o agente pode gerar comandos que não batem com o seu package manager ou com os scripts reais do projeto.

O arquivo do repositório que você deve ler primeiro

Comece por SKILL.md. Esta skill é simples e autocontida, e toda a lógica importante está ali:

• detectar o package manager
• instalar husky, lint-staged e prettier
• executar npx husky init
• escrever .husky/pre-commit
• escrever .lintstagedrc
• adicionar .prettierrc apenas se estiver faltando
• verificar o resultado

Para esta skill específica, não há arquivos auxiliares extras com comportamento escondido.

Como escrever um bom prompt para setup-pre-commit

Um prompt fraco:

Set up pre-commit hooks.

Um prompt melhor:

Use the setup-pre-commit skill in this repo. Detect the package manager from lockfiles, inspect package.json, add Husky with lint-staged and Prettier, and only include typecheck or test in .husky/pre-commit if those scripts already exist. Do not overwrite any existing Prettier config. Show me the files you changed and the exact commands you ran.

Por que isso é melhor:

• fixa a regra do package manager,
• evita scripts inventados,
• preserva convenções de formatação já existentes,
• pede um diff fácil de revisar.

Como transformar um objetivo vago em uma solicitação completa

Se o seu objetivo real é “deixar nosso fluxo de Git mais seguro”, traduza isso em restrições específicas do repositório:

• package manager em uso
• se os testes são rápidos o bastante para rodar no pre-commit
• se você quer só formatação ou formatação mais validação
• se o repositório já tem Prettier ou Husky
• se você quer um hook mínimo para manter a velocidade de contribuição

Exemplo:

Use setup-pre-commit for Git Workflows in this React TypeScript repo. We use pnpm, already have a test script, and have typecheck in package.json. Keep the hook simple and fast. Reuse existing Prettier config if present. If tests look expensive, explain whether they should stay in pre-commit or move to pre-push.

Esse prompt dá ao agente informações úteis para decidir bem, e não apenas um rótulo de tarefa.

Arquivos e comandos esperados

Em um repositório npm comum, a skill normalmente leva a:

• instalar dependências de desenvolvimento: husky, lint-staged, prettier
• executar npx husky init
• criar .husky/pre-commit
• criar .lintstagedrc
• possivelmente criar .prettierrc

O conteúdo do hook deve ser adaptado ao package manager. A skill de origem diz explicitamente para substituir npm pelo package manager detectado quando necessário.

Comportamento prático com package managers

A regra de detecção de package manager na skill é direta:

• package-lock.json → npm
• pnpm-lock.yaml → pnpm
• yarn.lock → yarn
• bun.lockb → bun
• se não estiver claro → npm

Isso importa porque muitas tentativas ruins de setup-pre-commit install falham não por causa do Husky em si, mas por misturar comandos de package managers diferentes na documentação ou nos arquivos gerados.

O que a skill deliberadamente deixa de fora

Um limite útil: a skill não deve inventar scripts que o seu repositório ainda não suporta. Se o package.json não tiver typecheck ou test, essas linhas devem ficar de fora de .husky/pre-commit, e isso deve ser informado explicitamente ao usuário.

Isso torna a skill mais segura do que prompts amplos que presumem que todo projeto tem checagem de TypeScript e test runner.

Fluxo recomendado depois de rodar a skill

Depois que o agente aplicar a skill:

1. inspecione package.json
2. inspecione .husky/pre-commit
3. inspecione .lintstagedrc
4. confirme que nenhuma configuração existente do Prettier foi sobrescrita
5. faça um commit de teste com uma pequena alteração de formatação em arquivo staged
6. decida se test deve mesmo ficar no pre-commit ou se faz mais sentido em outro lugar

Este último passo é importante: correção não é a mesma coisa que ergonomia. Um hook que roda testes longos pode estar tecnicamente certo e ainda assim prejudicar a adoção.

Um bom checklist padrão de revisão

Antes de fazer merge das mudanças, verifique:

• se o package manager corresponde ao repositório
• se .husky/pre-commit usa comandos que quem contribui consegue executar localmente
• se o hook não chama scripts inexistentes
• se a formatação dos arquivos staged está limitada via lint-staged
• se a configuração do Prettier só foi adicionada quando estava ausente
• se a latência do commit é aceitável para o uso diário

FAQ da skill setup-pre-commit

A setup-pre-commit é boa para iniciantes?

Sim, se o repositório for um projeto Node padrão. A skill é opinativa, mas não complicada, e evita boa parte da fricção comum de primeira vez com inicialização do Husky e a integração básica de lint-staged.

O que a setup-pre-commit não cobre?

A skill não tenta desenhar uma estratégia completa de qualidade de código. Ela não escolhe regras de ESLint, não otimiza execução de hooks em monorepo e não cria comandos sofisticados de lint-staged por tipo de arquivo. O escopo dela é a configuração inicial do hook de commit.

Quando eu não devo usar setup-pre-commit?

Evite usar se:

• seu repositório já tem um sistema maduro de Git hooks,
• você precisa de hooks em várias etapas e específicos por linguagem fora do ecossistema Node,
• você quer padrões de arquivos staged muito personalizados,
• rodar testes a cada commit claramente vai deixar o fluxo dos desenvolvedores lento.

Nesses casos, um prompt mais sob medida ou um padrão interno já existente provavelmente será melhor.

Isso é melhor do que pedir para uma IA “configurar Husky”?

Na maioria das vezes, sim, para este caso de uso específico. O valor da setup-pre-commit não está em ser novidade; está em executar com restrições claras. Ela codifica um caminho padrão sensato e reduz a adivinhação em torno de detecção de lockfile, scripts ausentes e do momento certo de criar configuração do Prettier.

A setup-pre-commit funciona para monorepos?

Às vezes, mas com cautela. Ela ainda pode ajudar se o repositório tiver um package.json principal bem definido e uma única estratégia de hooks. Fica menos confiável quando os pacotes têm scripts independentes, políticas separadas de formatação ou comandos de teste específicos por workspace.

Ela força o uso de Prettier mesmo se o repositório já tiver configuração de formatação?

Não. As instruções de origem dizem para criar .prettierrc apenas se ainda não existir configuração de Prettier. Esse é um comportamento importante para facilitar a adoção sem atropelar padrões já definidos.

Posso usar setup-pre-commit para Git Workflows além de formatação?

Sim, mas de forma limitada. A skill permite adicionar typecheck e test ao fluxo de commit quando esses scripts já existem. Ela não é uma ferramenta completa para desenhar proteção de branch ou estratégia de CI.

Como melhorar a skill setup-pre-commit

Forneça fatos mais fortes sobre o repositório logo de cara

A maneira mais rápida de melhorar o uso de setup-pre-commit é incluir sinais concretos do repositório no seu prompt:

• package manager
• se typecheck existe
• se test existe
• se os testes são rápidos
• se já existe configuração de Prettier
• se .husky/ já existe

A skill fica muito mais confiável quando pode trabalhar a partir de fatos verificados, e não de suposições.

Peça uma implementação orientada a diff

Um bom prompt de melhoria é:

Use the setup-pre-commit skill, but minimize changes. Reuse existing config where possible, avoid replacing current hook behavior, and show the exact file diff before writing anything risky.

Isso ajuda especialmente em repositórios que talvez já tenham tooling configurado parcialmente.

Evite o modo de falha mais comum

O modo de falha mais comum é adicionar comandos que o repositório não consegue executar. Para melhorar o resultado, diga explicitamente ao agente:

Only add typecheck and test to the hook if those scripts already exist in package.json. Otherwise omit them and explain why.

Essa instrução está alinhada com a skill de origem e evita commits quebrados.

Ajuste para velocidade do desenvolvedor, não só para correção

Muitas equipes percebem que npm run test no pre-commit pesa demais. Se velocidade importa, peça que o agente avalie o custo do hook:

Use setup-pre-commit, but if tests appear slow or broad, explain whether they should move to pre-push or CI instead of pre-commit.

Isso transforma a skill de “instalar tooling” em “ajustar ao fluxo real de trabalho”.

Peça comandos seguros para o package manager

Se sua equipe usa pnpm, yarn ou bun, diga isso explicitamente mesmo que o lockfile já esteja presente. Isso reduz ambiguidade e melhora a consistência dos comandos nos arquivos de hook gerados e nas instruções seguintes.

Peça ao agente para preservar padrões existentes

Se o seu repositório já tiver arquivos de formatação ou hooks, acrescente:

Do not overwrite existing Prettier or Husky config without comparing and explaining the merge strategy.

Isso é mais importante do que parece. Ferramentas de pre-commit muitas vezes falham socialmente porque substituem convenções locais de forma agressiva demais.

Melhore a qualidade da saída com uma etapa de validação

Um prompt final melhor inclui:

After applying setup-pre-commit, verify that the hook files exist, dependencies are in devDependencies, and the hook references only valid scripts. Then tell me how to test it with one staged file.

Isso força o agente a ir além da criação de arquivos e chegar à usabilidade de fato.

Faça uma segunda passada depois do primeiro resultado

Se a primeira saída estiver tecnicamente correta, mas pouco prática, refine com um destes follow-ups:

• “Make the hook faster.”
• “Adapt this for pnpm.”
• “Remove test from pre-commit but keep typecheck.”
• “Keep existing Prettier settings and only add missing pieces.”
• “Adjust for a monorepo root package.”

Em geral, isso funciona melhor do que recomeçar do zero com um prompt novo e amplo demais.

O que mais importa para os usuários

Para a maioria de quem vai adotar, o melhor setup-pre-commit guide não é “quantas ferramentas ele instala”, e sim se ele:

• funciona imediatamente no repositório atual,
• evita quebrar commits,
• respeita a configuração existente,
• continua rápido o suficiente para que os desenvolvedores mantenham o hook ativado.

Use a skill com esses resultados em mente, e a chance de ela gerar valor duradouro será bem maior.