Recebi uma pergunta sobre quais skills uso com o Codex para desenvolver código, criar automações e trabalhar com agentes em análises mais complexas. Fui fazer o inventário. Uma parte estava nas skills globais. Outra estava dentro dos projetos, nos hooks do Git e no código do Ralph Starter.

O resultado é o agent-skills: uma coleção aberta com 11 workflows para Codex e Claude Code, com instruções, exemplos e origem documentada.

Uma skill é uma pasta com um arquivo SKILL.md e, quando necessário, referências ou scripts. O nome e a descrição ajudam o agente a escolhê-la; as instruções dizem como executar a tarefa e qual evidência coletar. Você pode ler esses arquivos antes de dar acesso ao seu projeto.

O Addy Osmani e o Matt Pocock já mantêm coleções nesse formato. Gostei da distribuição em pastas pequenas, que você consegue ler antes de instalar. Escrevi as versões genéricas a partir dos meus fluxos e depois comparei as instruções com as deles.

Onde esses workflows entram

Vários métodos se sobrepõem. A diagnosing-bugs do Matt pede reprodução e confirmação de que a mudança de teste foi aplicada. A doubt-driven-development do Addy separa o review do artefato da justificativa de quem o construiu. São decisões que também quero nas minhas tarefas.

Mantive as 11 como a seleção que uso nos projetos. Duas têm um contexto especialmente concreto aqui: AEO com a API do aeo.js e Gauntlet com rodadas de captura e crítica dos mapas do jogo. Quem já usa um workflow de review que funciona pode experimentar uma dessas duas primeiro.

O README traz um cenário, um prompt e um artefato esperado para cada skill, além dos links para as coleções complementares. A comparação das instruções ajuda a escolher o workflow; medir o resultado exige executar a mesma tarefa com e sem ele.

Comecei pelos modos de erro

Uma skill útil precisa mudar uma decisão durante o trabalho. Para selecionar as minhas, usei os problemas que cada workflow tenta evitar.

Em debugging, o agente pode corrigir um módulo parecido e deixar intacto o caminho que o usuário reportou. Em review, pode repetir a justificativa de quem escreveu o código. Em um loop de implementação, pode confundir uma sequência de tentativas com progresso.

Isso virou quatro instruções concretas:

Skill	O que peço ao agente
`evidence-driven-debugging`	Reproduzir o cenário e seguir o caminho entre interface, request, resposta e renderização.
`critical-adversarial-review`	Revisar uma revisão específica e sustentar cada finding com localização, gatilho e impacto.
`gauntlet-loop`	Estabelecer baseline, implementar, criticar, procurar regressões e registrar a decisão de cada rodada.
`quality-gates`	Verificar se a régua realmente mede o comportamento esperado.

Gosto especialmente da última. Um gate de regressão ganha credibilidade quando você aplica uma mudança deliberadamente quebrada e observa o teste falhar pelo motivo esperado. Se a mudança nem chegou a ser aplicada, o experimento ficou inconclusivo. Se faltou uma medição, o resultado continua desconhecido.

Um exemplo real do jogo: uma rodada do Gauntlet deixou o mapa mais claro mais escuro que as cenas noturnas. O agente de captura usou o frame mais escuro como referência de exposição. A regra passou a pedir a média dos oito frames. Contei o caso em Por dentro do Gauntlet loop.

Na versão pública, os critérios visuais do FPS ficam no projeto original. O que viaja é o método de definir a régua, separar construção de avaliação e guardar a evidência de cada rodada.

Review crítico precisa de liberdade para discordar

No review adversarial, o revisor recebe o artefato, o contrato e o contexto necessário para avaliar a mudança. Precisa formar o próprio julgamento sobre o resultado.

A saída que me interessa tem uma forma simples: onde está o problema, qual entrada o dispara, o que deveria acontecer, o que acontece e como verificar. Uma reprodução ainda não executada fica identificada como hipótese.

Também tirei qualquer incentivo para preencher uma cota de findings. Pedir dez bugs em uma alteração pequena cria pressão para inventar defeitos. O revisor pode terminar sem um problema comprovado e explicar quais verificações ficaram pendentes.

Você pode experimentar com uma tarefa delimitada:

