lggarrison/agent-skills

Configuração de repositório

Um novo repositório precisa da mesma base toda vez: uma licença, uma forma de relatar problemas de segurança, um README, modelos que tornem PRs e issues úteis, e CI que execute as mesmas verificações que um contribuidor executa localmente. Esta skill é uma lista de verificação para essa base e uma forma de executá-la.

Regras do repositório vêm primeiro

Leia o que o repositório já tem antes de adicionar qualquer coisa: AGENTS.md / CLAUDE.md, CONTRIBUTING.md, arquivos .github/ existentes, o manifesto do pacote e seus scripts, e qualquer configuração de CI. Onde eles definirem uma convenção (branch padrão, licença, ferramentas, locais de arquivos), siga-a. Nunca sobrescreva um arquivo existente para corresponder a um modelo aqui. Estenda-o ou deixe-o e mencione a lacuna.

Fluxo de trabalho

1. Defina a tarefa

• Inicialização (Bootstrap): um repositório novo ou quase vazio. Execute toda a lista de verificação.
• Preencher lacunas: um repositório existente está faltando alguns itens. Adicione apenas o que está faltando.
• Auditoria: reporte o que está faltando ou fraco, e não altere nada.

2. Faça um inventário

Liste quais arquivos da lista de verificação existem e leia o manifesto (package.json, pyproject.toml, go.mod, Cargo.toml e assim por diante) para a linguagem, os scripts e se o projeto é publicado. Encontre a branch padrão com git remote show origin ou gh repo view --json defaultBranchRef. Não pergunte ao usuário nada que você possa aprender dessa forma.

3. Pergunte sobre as decisões críticas

Estas são decisões do usuário. Pergunte uma vez, em uma rodada curta, e recomende onde as evidências suportarem:

• Licença, e o nome do detentor dos direitos autorais.
• Contato de segurança: relatório de vulnerabilidade privada do GitHub, um endereço de e-mail, ou ambos.
• Contato do código de conduta, se for adicionar um.
• Branch base do PR, se não for a branch padrão.
• Publicado ou não: em um registro de pacotes, ou como um artefato de release.
• Matriz de CI: quais sistemas operacionais e versões de runtime suportar.

4. Escreva os arquivos

Trabalhe a lista de verificação de cima para baixo e pule seções que não se aplicam.

• Busque o texto canônico; não o memorize. Obtenha o texto da licença com gh api licenses/<spdx-id> --jq .body (por exemplo mit ou apache-2.0), depois preencha o ano e o detentor. Obtenha um código de conduta de sua fonte oficial, como o Contributor Covenant.
• Adapte os modelos. Comece de templates/. Substitua cada <placeholder> e altere os comandos para os que existem neste repositório. Um modelo que liste um script que o repositório não tem é pior do que nenhum modelo.
• Uma lista de verificações. A lista de verificação do modelo de PR, CONTRIBUTING.md, o hook de pre-commit e o CI devem todos nomear os mesmos comandos. Quando um mudar, mude os outros.
• Pergunte antes de alterar configurações. Proteção de branch, regras e relatório de vulnerabilidade privada são configurações do repositório, não arquivos. Proponha-as e aplique-as apenas quando o usuário concordar.

5. Verifique

• Todo comando nomeado em um modelo, hook ou job de CI é executado localmente e passa.
• Nenhum <placeholder> foi deixado em nenhum arquivo.
• Formulários de issue e workflows são YAML válido. Formulários de issue só aparecem na branch padrão, então verifique-os lá após o merge.
• Links funcionam, incluindo a URL da política de segurança.
• As próprias verificações de formato e lint do repositório passam nos novos arquivos.

6. Reporte

Diga o que você adicionou, o que você deixou como estava e por quê, as configurações de repositório que você propôs e quaisquer decisões críticas ainda em aberto.

Lista de verificação

R é obrigatório, rec é recomendado e opt é opcional.

Ferramentas

• R git e o runtime da linguagem e gerenciador de pacotes.
• rec Um gerenciador de versão de runtime (nvm, fnm, pyenv e assim por diante) correspondente ao arquivo de versão fixada.
• rec gh, autenticado com gh auth login, para mantenedores.

Legal e comunidade

• R LICENSE.
• R SECURITY.md: versões suportadas, como relatar privadamente e o que os relatores podem esperar após o relato.
• rec CONTRIBUTING.md: configuração, as verificações a executar, convenções de branch e commit e como PRs são revisados.
• rec CODE_OF_CONDUCT.md, com um contato de aplicação real.
• rec CHANGELOG.md no formato Keep a Changelog.

Documentação

• R README.md: o que é, como instalar, um exemplo de uso mínimo e links para CONTRIBUTING.md, SECURITY.md e a licença.
• opt AGENTS.md: o ponto de entrada neutro de fornecedor para agentes de codificação. Forneça os comandos a executar e as regras a seguir, e link para outros documentos em vez de repeti-los.
• opt RELEASING.md, para projetos publicados. Veja Publicação.

