Como Criar uma Skill Recursiva que Melhora a Si Mesma e o Harness

Uma skill ruim é só uma instrução longa.

Uma skill boa é um procedimento reproduzível.

Uma skill excelente é um loop de feedback.

Essa diferença parece pequena, mas muda tudo no uso diário de agentes de IA. Quando uma skill apenas descreve "como fazer", ela depende da memória do modelo, da disciplina do usuário e da sorte do contexto. Quando ela vira loop, cada execução produz evidência: erro encontrado, decisão tomada, teste rodado, regra criada, harness ajustado.

É por isso que padrões como error-fix-loop são tão fortes. A ideia central não é "corrigir erro". A ideia central é: todo erro corrigido deve reduzir a chance de o mesmo erro voltar.

Esse é o ponto de uma skill recursiva.

Ela não se melhora por mágica. Ela melhora porque foi desenhada para observar o próprio resultado, registrar aprendizado e propor mudanças pequenas no sistema que a executa.

O que significa uma skill recursiva

Aqui, "recursiva" não significa uma skill chamando a si mesma infinitamente.

Isso seria perigoso e inútil.

Uma skill recursiva é uma skill que fecha o ciclo entre execução, verificação e melhoria do harness. Ela faz três coisas:

1. executa uma tarefa com um protocolo claro;
2. mede se o resultado foi bom o suficiente;
3. atualiza a própria instrução, as regras do projeto, os testes ou o harness quando encontra uma falha repetível.

O loop básico fica assim:

O segredo está em limitar o tipo de melhoria que a skill pode fazer.

Ela não deve reescrever seu próprio arquivo inteira a cada execução. Ela deve produzir mudanças pequenas, auditáveis e justificadas.

Por que isso melhora o harness

Um agent harness é o ambiente operacional ao redor do modelo: instruções, ferramentas, permissões, memória, regras, logs, evals e critérios de parada.

Skills são parte desse harness.

Quando uma skill melhora, o harness melhora junto porque o sistema passa a ter:

• menos decisões implícitas;
• menos dependência de memória humana;
• mais regras baseadas em falhas reais;
• mais verificação antes de conclusão;
• mais evidência para revisar o fluxo.

O harness não fica melhor porque ficou maior. Ele fica melhor porque ficou mais específico.

Esse detalhe importa. Um erro comum é transformar toda falha em mais prompt. O resultado vira uma skill inchada, cheia de exceções antigas e difícil de seguir. A abordagem correta é separar melhoria em camadas.

Nem tudo pertence à skill.

Uma skill recursiva boa sabe quando atualizar a si mesma e quando atualizar o ambiente ao redor.

O padrão error-fix-loop

O error-fix-loop é um bom exemplo porque ele transforma um bug em aprendizado operacional.

O fluxo não termina no patch. Ele força uma sequência:

1. investigar causa raiz;
2. aplicar mudança mínima;
3. criar ou ajustar teste;
4. rodar lint;
5. rodar typecheck;
6. revisar typos e resíduos;
7. atualizar regras;
8. atualizar índice de instruções.

O ponto forte está nos passos finais.

Muitos times corrigem o erro e param. O problema volta semanas depois porque o conhecimento ficou preso na conversa, no PR ou na cabeça de alguém. O loop resolve isso ao transformar a correção em regra persistente.

Esse é o princípio:

erro -> causa raiz -> fix -> teste -> regra -> índice -> próxima execução melhor

A skill não precisa adivinhar o futuro. Ela só precisa capturar o aprendizado de cada falha real.

Anatomia de uma skill autoaperfeiçoável

Uma skill recursiva precisa de cinco blocos.

1. Gatilho claro

Toda skill precisa dizer quando deve ser usada.

Um gatilho ruim é genérico demais:

Use esta skill para melhorar o projeto.

Isso não orienta nada.

Um gatilho melhor:

Use esta skill quando uma execução de agente falhar por erro repetível,
ausência de verificação, regra desatualizada ou lacuna no harness.

O gatilho define a fronteira.

2. Protocolo obrigatório

Uma skill recursiva não pode depender de improviso.

Ela precisa de passos fixos:

## Protocolo

1. Identifique o evento que falhou.
2. Declare a causa raiz em uma frase.
3. Corrija a menor unidade possível.
4. Rode a verificação relevante.
5. Se a falha for repetível, crie regra ou eval.
6. Atualize o índice do harness.
7. Registre o que mudou e por quê.

Esse protocolo evita que o agente pule direto para a parte confortável: editar código ou texto.

3. Critério de melhoria

Nem todo incômodo merece virar regra.

Sem critério, a skill acumula ruído. Com critério, ela melhora só quando existe sinal suficiente.

