Metodologia de Melhoria de Habilidades

Melhore iterativamente uma habilidade do Claude Code usando o agente skill-reviewer até que ela atenda aos padrões de qualidade.

Pré-requisitos

Requer o plugin plugin-dev que fornece o agente skill-reviewer.

Verifique se está ativado: execute /plugins — plugin-dev deve aparecer na lista. Se estiver faltando, instale do repositório de plugins da Trail of Bits.

Loop Principal

1. Revisar - Chame o skill-reviewer na habilidade alvo
2. Categorizar - Analise os problemas por gravidade
3. Corrigir - Resolva problemas críticos e importantes
4. Avaliar - Verifique problemas menores quanto à validade antes de corrigir
5. Repetir - Continue até que o padrão de qualidade seja atingido

Quando Usar

• Melhorar uma habilidade com vários problemas de qualidade
• Iterar em uma nova habilidade até que ela atenda aos padrões
• Ciclos automatizados de correção-revisão em vez de edição manual
• Aplicação consistente de qualidade em todas as habilidades

Quando NÃO Usar

• Revisão única: Use /skill-reviewer diretamente em vez disso
• Correções rápidas e únicas: Edite o arquivo diretamente
• Arquivos não de habilidade: Funciona apenas em arquivos SKILL.md
• Habilidades experimentais: A iteração manual oferece mais controle durante a exploração

Categorização de Problemas

Problemas Críticos (DEVEM ser corrigidos imediatamente)

Estes bloqueiam o carregamento da habilidade ou causam falhas em tempo de execução:

• Campos de metadados obrigatórios ausentes (nome, descrição) — O Claude não consegue indexar ou acionar a habilidade
• Sintaxe inválida de metadados YAML — Falha na análise, a habilidade não carregará
• Arquivos referenciados que não existem — Erros em tempo de execução quando o Claude segue links
• Caminhos de arquivo quebrados — O mesmo que acima, leva a falhas na ferramenta

Problemas Importantes (DEVEM ser corrigidos)

Estes degradam significativamente a eficácia da habilidade:

• Descrições de gatilho fracas ou vagas — O Claude pode não reconhecer quando usar a habilidade
• Voz de escrita incorreta (segunda pessoa "você" em vez de imperativo) — Inconsistente com o modelo de execução do Claude
• SKILL.md excede 500 linhas sem usar referências/ — Sobrecarga de contexto, reduz a compreensão
• Seções "Quando Usar" ou "Quando NÃO Usar" ausentes — Exigido pelos padrões de qualidade do projeto
• Descrição não especifica quando acionar — A habilidade pode nunca ser selecionada

Problemas Menores (Avaliar antes de corrigir)

Estes são itens de polimento que podem ou não melhorar a habilidade:

• Preferências de estilo subjetivas — O revisor pode ter um gosto diferente do autor
• Melhorias opcionais — Podem adicionar complexidade sem valor proporcional
• Melhorias "bom ter" — Considere custo-benefício antes de implementar
• Sugestões de formatação — Frequentemente válidas, mas de baixo impacto

Avaliação de Problemas Menores

Antes de implementar qualquer correção de problema menor, avalie:

1. Esta é uma melhoria genuína? - Ela adiciona valor real ou apenas satisfaz uma preferência?
2. Pode ser um falso positivo? - O revisor está entendendo mal o contexto?
3. Isso realmente ajudaria o Claude a usar a habilidade? - Concentre-se em melhorias funcionais

Implemente apenas correções menores que sejam claramente benéficas. O skill-reviewer pode produzir falsos positivos.

Invocando o skill-reviewer

Use o agente skill-reviewer do plugin plugin-dev. Solicite uma revisão pedindo ao Claude para:

Revise a habilidade em [SKILL_PATH] usando o agente plugin-dev:skill-reviewer. Forneça uma avaliação de qualidade detalhada com problemas categorizados por gravidade.

Substitua [SKILL_PATH] pelo caminho absoluto para o diretório da habilidade (por exemplo, /path/to/plugins/my-plugin/skills/my-skill).

Exemplo de Ciclo de Correção

Iteração 1 — saída do skill-reviewer:

Critical: SKILL.md:1 - Missing required 'name' field in frontmatter
Major: SKILL.md:3 - Description uses second person ("you should use")
Major: Missing "When NOT to Use" section
Minor: Line 45 is verbose

Correções aplicadas:

• Adicionado campo name aos metadados
• Reescreveu a descrição em terceira pessoa
• Adicionada seção "Quando NÃO Usar"

Iteração 2 — execute o skill-reviewer novamente para verificar as correções:

Minor: Line 45 is verbose

Avaliação de problema menor: A linha 45 se comunica efetivamente como está. A verbosidade fornece contexto útil. Pular.

Todos os problemas críticos/importantes resolvidos. Imprima o marcador de conclusão:

<skill-improvement-complete>

Nota: O marcador DEVE aparecer na saída. Declarações como "padrão de qualidade atingido" ou "parece bom" NÃO interromperão o loop.

Critérios de Conclusão

CRÍTICO: O hook de parada VERIFICA APENAS o marcador explícito abaixo. Nenhum outro sinal encerrará o loop.

Imprima este marcador quando terminar:

<skill-improvement-complete>

Quando imprimir o marcador:

…