Agent Skill: Sistema de Aprendizagem Auto-Melhorável - detecta…

Coach – Sistema de Aprendizagem Auto-Melhorável

O Coach permite que o Claude aprenda com atritos e melhore ao longo do tempo. Ele detecta oportunidades de aprendizado (correções do usuário, instruções repetidas, falhas de ferramentas, escalada de tom), extrai candidatos a melhoria acionáveis e propõe alterações que exigem aprovação explícita do usuário.

Princípio Central: Sem escritas silenciosas. Todas as melhorias exigem aprovação do usuário via /coach approve.

Gatilhos de Ativação

Ative quando: correções do usuário ("não", "pare", "não faça"), instruções repetidas, falhas de ferramentas/comandos, escalada de tom (CAPS LOCK, "!!!"), suplementos de skill ("lembre-se também..."), avisos de ferramentas obsoletas, comandos explícitos /coach, ou fim de sessão.

Categorias de Sinal (Ordem de Prioridade)

1. COMMAND_FAILURE (Mais Alta) – Saída não-zero, padrões em stderr
2. USER_CORRECTION (Alta) – Linguagem explícita de correção
3. SKILL_SUPPLEMENT (Alta) – Orientação adicional para uma skill
4. VERSION_ISSUE (Média-Alta) – Avisos de obsoletos/desatualizados
5. REPETITION (Média) – Instrução semanticamente semelhante repetida
6. TONE_ESCALATION (Baixa) – Indicadores de frustração

Tipos de Candidato

Tipo	Descrição	Exemplo
rule	Restrição estável	"Nunca editar arquivos gerados"
checklist	Etapa de workflow	"Executar testes após alteração de código"
snippet	Comando reutilizável	"Script de verificação prévia"
skill	Sugestão de atualização de skill	"Adicionar orientação X à skill Y"
antipattern	Coisas a nunca fazer	"Nunca assumir que a ferramenta existe"

Resumo do Workflow

1. Detecção — hooks capturam eventos → ~/.claude-coach/events.sqlite
2. Geração — agrega sinais em propostas (fingerprints deduplicam)
3. Escopo — projeto vs. global por caminho/linguagem
4. Revisão — /coach review aprova/rejeita/edita
5. Aplicação — regras aprovadas → CLAUDE.md
6. Retrospectiva — /coach retro mapeia trabalho manual para lacunas de skill, abre PRs em repositórios fonte

Localizações dos Arquivos

~/.claude-coach/
├── events.sqlite      # Eventos brutos de atrito
├── candidates.json    # Propostas pendentes
└── ledger.sqlite      # Fingerprints entre repositórios

~/.claude/ ou <repo>/.claude/
├── CLAUDE.md          # Destino das regras
├── checklists/        # Checklists de workflow
└── snippets/          # Comandos reutilizáveis

Scripts

Execute a partir de ${CLAUDE_PLUGIN_ROOT}/scripts/:

Script	Propósito
init_coach.py	Inicializar o sistema Coach
detect_signals.py	Detecção de padrões de atrito
aggregate.py	Transformar sinais em candidatos
skill_analyzer.py	Analisar skills e verificar ferramentas obsoletas
apply.py	Aplicar propostas aprovadas

Comandos Proativos

• /coach scan — Verificar ferramentas CLI e dependências desatualizadas
• /coach retro — Retrospectiva de sessão: analisar trabalho manual, criar PRs para melhorar skills no repositório fonte

Para arquitetura detalhada, esquemas e padrões, consulte o diretório references/.