Skill: agents-generator

[!WARNING] [Uso Autorizado Apenas] Esta skill escreve ou atualiza AGENTS.md, .agents/rules/, arquivos opcionais de instruções da plataforma e backups com data e hora no projeto de destino. Leia as entradas detectadas e as saídas propostas primeiro, obtenha aprovação antes de alterar arquivos de destino e use-a apenas dentro do escopo pretendido do projeto pelo usuário.

Quando Usar

Use esta skill quando o usuário quiser:

• criar um AGENTS.md completo e específico do projeto em vez de regras genéricas de agente;
• gerar regras complementares para frameworks, testes, bancos de dados, estilização ou pacotes monorepo detectados;
• criar um AGENTS.md mínimo, pré-visualizar alterações sem escrever, ou atualizar instruções existentes após mudanças na stack.

Não a use para inventar convenções sem inspecionar o projeto de destino, para sobrescrever instruções fora do escopo do usuário, ou para tratar orientações geradas como substitutas de revisão humana.

Gera um AGENTS.md + .agents/rules/*.md personalizado para o projeto de destino — não um template com placeholders, mas um documento vivo que corresponde à toolchain real do projeto.

O Que Você Obtém

De um projeto que usa Bun + Next.js 16 + Tailwind + Vitest + Server Actions, a skill produz:

AGENTS.md
├── Setup commands: bun install, bun dev, bun run test:run, bun doctor
├── Verification Cycle: bunx tsc --noEmit → bun run lint → bun run test:run → bun doctor
├── Conventions: "Bun always. Plain TypeScript types + guards."
└── Architecture → .agents/rules/architecture.md

.agents/rules/
├── architecture.md       ← ASCII diagram with real directories, exact versions
├── frontend-patterns.md  ← Component rules, state locations, trust boundaries
├── server-actions.md     ← downloadVideo() flow, DownloadResult type, rate limiter
├── testing.md            ← "74 tests in 5 files", vitest commands, mock patterns
├── git-workflow.md       ← Conventional commits, pre-commit checks
└── sdd-workflow.md       ← Preflight defaults, post-apply verification

Regras NÃO geradas: backend.md (sem NestJS), database.md (sem ORM), i18n.md (espanhol hardcoded), forms.md (entradas manuais), styling.md (Tailwind em regras de frontend).

Contrato de Ativação

Gerar AGENTS.md + .agents/rules/*.md para o projeto de destino. Nunca adivinhe — leia os arquivos reais do projeto primeiro.

Seleção de Modo

Modo Dry-run

Se o usuário pedir para "preview", "show what would change", "dry-run": execute toda a detecção, mas NÃO escreva arquivos. Mostre o resumo da detecção, os arquivos que seriam criados, as regras puladas e um exemplo de saída.

Regras Fixas

• Leia antes de escrever, mas nunca leia segredos. Leia package.json, arquivos de configuração não secretos e a estrutura de diretórios antes de gerar qualquer coisa. Nunca abra .env, .env.local, armazenamentos de credenciais ou arquivos similares que contenham segredos. Derive nomes de variáveis de ambiente apenas de placeholders .env.example e referências de origem como process.env.NAME, sem ler ou reportar valores.
• Detecte o gerenciador de pacotes PRIMEIRO. Verifique os lockfiles: bun.lock→bun, pnpm-lock.yaml→pnpm, package-lock.json→npm, yarn.lock→yarn. NUNCA use npm como padrão. Todo comando usa o PM detectado.
• Gere apenas o que se aplica. Sem regras de backend para frontend apenas. Sem regras de banco de dados sem ORM.
• Não execute scripts do projeto por padrão. Scripts do gerenciador de pacotes são pontos de entrada shell controlados pelo repositório. Detecte e documente comandos candidatos de formatação/lint, mas não os execute a menos que o usuário solicite separadamente a execução após a revisão do corpo exato do script e das ferramentas invocadas.
• Valide comandos. Todo comando na saída deve existir como uma chave de script em package.json.
• Sem placeholders. Verifique a saída em busca de {{, TODO, add here, .... Rejeite se algum permanecer.
• Faça backup primeiro. Se os arquivos existirem, copie para .agents/backups/ com data e hora.

Passos de Execução

Comum

1. git rev-parse --show-toplevel → raiz do projeto.
2. Detecte o gerenciador de pacotes PRIMEIRO: verifique os lockfiles. bun.lock→bun, pnpm-lock.yaml→pnpm, package-lock.json→npm, yarn.lock→yarn. Nunca use npm como padrão.

…