skill-creator

Skill Creator

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

Em um nível alto, 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, elabore 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 mudar). Em seguida, explique-as ao usuário (ou, se já existirem, explique as que já existem)
  • Use o script eval-viewer/generate_review.py para mostrar os resultados ao usuário para que ele os examine 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 gritantes que se tornem aparentes a partir dos benchmarks quantitativos)
• Repita até ficar satisfeito
• Expanda o conjunto de testes e tente novamente em uma escala maior

Seu trabalho ao usar esta skill é descobrir em que ponto do processo o usuário está e, em seguida, intervir e ajudá-lo a progredir por essas etapas. Por exemplo, talvez o usuário diga "Quero fazer uma skill para X". Você pode ajudar a definir 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 o usuário já tenha um rascunho da skill. Nesse caso, você pode ir direto para a parte de avaliação/iteração do ciclo.

Claro, você deve ser sempre flexível e, se o usuário disser "Não preciso executar um monte de avaliações, apenas sinta o fluxo comigo", 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 uma ampla gama de familiaridade com jargões 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 o npm". Por outro lado, a maioria dos usuários provavelmente tem um conhecimento razoável de computadores.

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

• "avaliação" e "benchmark" estão no limite, mas são aceitáveis
• para "JSON" e "assertiva", você deve ver sinais sérios do usuário de que ele sabe o que essas coisas são antes de usá-las sem explicá-las

Não há problema em explicar brevemente os termos se você estiver em dúvida, e sinta-se à vontade para esclarecer os termos com uma definição curta se não tiver certeza se o usuário vai 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"). Nesse caso, extraia as respostas do histórico da conversa primeiro — as ferramentas usadas, a sequência de etapas, correções que o usuário fez, 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íveis, caso contrário, faça inline. Venha preparado com contexto para reduzir a carga sobre o usuário.

Escreva o 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 a tendência de "subacionar" skills — de 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 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

nome-da-skill/
├── SKILL.md (obrigatório)
│   ├── Frontmatter YAML (name, description obrigatórios)
│   └── Instruções em Markdown
└── Recursos Empacotados (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 do SKILL.md - No contexto sempre que a skill é acionada (<500 linhas ideal)
3. Recursos empacotados - Conforme necessário (ilimitado, scripts podem ser executados sem carregamento)

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

Padrões principais:

• Mantenha o SKILL.md com menos de 500 linhas; se estiver se aproximando desse limite, adicione uma camada adicional de hierarquia com ponteiros claros sobre para onde o modelo que usa a skill deve ir em seguida para acompanhar.
• Faça referência a arquivos claramente a partir do SKILL.md com orientações sobre quando lê-los
• Para arquivos de referência grandes (>300 linhas), inclua um índice

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

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

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

Princípio da Ausência de Surpresa

Escusado será dizer, 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.

Definindo 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 MUsTUs pesados e imperativos. Use a teoria da mente e tente tornar a skill geral e não muito restrita a exemplos específicos. Comece escrevendo um rascunho e, em seguida, olhe para ele com novos olhos e melhore-o.

Casos de Teste

Depois de escrever o rascunho da skill, crie de 2 a 3 prompts de teste realistas — o tipo de coisa que um usuário real 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 experimentar. Eles parecem corretos ou você quer adicionar mais?" Em seguida, execute-os.

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

{
  "skill_name": "exemplo-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 schema completo (incluindo o campo assertions, que você adicionará mais tarde).

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 <nome-da-skill>-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 disso, cada caso de teste recebe um diretório (eval-0/, eval-1/, etc.). Não crie tudo isso de antemão — apenas crie os diretórios conforme avança.

Etapa 1: Iniciar todas as execuções (com-skill E linha de base) no mesmo turno

Para cada caso de teste, inicie dois subagentes no mesmo turno — um com a skill, um sem. Isso é importante: não inicie as execuções com-skill primeiro e depois volte para as linhas de base mais tarde. 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-a-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 de linha de base (mesmo prompt, mas a linha de base 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, tire um snapshot da skill (cp -r <caminho-da-skill> <workspace>/skill-snapshot/), em seguida, aponte o subagente de linha de base para o snapshot. Salve em old_skill/outputs/.

Escreva um eval_metadata.json para cada caso de teste (as assertivas 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, crie assertivas

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

Boas assertivas 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 do design) são melhor avaliadas qualitativamente — não force assertivas em coisas que precisam de julgamento humano.

Atualize os arquivos eval_metadata.json e evals/evals.json com as assertivas assim que forem criadas. 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 do subagente for concluída, você receberá 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 por meio da notificação de tarefa e não são persistidos em outro lugar. Processe cada notificação à medida que chega, em vez de tentar agrupar.

Etapa 4: Avaliar, agregar e iniciar o visualizador

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

1. Avaliar cada execução — inicie um subagente avaliador (ou avalie inline) que leia agents/grader.md e avalie cada assertiva 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 assertivas que podem ser verificadas programaticamente, escreva e execute um script em vez de inspecionar manualmente — scripts são mais rápidos, mais confiáveis e podem ser reutilizados entre iterações.

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

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

   Isso produz benchmark.json e benchmark.md com a taxa de aprovação, tempo 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 schema exato que o visualizador espera. Coloque cada versão com_skill antes de sua contraparte de linha de base.

3. Fazer uma passagem de análise — leia os dados do benchmark e identifique padrões que as estatísticas agregadas podem ocultar. Consulte agents/analyzer.md (a seção "Analisando Resultados de Benchmark") para saber o que procurar — coisas como assertivas que sempre passam independentemente da skill (não discriminatórias), avaliações de alta variância (possivelmente instáveis) e trade-offs de tempo/token.

4. Iniciar o visualizador com as saídas qualitativas e os dados quantitativos:

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

…

[truncado para tradução]