Use critical-adversarial-review para revisar a alteração entre BASE e HEAD.
O endpoint deve preservar a paginação quando o filtro muda.
Leia o diff e os callers. Não altere arquivos.
Para cada finding, indique localização, entrada que dispara a falha,
resultado esperado, resultado observado e uma reprodução mínima.
Identifique hipóteses ainda não executadas. Aceito zero findings.

Troque BASE e HEAD pelas revisões reais. O prompt prende a análise a uma mudança e a um comportamento observável. A skill fornece o contrato de review e seus limites.

Pesquisa inclui saber o que um post permite concluir

Uso pesquisa em redes sociais para encontrar relatos, exemplos e problemas que a documentação deixa de fora. Isso entrou em source-backed-research junto com a pesquisa técnica.

Cada fonte precisa carregar o que ela sustenta. Um post pode documentar a experiência de uma pessoa. Curtidas medem uma forma de interação com aquele conteúdo. Uma amostra escolhida manualmente precisa ter o critério de seleção registrado.

Para comparar ferramentas, combino esse material com documentação e código quando estão disponíveis. Registro data, versão e a diferença entre observação, relato da fonte e inferência minha. Isso permite voltar a uma conclusão quando o produto muda.

A pergunta que motivou o inventário também citava análise de crédito. O pacote pode ajudar a organizar fontes e confrontar recomendações, mas esse uso exige requisitos e avaliação do domínio. Nenhuma das 11 skills foi validada como sistema de decisão de crédito.

O que extraí do Ralph Starter

O Ralph Starter já tem skills próprias, várias ligadas às integrações do produto. Nesta coleção, extraí três métodos do executor e da coordenação:

Skill	Decisão que organiza
`spec-to-plan`	Qual comportamento observável define que a tarefa terminou?
`validated-coding-loop`	Qual evidência orienta a próxima tentativa e quando o loop deve parar?
`agent-worktree-orchestration`	Quem pode escrever onde e como comparar os candidatos?

A inspeção encontrou um detalhe bom da diferença entre intenção e implementação. No swarm.ts da revisão analisada, o comentário descreve um juiz LLM para o modo consensus. O código seleciona entre os resultados bem-sucedidos pelo número de iterações.

Por isso a skill pede uma régua explícita de aceitação. Menos iterações pode ser uma informação de custo; a correção precisa da própria evidência. O artigo sobre o Ralph Starter explica o executor que inspirou esses métodos.

A skill multi-agent-collaboration veio de outro contexto, meu trabalho com ECDSA. Generalizei os handoffs, a reprodução independente e a resolução de hipóteses conflitantes. Os detalhes de circuitos e métricas daquele domínio ficaram no projeto original.

Colaboração entra quando a tarefa permite agentes em paralelo. Para uma correção pequena, o custo de preparar o handoff e reconciliar resultados pode superar o benefício. O pacote mantém essa decisão no escopo da tarefa.

AEO com aeo.js também entrou

A skill aeo usa o aeo.js para auditar e implementar as superfícies públicas de descoberta de um site: política de crawlers, URLs canônicas, sitemap, conteúdo legível por máquinas e dados estruturados. AEO vem de Answer Engine Optimization: preparar esse conteúdo para mecanismos que produzem respostas.

Ela começa pela configuração existente. Se outra integração já gera robots.txt e sitemap, precisamos preservar esse dono e desabilitar os geradores sobrepostos. A política de acesso também precisa continuar refletindo a intenção do projeto.

Autenticação e autorização do conteúdo restrito continuam na aplicação. Arquivos como robots.txt e llms.txt descrevem política de crawlers e descoberta; não impõem controle de acesso.

Na validação, arquivo gerado e resposta servida são etapas distintas. Um schema.json no build pede uma verificação adicional de como os dados chegam à página. O score do auditor descreve os critérios da ferramenta; citações em respostas e ganhos de tráfego precisam de observações próprias.

Até a versão merece inspeção. Na revisão usada como referência, o package.json diz 0.0.17, enquanto a constante exibida pelo CLI diz 0.0.14. Registrei o commit junto dos comandos para deixar a referência reproduzível.

Três tarefas, com e sem skill

