liuchunming033/skill-doctor

Skill Doctor — Ferramenta de Diagnóstico de Saúde para Skills

Fluxo

1. Ler o diretório da Skill especificada
2. Verificar se os arquivos principais existem (SKILL.md, gotchas.md, etc.)
3. Chamar o script para obter relatório estruturado: python scripts/analyze_skill.py <skill_path> --output json, obtendo pontuações, problemas e sugestões para cada item de verificação
4. Para cada item com pontuação baixa (<70), complementar com recomendações específicas de otimização + ganho esperado + estimativa de esforço
5. Listar todos os itens otimizáveis e deixar o usuário escolher quais aceitar
6. Otimizar cada item aceito pelo usuário (modificando arquivos diretamente)
7. Após a otimização, executar novamente o script para reavaliar e gerar um relatório comparativo

O Agente é responsável pela camada inteligente (recomendações de otimização, interação com o usuário, execução de modificações), enquanto o script é responsável pela camada estável (cálculo de pontuação, saída estruturada). Veja o uso do script em scripts/analyze_skill.py.

Nove Dimensões de Verificação de Saúde

Item de Verificação	O que verifica	Critério de Aprovação
Verificação de description	Se está escrita como condição de acionamento, não como descrição de funcionalidade	Contém palavras-chave de acionamento, comprimento < 100 caracteres
Verificação de gotchas	Se possui registro de armadilhas	gotchas.md existe e não está vazio
Verificação de organização de arquivos	Se está organizada segundo o padrão de três categorias	Diretório raiz contém apenas SKILL.md + gotchas.md + examples.md, materiais de referência em reference/, scripts em scripts/, configuração em config/
Verificação de restrições excessivas	Se restringe excessivamente o caminho	Não possui fluxos rígidos como "primeiro passo, segundo passo"
Verificação de conhecimento conhecido	Se repete conteúdo já conhecido pelo Agente	Não possui tutoriais como "O que é X", "Como usar Y"
Verificação de configuração de memória	Se possui config.json	config.json existe com configuração razoável
Verificação de scripts	Se precisa de script mas está ausente	Se requer capacidade estável, possui diretório scripts/
Verificação de hooks	Se a configuração de hooks está correta	Formato PreToolUse/PostToolUse está correto
Verificação de formato markdown	Se o formato está padronizado	YAML, tabelas, blocos de código com formato correto

Formato do Relatório de Saúde

{
  "skill_name": "xxx",
  "overall_score": 55,
  "grade": "D",
  "check_results": {
    "description": {"score": 50, "issues": ["Escrito como descrição de funcionalidade"], "suggestions": ["Reescrever como condição de acionamento"], "expected_gain": 40},
    "gotchas": {"score": 40, "issues": ["gotchas.md é apenas um esqueleto vazio"], "suggestions": ["Adicionar 3 ou mais armadilhas reais"], "expected_gain": 50}
  },
  "optimization_options": [
    {"id": 1, "item": "description", "current_score": 50, "expected_score": 90, "gain": 40,
     "effort": "Baixo", "action": "Reescrever description como condição de acionamento",
     "token_saved_per_call": 50, "time_saved_per_call_sec": 0},
    {"id": 2, "item": "gotchas", "current_score": 40, "expected_score": 90, "gain": 50,
     "effort": "Médio", "action": "Adicionar armadilhas reais",
     "token_saved_per_call": 0, "time_saved_per_call_sec": 180}
  ],
  "overall_after_accept_all": 85,
  "total_benefits": {
    "token_saved_per_call": 200,
    "time_saved_per_call_sec": 300
  }
}

Regras de Estimativa de Benefícios

Tipo de Otimização	Economia de Tokens (por chamada)	Economia de Tempo (por chamada)	Descrição
Encurtar description	Cada caractere extra × 1 token	—	Reduz a carga do contexto
Complementar gotchas	—	2-5 minutos por armadilha	Evita depuração repetitiva
Dividir arquivos	(Linhas originais - novas) × 3 tokens	—	Mover materiais de referência para reference/, carregar sob demanda (não entram no contexto)
Restrições excessivas → Framework de decisão	Cada passo rígido × 20 tokens	10-30 segundos por passo	Reduz execução de passos inúteis
Remover conhecimento conhecido	Comprimento do parágrafo de tutorial em tokens	—	Não repete conteúdo já conhecido pelo Agente
Encapsular em script	—	1-3 minutos cada vez	Evita que o Agente reescreva o mesmo código toda vez

Benefícios são estimativas por chamada única. Os valores reais variam conforme o conteúdo da Skill e a forma de uso.

Sobre "tempo desperdiçado": O "tempo" no relatório refere-se ao desperdício adicional causado por falhas de design, não ao tempo total de execução da Skill. Especificamente:

• Falta de gotchas → Agente depura repetidamente (2-5 minutos cada vez)
• Restrições excessivas → Agente executa passos rígidos sem sentido (10-30 segundos por passo)
• Script ausente → Agente reescreve o mesmo código cada vez (1-3 minutos cada vez)

