Revisão e Validação de Habilidades
Processo
Etapa 1: Localizar Arquivos da Habilidade
Aceitar entrada como:
- Caminho para um diretório de habilidade
- Nome da habilidade (pesquisar em
~/.claude/skills/) - URL para um repositório GitHub
Ler todos os arquivos .md, scripts e arquivos de ativos.
Etapa 2: Validação de Estrutura
Executar python scripts/validate_skill.py <caminho> para verificações programáticas.
Verificação manual:
- SKILL.md existe (maiúsculas/minúsculas exatas)
- Nenhum README.md dentro da pasta de habilidade
- Nome da pasta corresponde ao campo
name - Nomenclatura kebab-case válida (1-64 caracteres)
- Nenhum "claude" ou "anthropic" no nome
Etapa 3: Auditoria de Frontmatter
| Verificação | Critério de Aprovação |
|---|---|
| Formato do nome | kebab-case, 1-64 caracteres, sem hífens no início/fim |
| Descrição presente | Não vazia, 1-1024 caracteres |
| Descrição tem O QUE | Explica capacidades |
| Descrição tem QUANDO | Inclui frases de gatilho |
| Descrição tem palavras-chave | Termos específicos do domínio incluídos |
| Sem tags XML | Sem caracteres < ou > |
| Campos opcionais válidos | licença, compatibilidade (<500 caracteres), metadados |
Etapa 4: Análise de Acionamento
Avaliar a descrição quanto à qualidade de ativação:
Riscos de sub-acionamento:
- Muito genérico ("Ajuda com projetos")
- Faltam paráfrases comuns
- Sem palavras-chave de domínio
- Faltam menções a tipos de arquivo (se relevante)
Riscos de sobre-acionamento:
- Muito amplo ("Processa documentos")
- Sobreposição com capacidades internas do Claude
- Faltam gatilhos negativos para desambiguação
Gerar consultas de teste:
- 5 consultas que DEVEM acionar a habilidade
- 5 consultas que NÃO DEVEM acionar
- 3 casos extremos (consultas ambíguas)
Etapa 5: Qualidade das Instruções
| Critério | Pontuação (0-10) |
|---|---|
| Especificidade | As instruções são acionáveis? (não "validar corretamente") |
| Completude | Todos os fluxos de trabalho cobertos? |
| Tratamento de erros | Falhas comuns abordadas? |
| Exemplos | Exemplos concretos fornecidos? |
| Divulgação progressiva | Documentos detalhados em referências/ e não em SKILL.md? |
| Tamanho | Abaixo de 500 linhas / 5000 tokens? |
| Referências cruzadas | Links claros para referências/scripts? |
Etapa 6: Revisão de Arquitetura (Multi-habilidade)
Para habilidades com sub-habilidades:
- Habilidade principal tem tabela de roteamento clara
- Sub-habilidades têm responsabilidades focadas
- Referências cruzadas são válidas (arquivos existem)
- Nomenclatura segue convenção
pai-filho - Referências compartilhadas no pai, não duplicadas
- Agentes têm papéis claros (se Nível 4)
Etapa 7: Qualidade dos Scripts (se presentes)
- Docstrings com propósito, entrada, saída
- Interface CLI (argparse ou similar)
- Saída estruturada (JSON)
- Tratamento de erros (try/except com mensagens claras)
- Sem caminhos codificados ou segredos
- Dependências mínimas
Etapa 8: Gerar Pontuação de Saúde da Habilidade
Metodologia de pontuação (0-100):
| Categoria | Peso | Verificações |
|---|---|---|
| Qualidade do Frontmatter | 25% | Nome, descrição, formato |
| Precisão do Acionamento | 20% | O QUE + QUANDO + palavras-chave |
| Qualidade das Instruções | 25% | Especificidade, completude, exemplos |
| Conformidade Estrutural | 15% | Nomenclatura de arquivos, organização, referências |
| Qualidade dos Scripts | 10% | Se aplicável (pontuação máxima se nenhum script for necessário) |
| Divulgação Progressiva | 5% | Uso correto do sistema de 3 níveis |
Etapa 9: Gerar Conjunto de Avaliação de Gatilhos
Após a revisão, gerar um conjunto de avaliação de gatilhos estruturado para testes contínuos:
- Executar
python scripts/generate_eval_set.py <caminho>para gerar automaticamente um conjunto inicial - Revisar e refinar as consultas geradas:
- Garantir que 8-10 consultas de acionamento cubram diferentes formulações e casos extremos
- Garantir que 8-10 consultas de não-acionamento sejam quase acertos (não obviamente irrelevantes)
- Incluir linguagem casual, erros de digitação e usos incomuns do domínio no conjunto de acionamento
- Salvar o conjunto de avaliação em
evals/evals.jsonno diretório da habilidade
Boas consultas são realistas e específicas (incluem caminhos de arquivo, contexto, detalhes de domínio). Consultas ruins são excessivamente genéricas ("formatar esses dados") ou obviamente irrelevantes.
- Executar
python scripts/optimize_description.py <caminho> --eval-set evals/evals.jsonpara pontuar a descrição atual e obter sugestões de melhoria - Recomendar executar
/skill-forge eval <caminho>para avaliação funcional completa
Etapa 10: Gerar Relatório
# Revisão da Habilidade: [nome]
## Pontuação de Saúde: [X]/100
## Resumo
[Avaliação de 2-3 frases]
## Pontuações por Categoria
| Categoria | Pontuação | Observações |
|-----------|-----------|-------------|
| Frontmatter | X/25 | [problemas] |
| Acionamento | X/20 | [problemas] |
| Instruções | X/25 | [problemas] |
| Estrutura | X/15 | [problemas] |
| Scripts | X/10 | [problemas] |
| Divulgação | X/5 | [problemas] |
## Problemas Críticos (corrigir imediatamente)
- [problema 1]
- [problema 2]
## Alta Prioridade (corrigir em 1 semana)
- [problema 1]
## Recomendações
- [sugestão 1]
- [sugestão 2]
## Consultas de Teste Sugeridas
### Devem Acionar
1. [consulta]
2. [consulta]
3. [consulta]
### Não Devem Acionar
1. [consulta]
2. [consulta]
3. [consulta]