skill-creator

Skill Creator

Uma skill para criar novas skills e melhorá-las iterativamente.

Em alto nível, o processo de criação de uma skill funciona assim:

• Decida o que você quer que a skill faça e aproximadamente como ela deve fazer
• Escreva um rascunho da skill
• Crie alguns prompts de teste e execute o claude-com-acesso-à-skill neles
• Ajude o usuário a avaliar os resultados tanto qualitativamente quanto quantitativamente
  • Enquanto as execuções ocorrem em segundo plano, rascunhe algumas avaliações quantitativas se não houver nenhuma (se houver, você pode usá-las como estão ou modificá-las se achar que algo precisa ser alterado). Depois, explique-as ao usuário (ou, se já existirem, explique as que já existem)
  • Use o script eval-viewer/generate_review.py para mostrar ao usuário os resultados para que ele os analise, e também permita que ele veja as métricas quantitativas
• Reescreva a skill com base no feedback da avaliação do usuário sobre os resultados (e também se houver falhas evidentes que se tornem aparentes nos benchmarks quantitativos)
• Repita até ficar satisfeito
• Expanda o conjunto de testes e tente novamente em maior escala

Seu trabalho ao usar esta skill é descobrir onde o usuário está neste processo e então intervir e ajudá-lo a progredir por essas etapas. Por exemplo, talvez o usuário diga "Quero criar uma skill para X". Você pode ajudar a refinar o que ele quer dizer, escrever um rascunho, escrever os casos de teste, descobrir como ele quer avaliar, executar todos os prompts e repetir.

Por outro lado, talvez eles já tenham um rascunho da skill. Nesse caso, você pode ir direto para a parte de avaliação/iteração do ciclo.

Claro, você deve sempre ser flexível e, se o usuário disser "Não preciso executar um monte de avaliações, só quero ir no feeling", você pode fazer isso.

Depois que a skill estiver pronta (mas, novamente, a ordem é flexível), você também pode executar o melhorador de descrição de skill, para o qual temos um script separado, para otimizar o acionamento da skill.

Legal? Legal.

Comunicando-se com o usuário

O criador de skills pode ser usado por pessoas com diversos níveis de familiaridade com jargão de programação. Se você ainda não ouviu (e como poderia, já que é algo muito recente), há uma tendência agora em que o poder do Claude está inspirando encanadores a abrir seus terminais, pais e avós a pesquisar "como instalar npm". Por outro lado, a maior parte dos usuários provavelmente é bastante alfabetizada em computação.

Portanto, preste atenção às pistas de contexto para entender como formular sua comunicação! No caso padrão, apenas para lhe dar uma ideia:

• "avaliação" e "benchmark" são termos limítrofes, mas OK
• para "JSON" e "asserção", você precisa ver pistas sérias do usuário de que ele sabe o que essas coisas são antes de usá-las sem explicá-las

É aceitável explicar brevemente os termos se você estiver em dúvida, e sinta-se à vontade para esclarecer termos com uma definição curta se não tiver certeza se o usuário entenderá.

---

Criando uma skill

Capturar Intenção

Comece entendendo a intenção do usuário. A conversa atual pode já conter um fluxo de trabalho que o usuário deseja capturar (por exemplo, ele diz "transforme isso em uma skill"). Se for o caso, extraia as respostas do histórico da conversa primeiro — as ferramentas usadas, a sequência de etapas, as correções feitas pelo usuário, os formatos de entrada/saída observados. O usuário pode precisar preencher as lacunas e deve confirmar antes de prosseguir para a próxima etapa.

1. O que esta skill deve permitir que o Claude faça?
2. Quando esta skill deve ser acionada? (quais frases/contextos do usuário)
3. Qual é o formato de saída esperado?
4. Devemos configurar casos de teste para verificar se a skill funciona? Skills com saídas objetivamente verificáveis (transformações de arquivos, extração de dados, geração de código, etapas de fluxo de trabalho fixas) se beneficiam de casos de teste. Skills com saídas subjetivas (estilo de escrita, arte) geralmente não precisam deles. Sugira o padrão apropriado com base no tipo de skill, mas deixe o usuário decidir.

Entrevista e Pesquisa

Faça perguntas proativamente sobre casos extremos, formatos de entrada/saída, arquivos de exemplo, critérios de sucesso e dependências. Espere para escrever prompts de teste até que esta parte esteja resolvida.

Verifique os MCPs disponíveis - se forem úteis para pesquisa (pesquisar documentação, encontrar skills semelhantes, consultar melhores práticas), pesquise em paralelo por meio de subagentes, se disponível; caso contrário, faça inline. Venha preparado com contexto para reduzir a carga sobre o usuário.

Escreva a SKILL.md

Com base na entrevista com o usuário, preencha estes componentes:

