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:

```text
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:

```text
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:

```typescript
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 é:

```text
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/