Higiene do editor e Git

• R .gitignore para a linguagem, a saída de build e arquivos de ambiente local.
• rec .gitattributes com * text=auto eol=lf, para que as terminações de linha não variem entre sistemas operacionais.
• rec .editorconfig para charset, nova linha final e indentação.

Modelos e automação do GitHub

Se o repositório não estiver no GitHub, use os equivalentes do host.

• rec .github/PULL_REQUEST_TEMPLATE.md. Veja Modelos.
• rec Formulários de issue em .github/ISSUE_TEMPLATE/: bug_report.yml, feature_request.yml e um config.yml que desative issues em branco e aponte relatos de segurança para o canal privado. Veja Modelos.
• rec .github/dependabot.yml, com uma entrada para cada ecossistema de pacotes que o repositório usa, mais github-actions.
• R .github/workflows/ci.yml, executando as mesmas verificações que o modelo de PR em todo PR e todo push para a branch padrão.
• opt .github/release.yml, para agrupar notas de release geradas por label.
• opt .github/workflows/release.yml, apenas para projetos publicados.
• rec Proteção de branch ou um conjunto de regras na branch padrão que exija CI. Isso é uma configuração, então peça primeiro.

Node.js e TypeScript

Pule esta seção para outras linguagens e aplique as mesmas ideias com as ferramentas desse ecossistema: uma versão de runtime fixada, um formatador, um linter, um executor de testes, um único comando "verificar tudo" e uma matriz de CI.

Runtime e metadados

• rec .nvmrc e engines.node em package.json, concordando entre si.
• R package.json repository, homepage, bugs, license e author.
• rec "type": "module" para ESM nativo.

TypeScript (apenas projetos TypeScript)

• R typescript e um tsconfig.json, com um npm run build que compile.
• Não converta um projeto JavaScript para TypeScript. Para um projeto novo, usar TypeScript é decisão do usuário.

Formatação e lint

• rec Prettier (.prettierrc.json, .prettierignore) e uma configuração plana do ESLint.
• rec Scripts lint, lint:fix, format e format:check.

Testes unitários

• R Um npm test que execute os testes unitários.
• rec Vitest, com testes ao lado do código (src/**/*.test.ts) e fixtures compartilhadas em test/.

Testes de ponta a ponta (opt, para projetos com UI ou fluxos de navegador)

• rec @playwright/test, um playwright.config.ts e testes em e2e/.
• rec Um script npm run test:e2e.
• rec playwright-report/, test-results/ e blob-report/ em .gitignore.
• rec Um job de CI que instale navegadores com npx playwright install --with-deps e faça upload do relatório quando um teste falhar.
• opt Para uma CLI sem navegador, execute testes de ponta a ponta através de uma configuração separada do Vitest.

Hooks Git (apenas desenvolvimento local)

• rec Husky com um hook pre-commit que execute lint-staged.
• rec Um script prepare que pule a instalação do Husky quando CI estiver definido ou NODE_ENV=production, para que instalações em CI e produção não falhem.
• opt Um hook pre-push que execute os testes unitários.

Portão de qualidade

• rec Um script, como check, que execute lint, format:check, os testes unitários, o build e os testes de ponta a ponta nessa ordem. CI e contribuidores o executam.
• rec Uma matriz de CI entre os sistemas operacionais suportados e versões do Node.js.

Publicação

Para projetos publicados em um registro de pacotes. Estes são opt para todo o resto.

• rec Uma lista de permissão "files" em package.json (ou .npmignore), verificada com npm pack --dry-run.
• rec Um script prepublishOnly que execute o build.
• rec Publicação a partir de CI com npm Trusted Publishing (OIDC, id-token: write), para que nenhum token de longa duração seja armazenado como segredo.
• rec RELEASING.md cobrindo como as versões são escolhidas (semver), como um release é marcado, as verificações que bloqueiam uma tag ruim e como reverter.

Modelos

Arquivo	Copiar para
templates/PULL_REQUEST_TEMPLATE.md	.github/PULL_REQUEST_TEMPLATE.md
templates/ISSUE_TEMPLATE/bug_report.yml	.github/ISSUE_TEMPLATE/bug_report.yml
templates/ISSUE_TEMPLATE/feature_request.yml	.github/ISSUE_TEMPLATE/feature_request.yml
templates/ISSUE_TEMPLATE/config.yml	.github/ISSUE_TEMPLATE/config.yml

Os placeholders são escritos <assim>. Por exemplo, substitua <runtime-version-command> por node --version, python --version ou go version. Os outros comandos nos modelos são exemplos de um projeto Node.js. Substitua-os pelos do próprio repositório.