Lógica de comparação: Valor pré-otimização = soma desses desperdícios; pós-otimização, desperdício zerado → ~0; "Economia" = quantidade de desperdício eliminado. A execução da Skill otimizada ainda leva tempo, mas não possui essas perdas adicionais.

Apresentação das Recomendações de Otimização

Após gerar o relatório, exiba os itens otimizáveis como uma lista para o usuário, cada item contendo:

### 🔧 Itens Otimizáveis

| # | Item | Pontuação Atual | Pontuação Esperada | Ganho | Esforço | Tokens/vez | Tempo/vez | Ação |
|---|------|----------------|--------------------|-------|---------|------------|-----------|------|
| 1 | description | 50 | 90 | +40 | Baixo | ~50 | — | Reescrever como condição de acionamento |
| 2 | gotchas | 40 | 90 | +50 | Médio | — | ~3min | Adicionar armadilhas reais |
| ... | ... | ... | ... | ... | ... | ... | ... | ... |

**Após aceitar todas as otimizações**: 55(D) → 85(B), ganho de 30 pontos

### 📈 Benefícios Totais (por chamada única)
- Economia de Tokens: ~200/vez
- Economia de Tempo: ~5 minutos/vez
- Prevenção de erros: Após complementar gotchas, erros comuns são evitados

> **Critério de contagem de tempo**: O "tempo economizado" aqui refere-se ao **desperdício adicional causado por falhas de design**, não ao tempo total de execução da Skill:
> - Falta de gotchas → Agente depura repetidamente (2-5 minutos cada vez)
> - Restrições excessivas → Agente executa passos rígidos sem sentido (10-30 segundos por passo)
> - Script ausente → Agente reescreve o mesmo código cada vez (1-3 minutos cada vez)
> - Valor pré-otimização = soma dos desperdícios, pós-otimização desperdício zerado, "Economia" = quantidade de desperdício eliminado

Por favor, escolha:
- **"Aceitar Tudo"** — Otimizar todos os itens de uma vez
- **"Aceitar 1,3"** — Otimizar apenas os itens especificados
- **"Pular"** — Apenas ver o relatório sem otimizar

Execução Após Confirmação do Usuário

1. Após a escolha do usuário, modificar os arquivos correspondentes um a um
2. Marcar o status de cada item concluído
3. Após concluir todos, executar novamente a verificação de saúde para gerar um relatório comparativo

Formato do Relatório Comparativo Pré/Pós-Otimização

## 📊 Comparação Pré/Pós-Otimização

| Item de Verificação | Pré-Otimização | Pós-Otimização | Mudança |
|--------------------|----------------|----------------|---------|
| description | 50 (descrição de funcionalidade) | 90 (condição de acionamento) | +40 ⬆️ |
| gotchas | 40 (esqueleto vazio) | 90 (completo) | +50 ⬆️ |
| ... | ... | ... | ... |
| **Pontuação Total** | **55 (D)** | **85 (B)** | **+30 ⬆️** |

### 📈 Benefícios Totais (por chamada única)
| Dimensão | Pré-Otimização | Pós-Otimização | Economia |
|----------|----------------|----------------|--------|
| Tokens | ~800/vez | ~600/vez | ~200/vez |
| Desperdício de Tempo | ~5min | ~0 | ~5min |
| Arquivo Principal | 466 linhas | 75 linhas | -84% |

> O desperdício de tempo representa custos adicionais causados por falhas de design (depuração de armadilhas, passos redundantes, etc.), não o tempo total de execução da Skill. Veja [Regras de Estimativa de Benefícios](#regras-de-estimativa-de-benefícios).

### Arquivos Modificados
- `SKILL.md` — Reescrever description
- `gotchas.md` — Adicionar 5 armadilhas reais

Exemplo Completo de Interação

Veja o exemplo 9 em examples.md

Níveis de Pontuação

• A (90-100) : Excelente, segue todas as melhores práticas
• B (75-89) : Bom, com pequeno espaço para otimização
• C (60-74) : Satisfatório, com pontos de melhoria evidentes
• D (<60) : Insatisfatório, precisa ser reestruturado

Lista de Verificação Detalhada

Veja checklists.md

Armadilhas Comuns

Veja gotchas.md

Exemplos de Otimização

Veja examples.md

Script

A lógica central da verificação de saúde está encapsulada em scripts/analyze_skill.py. O Agente a invoca para obter pontuações estruturadas:

python scripts/analyze_skill.py <skill_path> --output json    # Passo 3: Obter relatório de pontuação
python scripts/analyze_skill.py <skill_path> --output markdown # Opcional: Gerar relatório legível por humanos

O script é responsável por: cálculo de pontuação, detecção de problemas, classificação de níveis (camada estável) O Agente é responsável por: geração de recomendações de otimização, interação com o usuário, execução de modificações em arquivos (camada inteligente)