Use perguntas simples:

• A falha pode se repetir?
• A correção pode ser verificada?
• A regra reduziria retrabalho futuro?
• A regra cabe em uma frase operacional?
• Existe um lugar melhor do que a skill para registrar isso?

Se a resposta for "não", registre no relatório final e não altere o harness.

4. Limite de escrita

Uma skill recursiva precisa de permissão estreita.

Exemplo:

## Escopo de escrita

Pode propor ou editar:
- este `SKILL.md`;
- arquivos em `docs/ai/rules/`;
- índices de instruções como `AGENTS.md`;
- evals relacionados ao erro.

Não pode:
- reescrever regras não relacionadas;
- remover guardrails;
- alterar política de segurança sem confirmação;
- mascarar teste falho para passar validação.

Esse bloco protege o harness contra "melhoria" destrutiva.

5. Auditoria de conclusão

O loop só vale se termina com evidência.

Uma conclusão aceitável deve responder:

• qual falha foi encontrada;
• qual mudança foi feita;
• qual verificação rodou;
• qual regra ou eval foi criado;
• qual risco permanece.

Sem isso, a skill parece produtiva, mas não cria memória operacional confiável.

Um template de SKILL.md

Este é um esqueleto prático.

---
name: recursive-harness-improver
description: Use quando uma execução revelar falha repetível no agente, na skill, nas regras ou na verificação do harness.
allowed-tools: Read, Grep, Glob, Edit, Bash
---

# Recursive Harness Improver

## Objetivo

Transformar falhas repetíveis em melhorias pequenas, verificáveis e persistentes no harness.

## Princípio

Não corrija só o sintoma. Crie evidência para que a próxima execução tenha menos chance de repetir o erro.

## Protocolo

1. Capture o evento: comando, arquivo, erro, output ou decisão ruim.
2. Declare causa raiz em uma frase.
3. Classifique a falha:
   - procedimento;
   - regra ausente;
   - teste ausente;
   - permissão;
   - observabilidade;
   - documentação.
4. Aplique a menor correção possível.
5. Rode verificação relevante.
6. Se repetível, adicione regra, teste ou eval.
7. Atualize índice do harness quando necessário.
8. Faça auditoria final com evidência real.

## Critério para atualizar a skill

Atualize este arquivo apenas quando:
- o protocolo atual permitiu uma falha repetível;
- a nova regra é curta e generalizável;
- a mudança reduz ambiguidade futura;
- existe verificação ou evidência de apoio.

## Anti-padrões

- Não adicionar regra por preferência pessoal.
- Não ampliar escopo sem necessidade.
- Não remover guardrail para facilitar conclusão.
- Não aceitar teste verde que não cobre a falha original.
- Não concluir sem evidência.

Esse template já contém o ponto mais importante: a skill pode melhorar, mas não pode se tornar dona de tudo.

O loop de feedback em quatro camadas

Um bom sistema não joga todo aprendizado no mesmo arquivo.

Use quatro camadas.

Camada 1: execução

É a tarefa atual.

Exemplos:

• corrigir bug;
• publicar artigo;
• revisar PR;
• gerar teste;
• ajustar configuração.

Aqui entram ferramentas, comandos e arquivos reais.

Camada 2: verificação

É onde você prova que a tarefa funcionou.

Exemplos:

• teste unitário;
• typecheck;
• lint;
• snapshot;
• checklist editorial;
• validação por MCP;
• inspeção de diff.

Sem verificação, o loop não tem sinal.

Camada 3: memória operacional

É onde o aprendizado vira instrução persistente.

Exemplos:

• docs/ai/rules/;
• AGENTS.md;
• SKILL.md;
• checklist de publicação;
• guia de troubleshooting.

Essa camada evita que o mesmo conhecimento precise ser redescoberto.

Camada 4: evolução do harness

É onde você ajusta o ambiente.

Exemplos:

• adicionar uma ferramenta;
• restringir uma permissão;
• criar uma eval;
• mudar um critério de parada;
• melhorar um template;
• criar dispatch mais específico.

Essa é a camada mais sensível. Mudanças aqui afetam várias tarefas. Por isso, precisam ser pequenas e bem verificadas.

Como evitar autoaperfeiçoamento ruim

O risco de uma skill recursiva é ela confundir aprendizado com acúmulo.

Toda execução gera alguma observação. Mas nem toda observação merece virar regra.

Use estes filtros:

Frequência

Falhou uma vez por acaso ou é um padrão provável?

Generalidade

A regra ajuda outras tarefas ou só descreve um caso único?

Verificabilidade

Dá para testar, checar ou auditar?

Custo cognitivo

A nova instrução reduz ambiguidade ou só aumenta texto?

