skill-forge-eval

Pipeline de Avaliação de Skills

Execute avaliações estruturadas em skills do Claude Code para verificar acionamento, corretude e qualidade usando um pipeline multiagente.

Processo

Passo 1: Definir Conjunto de Avaliação

Aceitar definições de avaliação de:

• Caminho para JSON do conjunto de avaliação: evals/evals.json ou arquivo especificado pelo usuário
• Prompts inline: O usuário fornece consultas de avaliação diretamente
• Gerado automaticamente: Gerar a partir da descrição da skill (veja Passo 1b)

Esquema JSON do conjunto de avaliação:

{
  "skill_name": "my-skill",
  "skill_path": "./my-skill",
  "evals": [
    {
      "eval_id": 0,
      "eval_name": "descriptive-name",
      "prompt": "The user's task prompt",
      "input_files": [],
      "assertions": [
        {
          "name": "output-has-score",
          "check": "Output contains a numeric score between 0-100",
          "weight": 1.0
        }
      ],
      "should_trigger": true
    }
  ]
}

Passo 1b: Gerar Conjunto de Avaliação Automaticamente

Se nenhum conjunto de avaliação existir, gere um:

1. Leia a descrição e as instruções do SKILL.md da skill
2. Execute python scripts/generate_eval_set.py <skill-path> para produzir um conjunto inicial
3. Apresente o conjunto gerado ao usuário para revisão e edição
4. O usuário aprova ou modifica antes de prosseguir

Passo 2: Configurar Workspace

Crie o workspace de avaliação fora do diretório da skill para evitar confundir artefatos de avaliação com arquivos da skill. Use um diretório irmão ou um local dedicado:

eval-workspace/
  iteration-1/
    eval-0/
      eval_metadata.json        # Asserções e configuração para esta avaliação
      with_skill/
        outputs/                # Saídas da execução da skill
        timing.json             # Contagem de tokens + duração
        grading.json            # Resultados das asserções + evidências
      baseline/
        outputs/
        timing.json
        grading.json
    eval-1/
      eval_metadata.json
      with_skill/
        outputs/
        timing.json
        grading.json
      baseline/
        outputs/
        timing.json
        grading.json
    benchmark.json              # Métricas agregadas
    benchmark.md                # Relatório legível para humanos

Para cada diretório de avaliação, crie eval_metadata.json a partir da entrada do conjunto de avaliação:

{
  "eval_id": 0,
  "eval_name": "descriptive-name",
  "prompt": "The user's task prompt",
  "assertions": [...],
  "should_trigger": true
}

Passo 3: Executar as Execuções de Avaliação

Para cada avaliação no conjunto, inicie duas execuções paralelas:

Execução com skill (delegar a agents/skill-forge-executor.md):

Execute esta tarefa:
- Caminho da skill: <path-to-skill>
- Tarefa: <eval prompt>
- Arquivos de entrada: <eval files if any, or "none">
- Salvar saídas em: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Saídas a salvar: <what the assertions check>

Execução de baseline (delegar a agents/skill-forge-executor.md):

• Para novas skills: execute sem a skill carregada
• Para skills melhoradas: execute com a versão anterior (primeiro, tire um snapshot)

Salve os dados de tempo em timing.json em cada diretório de execução:

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

Passo 4: Avaliar Resultados

Delegue a agents/skill-forge-grader.md para cada execução concluída:

1. Avalie em relação às asserções definidas em eval_metadata.json
2. Salve os resultados em grading.json por execução:

{
  "eval_id": 0,
  "run_type": "with_skill",
  "assertions": [
    {
      "name": "output-has-score",
      "passed": true,
      "evidence": "Found score: 87/100 on line 14"
    }
  ],
  "pass_rate": 1.0
}

Passo 5: Agregar e Analisar

1. Execute python scripts/aggregate_benchmark.py <workspace>/iteration-<N> --skill-name <name>

2. Isso produz benchmark.json e benchmark.md com:

   • Taxa de aprovação por avaliação (com skill vs baseline)
   • Tempo médio e uso de tokens
   • Taxa de melhoria (com skill / baseline)

3. Delegue a agents/skill-forge-analyzer.md para:

   • Revelar padrões que as estatísticas agregadas podem esconder
   • Identificar tipos de asserção que falham consistentemente
   • Sinalizar regressões de iterações anteriores

Passo 6: Apresentar Resultados

Gere um relatório de resumo:

# Relatório de Avaliação: [skill-name] — Iteração [N]

## Geral
| Métrica | Com Skill | Baseline | Delta |
|---------|-----------|----------|-------|
| Taxa de Aprovação | X% | Y% | +Z% |
| Tempo Médio | Xs | Ys | -Zs |
| Tokens Médios | X | Y | -Z |

## Resultados por Avaliação
| Avaliação | Com Skill | Baseline | Status |
|-----------|-----------|----------|--------|
| eval-0 | PASS | FAIL | Melhorou |
| eval-1 | PASS | PASS | Mantido |

## Padrões e Insights
[Do agente analisador]

## Recomendações
[Melhorias específicas com base nas falhas]

Passo 7: Coletar Feedback

Salve o feedback do usuário em feedback.json:

{
  "reviews": [
    {
      "run_id": "eval-0-with_skill",
      "feedback": "the chart is missing axis labels",
      "timestamp": "2026-03-06T12:00:00Z"
    }
  ],
  "status": "complete"
}

Passe o feedback para /skill-forge evolve para a próxima iteração.

Avançado: Comparação Cega

Para testes A/B rigorosos entre versões de skill:

1. Delegue a agents/skill-forge-comparator.md
2. Passe dois diretórios: eval-<ID>/with_skill/outputs/ e eval-<ID>/baseline/outputs/
3. O comparador atribui rótulos aleatórios (Versão A / Versão B) para que não saiba qual é a nova
4. Avalia cada saída com base nos critérios de asserção de eval_metadata.json
5. Retorna pontuações de preferência sem saber qual é "nova" vs "antiga"

Tratamento de Erros

• Timeout do executor: Se uma execução exceder 5 minutos, encerre-a e marque como "timed_out": true em timing.json
• Falha do executor: Se uma execução travar, salve o erro em error.txt no diretório da execução e continue com as avaliações restantes
• Falha de avaliação: Se a avaliação não puder determinar aprovação/reprovação, marque a asserção como "passed": null com evidências explicando o porquê
• Arquivos ausentes: Se timing.json ou grading.json estiver faltando após uma execução, sinalize a avaliação como incompleta no relatório
• Conclusão parcial: Sempre agregue e relate quaisquer resultados disponíveis — não bloqueie em uma avaliação com falha

Portões de Qualidade

Antes de marcar uma execução de avaliação como concluída:

• Todas as avaliações executadas (com skill + baseline)
• Dados de tempo capturados para cada execução
• Todas as asserções avaliadas com evidências
• Benchmark agregado com taxa de aprovação, tempo, tokens
• Padrões do analisador documentados
• Resultados apresentados ao usuário