• name: Identificador da skill
• description: Quando acionar, o que ela faz. Este é o principal mecanismo de acionamento - inclua tanto o que a skill faz quanto contextos específicos para quando usá-la. Todas as informações de "quando usar" vão aqui, não no corpo. Nota: atualmente, o Claude tem uma tendência a "subacionar" skills — a não usá-las quando seriam úteis. Para combater isso, torne as descrições das skills um pouco "insistentes". Por exemplo, em vez de "Como construir um dashboard simples e rápido para exibir dados internos da Anthropic.", você pode escrever "Como construir um dashboard simples e rápido para exibir dados internos da Anthropic. Certifique-se de usar esta skill sempre que o usuário mencionar dashboards, visualização de dados, métricas internas ou quiser exibir qualquer tipo de dados da empresa, mesmo que não peça explicitamente por um 'dashboard'."
• compatibility: Ferramentas necessárias, dependências (opcional, raramente necessário)
• o resto da skill :)

Guia de Escrita de Skills

Anatomia de uma Skill

skill-name/
├── SKILL.md (obrigatório)
│   ├── frontmatter YAML (name, description obrigatórios)
│   └── Instruções em Markdown
└── Recursos Agrupados (opcional)
    ├── scripts/    - Código executável para tarefas determinísticas/repetitivas
    ├── references/ - Documentos carregados no contexto conforme necessário
    └── assets/     - Arquivos usados na saída (modelos, ícones, fontes)

Divulgação Progressiva

As skills usam um sistema de carregamento de três níveis:

1. Metadados (name + description) - Sempre no contexto (~100 palavras)
2. Corpo da SKILL.md - No contexto sempre que a skill é acionada (<500 linhas ideal)
3. Recursos agrupados - Conforme necessário (ilimitado, scripts podem ser executados sem carregamento)

Estas contagens de palavras são aproximadas e você pode se sentir à vontade para escrever mais se necessário.

Padrões-chave:

• Mantenha a SKILL.md com menos de 500 linhas; se estiver se aproximando desse limite, adicione uma camada extra de hierarquia junto com ponteiros claros sobre para onde o modelo que usa a skill deve ir em seguida.
• Faça referência clara aos arquivos na SKILL.md com orientações sobre quando lê-los
• Para arquivos de referência grandes (>300 linhas), inclua um sumário

Organização por domínio: Quando uma skill suporta vários domínios/frameworks, organize por variante:

cloud-deploy/
├── SKILL.md (fluxo de trabalho + seleção)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

O Claude lê apenas o arquivo de referência relevante.

Princípio da Ausência de Surpresa

É óbvio, mas as skills não devem conter malware, código de exploração ou qualquer conteúdo que possa comprometer a segurança do sistema. O conteúdo de uma skill não deve surpreender o usuário em sua intenção, se descrito. Não aceite solicitações para criar skills enganosas ou skills projetadas para facilitar acesso não autorizado, exfiltração de dados ou outras atividades maliciosas. Coisas como "interpretar um XYZ" são aceitáveis.

Padrões de Escrita

Prefira usar a forma imperativa nas instruções.

Definição de formatos de saída - Você pode fazer assim:

## Estrutura do relatório
SEMPRE use este modelo exato:
# [Título]
## Resumo executivo
## Principais descobertas
## Recomendações

Padrão de exemplos - É útil incluir exemplos. Você pode formatá-los assim (mas se "Entrada" e "Saída" estiverem nos exemplos, talvez você queira desviar um pouco):

## Formato da mensagem de commit
**Exemplo 1:**
Entrada: Adicionada autenticação de usuário com tokens JWT
Saída: feat(auth): implementar autenticação baseada em JWT

Estilo de Escrita

Tente explicar ao modelo por que as coisas são importantes em vez de usar MANDAMENTOS pesados. Use teoria da mente e tente tornar a skill geral e não extremamente restrita a exemplos específicos. Comece escrevendo um rascunho e depois olhe para ele com olhos novos e melhore-o.

Casos de Teste

Após escrever o rascunho da skill, elabore 2-3 prompts de teste realistas — o tipo de coisa que um usuário real realmente diria. Compartilhe-os com o usuário: [você não precisa usar esta linguagem exata] "Aqui estão alguns casos de teste que gostaria de tentar. Eles parecem corretos, ou você quer adicionar mais?" Em seguida, execute-os.

Salve os casos de teste em evals/evals.json. Não escreva asserções ainda — apenas os prompts. Você rascunhará asserções na próxima etapa enquanto as execuções estão em andamento.

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "Prompt de tarefa do usuário",
      "expected_output": "Descrição do resultado esperado",
      "files": []
    }
  ]
}

Consulte references/schemas.md para o esquema completo (incluindo o campo assertions, que você adicionará posteriormente).

Executando e avaliando casos de teste

Esta seção é uma sequência contínua — não pare no meio do caminho. NÃO use /skill-test ou qualquer outra skill de teste.