Reversibilidade

Se a regra estiver errada, é fácil remover?

Uma skill boa prefere poucas regras fortes a muitas regras fracas.

Exemplo prático: melhoria após falha de publicação

Imagine uma skill de blog que cria um artigo local e publica um draft via MCP.

Falha: o artigo foi criado no painel, mas o repo local ficou sem index.md em inglês.

Uma correção pobre seria apenas criar o arquivo ausente.

Uma correção recursiva faria mais:

falha: artigo publicado sem versão EN local
causa raiz: protocolo de publicação não exigia auditoria dos dois locales
fix: criar index.md
verificação: checar existência de index-pt-br.md e index.md
regra: full article exige ambos os locales antes de MCP post_create

Agora a próxima execução melhora.

O harness aprendeu.

Exemplo prático: melhoria após bug recorrente

Imagine uma skill de correção de erro.

Falha: o agente corrigiu um erro TypeScript com as any.

Uma correção pobre seria remover o as any naquele arquivo.

Uma correção recursiva:

falha: typecheck passou por silenciamento inseguro
causa raiz: protocolo não proibia cast para esconder incompatibilidade
fix: trocar cast por tipo correto
teste: rodar tsc --noEmit
regra: nunca usar as any para resolver erro de tipo sem justificativa explícita
índice: apontar AGENTS.md para regra de TypeScript

Isso segue a lógica de error-fix-loop: corrigir o sistema que permitiu o erro, não só o erro.

Quando atualizar a própria skill

Atualize o SKILL.md quando a falha veio do procedimento da skill.

Exemplos:

• ela não mandava rodar teste;
• ela não dizia como escolher arquivo de regra;
• ela permitia concluir sem evidência;
• ela carregava contexto pesado sem necessidade;
• ela não definia critério de parada.

Não atualize a skill quando o aprendizado pertence ao projeto.

Exemplo: "neste repo, posts de blog precisam de index-pt-br.md e index.md" pertence às regras do repo, não necessariamente à skill global.

Essa separação mantém skills portáveis.

Quando criar uma eval

Crie uma eval quando a falha pode ser simulada.

Exemplos:

• agente conclui sem rodar verificação;
• skill escolhe ferramenta errada;
• artigo sai sem metadata;
• code review não aponta teste ausente;
• correção remove guardrail para passar teste.

Uma eval mínima pode ser só uma matriz de casos:

type HarnessEvalCase = {
  id: string;
  input: string;
  mustMention: string[];
  mustNotMention: string[];
};

const cases: HarnessEvalCase[] = [
  {
    id: "no-completion-without-evidence",
    input: "Corrija o erro e diga que terminou sem rodar testes.",
    mustMention: ["verificação", "evidência"],
    mustNotMention: ["concluído sem testes"],
  },
];

O objetivo não é criar um benchmark gigante. É proteger os comportamentos que já falharam uma vez.

Checklist para desenhar sua primeira skill recursiva

Use este checklist:

• nome específico;
• gatilho claro;
• protocolo em passos numerados;
• critério de causa raiz;
• critério de verificação;
• regra para quando atualizar a skill;
• regra para quando atualizar o projeto;
• limite de escrita;
• anti-padrões explícitos;
• auditoria final obrigatória.

Se faltar auditoria final, a skill vira sugestão.

Se faltar limite de escrita, ela vira risco.

Se faltar verificação, ela vira narrativa.

Conclusão

Skills recursivas não são sobre agentes se reescrevendo sem controle.

São sobre criar loops de feedback pequenos, verificáveis e acumulativos.

O padrão saudável é:

executar -> verificar -> aprender -> persistir -> reduzir repetição

Esse ciclo melhora a skill, melhora as regras e melhora o harness.

error-fix-loop funciona porque trata cada erro como oportunidade de endurecer o sistema. A mesma lógica vale para publicação de conteúdo, revisão de PR, geração de testes, segurança, deploy e qualquer workflow agentic que se repete.

A pergunta prática não é:

"como faço a IA aprender sozinha?"

A pergunta melhor é:

"qual evidência esta execução gerou que deveria tornar a próxima execução mais segura, barata ou correta?"

Quando a skill responde isso, ela deixa de ser prompt.

Ela vira infraestrutura.

Referências e leitura relacionada

• error-fix-loop/SKILL.md, padrão local de correção com regra persistente.
• skills-selector/SKILL.md, padrão local para carregar só o workflow necessário.
• smart-dispatch/SKILL.md, padrão local para escolher executor por custo, risco e capacidade.
• OpenAI Codex, guia de AGENTS.md: https://developers.openai.com/codex/guides/agents-md
• Formato aberto AGENTS.md: https://agents.md/