Preparei três tarefas sintéticas: corrigir um gate que aceita observações ausentes, reduzir leituras de dados em uma rota e reparar a descoberta EN/PT com aeo.js. Cada par usa sessões novas do mesmo Claude Code, com o mesmo modelo, ferramentas e limites. Uma sessão recebe o texto da skill e suas referências; a outra recebe só a tarefa.

A primeira rodada expôs uma falha do enunciado. Cinco das seis sessões pediram comandos de shell ou Git que o ambiente não permitia. Ficaram sem pontuação, conforme o protocolo. Congelei uma segunda versão explicando os comandos Node disponíveis, com a mesma orientação nos dois lados e sem mudar os checks. As tentativas anteriores continuam no relatório do piloto.

As seis sessões da segunda rodada concluíram sem comandos negados:

Tarefa	Sem texto da skill	Com texto da skill
Gate de release	5/5 checks	5/5 checks
Resumo de participantes	4/4 checks, 400 leituras	4/4 checks, 400 leituras
Descoberta EN/PT	4/5 checks	5/5 checks

No caso de AEO, o baseline manteve o rascunho em config.routes e desligou geradores de descoberta. A página não publicada continuou respondendo HTTP 200. A sessão com a skill removeu essa rota e o probe recebeu 404. Os dois lados preservaram robots e sitemap. É uma diferença observada em um fixture que exige excluir conteúdo não publicado; os outros dois casos empataram. Uma execução por lado não estabelece eficácia geral.

Esses casos exercitam instruções fornecidas diretamente ao Claude Code. A descoberta automática das skills, o comportamento no Codex e o review visual dos mapas precisam de execuções próprias. As coleções do Matt e do Addy ficaram fora dos braços do experimento.

Como experimentar uma skill

O pacote compartilha os mesmos arquivos SKILL.md entre os agentes. Cada pasta contém o nome, a descrição e as instruções, com referências locais quando o workflow precisa delas. Os metadados de distribuição ficam separados.

Instale só a skill que você precisa. Na raiz do projeto onde vai usá-la, escolha o comando do seu agente:

# Codex: só aeo neste projeto
npx skills add rubenmarcus/agent-skills --skill aeo --agent codex --copy

# Claude Code: só aeo neste projeto
npx skills add rubenmarcus/agent-skills --skill aeo --agent claude-code --copy

Troque aeo por qualquer nome de skill do README. Os comandos usam a CLI skills da Vercel, uma ferramenta opcional que exige Node.js 22.20+. Eles copiam só a skill escolhida e os arquivos de apoio para .agents/skills/ no Codex ou .claude/skills/ no Claude Code. Confira o destino e qualquer aviso de sobrescrita antes de confirmar.

O README também explica como copiar uma pasta manualmente, sem a CLI. O plugin do marketplace do Claude é uma opção para instalar as 11 skills juntas. O exemplo da git-quality-hooks fica inativo até você configurá-lo, preservando os hooks existentes.

Com a aeo disponível, eu começaria por uma auditoria que gere algo para revisar:

Use aeo para auditar as páginas públicas em inglês e português deste site Astro.
Registre a origem canônica, os idiomas, a versão instalada do aeo.js
e qual integração é dona de robots.txt e do sitemap.
Inspecione canônicas e dados estruturados nas respostas servidas. Liste
as rotas públicas pretendidas e qualquer conteúdo não publicado na descoberta.
Escreva os findings e a menor mudança proposta. Aguarde antes de editar.

O primeiro resultado deve ser um inventário e uma proposta de mudança. Para uma tarefa de implementação, acrescente o escopo aceito e as respostas que você espera verificar depois do build. O README tem um cenário e um artefato esperado para cada skill.

Os checks de estrutura, manifests e exemplos isolados passaram na preparação. O piloto usa fixtures sintéticos, incluindo o ciclo do adapter AEO e respostas HTTP locais. A avaliação comportamental completa das 11 skills com Codex e Claude continua pendente, com cenários registrados no repo.

Para começar, escolha um problema recorrente do seu projeto. Escreva a evidência que faria você aceitar a solução e rode a skill em uma tarefa pequena. Guarde o resultado, inclusive quando o agente ignorar uma instrução. Use esse material para corrigir a próxima versão.