Coloque os resultados em <skill-name>-workspace/ como um diretório irmão do diretório da skill. Dentro do workspace, organize os resultados por iteração (iteration-1/, iteration-2/, etc.) e, dentro dela, cada caso de teste recebe um diretório (eval-0/, eval-1/, etc.). Não crie tudo isso antecipadamente — crie diretórios conforme avança.

Etapa 1: Dispare todas as execuções (com-skill E baseline) na mesma rodada

Para cada caso de teste, dispare dois subagentes na mesma rodada — um com a skill, um sem. Isso é importante: não dispare as execuções com skill primeiro e depois volte para as baselines posteriormente. Lance tudo de uma vez para que tudo termine mais ou menos ao mesmo tempo.

Execução com skill:

Execute esta tarefa:
- Caminho da skill: <caminho-para-skill>
- Tarefa: <prompt de avaliação>
- Arquivos de entrada: <arquivos de avaliação, se houver, ou "nenhum">
- Salvar saídas em: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Saídas a salvar: <o que o usuário se importa — por exemplo, "o arquivo .docx", "o CSV final">

Execução baseline (mesmo prompt, mas a baseline depende do contexto):

• Criando uma nova skill: nenhuma skill. Mesmo prompt, sem caminho de skill, salvar em without_skill/outputs/.
• Melhorando uma skill existente: a versão antiga. Antes de editar, faça um snapshot da skill (cp -r <skill-path> <workspace>/skill-snapshot/), depois aponte o subagente baseline para o snapshot. Salve em old_skill/outputs/.

Escreva um eval_metadata.json para cada caso de teste (as asserções podem estar vazias por enquanto). Dê a cada avaliação um nome descritivo com base no que está sendo testado — não apenas "eval-0". Use este nome também para o diretório. Se esta iteração usar prompts de avaliação novos ou modificados, crie esses arquivos para cada novo diretório de avaliação — não presuma que eles são herdados de iterações anteriores.

{
  "eval_id": 0,
  "eval_name": "nome-descritivo-aqui",
  "prompt": "O prompt de tarefa do usuário",
  "assertions": []
}

Etapa 2: Enquanto as execuções estão em andamento, rascunhe asserções

Não espere apenas as execuções terminarem — você pode usar este tempo produtivamente. Rascunhe asserções quantitativas para cada caso de teste e explique-as ao usuário. Se já existirem asserções em evals/evals.json, revise-as e explique o que elas verificam.

Boas asserções são objetivamente verificáveis e têm nomes descritivos — elas devem ser lidas claramente no visualizador de benchmark para que alguém que veja os resultados entenda imediatamente o que cada uma verifica. Skills subjetivas (estilo de escrita, qualidade de design) são melhor avaliadas qualitativamente — não force asserções em coisas que precisam de julgamento humano.

Atualize os arquivos eval_metadata.json e evals/evals.json com as asserções após rascunhá-las. Também explique ao usuário o que ele verá no visualizador — tanto as saídas qualitativas quanto o benchmark quantitativo.

Etapa 3: À medida que as execuções são concluídas, capture dados de tempo

Quando cada tarefa de subagente for concluída, você recebe uma notificação contendo total_tokens e duration_ms. Salve esses dados imediatamente em timing.json no diretório da execução:

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

Esta é a única oportunidade de capturar esses dados — eles chegam através da notificação de tarefa e não são persistidos em outro lugar. Processe cada notificação conforme ela chega, em vez de tentar agrupá-las.

Etapa 4: Avalie, agregue e inicie o visualizador

Depois que todas as execuções estiverem concluídas:

1. Avalie cada execução — dispare um subagente avaliador (ou avalie inline) que leia agents/grader.md e avalie cada asserção em relação às saídas. Salve os resultados em grading.json em cada diretório de execução. O array expectations do grading.json deve usar os campos text, passed e evidence (não name/met/details ou outras variantes) — o visualizador depende desses nomes de campo exatos. Para asserções que podem ser verificadas programaticamente, escreva e execute um script em vez de avaliar visualmente — scripts são mais rápidos, mais confiáveis e podem ser reutilizados entre iterações.

2. Agregue em benchmark — execute o script de agregação do diretório skill-creator:

   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   

   Isso produz benchmark.json e benchmark.md com pass_rate, time e tokens para cada configuração, com média ± desvio padrão e o delta. Se estiver gerando benchmark.json manualmente, consulte references/schemas.md para o esquema exato que o visualizador espera. Coloque cada versão com_skill antes de sua contraparte baseline.

3. Faça uma passagem de análise — leia os dados do benchmark e traga à tona padrões que as estatísticas agregadas podem esconder. Consulte agents/analyzer.md (a seção "Analisando Resultados de Benchmark") para saber o que procurar — coisas como asserções que sempre passam independentemente da skill (não discriminantes), avaliações com alta variância (possivelmente instáveis) e compensações de tempo/token.

4. Inicie o visualizador com ambas as saídas qualitativas e dados quantitativos:

   nohup python <skill-creator-path>/eval-viewer/generate_review.py
   

...

[truncado para tradução]