O que Skill Creator faz?

Uma habilidade para criar novas habilidades e aprimorá-las iterativamente.

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

Decida o que você quer que a habilidade faça e como ela deve fazer
Escreva um rascunho da habilidade
Crie alguns prompts de teste e execute o claude-com-acesso-à-habilidade neles
Ajude o usuário a avaliar os resultados tanto qualitativa 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 ao usuário os resultados para que ele os analise, e também permita que ele veja as métricas quantitativas
Reescreva a habilidade com base no feedback da avaliação do usuário sobre os resultados (e também se houver falhas evidentes que se tornem aparentes a partir dos benchmarks quantitativos)
Repita até ficar satisfeito
Expanda o conjunto de testes e tente novamente em maior escala

Seu trabalho ao usar esta habilidade é descobrir onde o usuário está nesse processo e, em seguida, intervir e ajudá-lo a progredir por esses estágios. Por exemplo, talvez o usuário diga "Quero fazer uma habilidade para X". Você pode ajudar a restringir 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 habilidade. Nesse caso, você pode ir diretamente para a parte de avaliação/iteração do ciclo.

É claro que você deve sempre ser flexível: se o usuário disser "Não preciso executar um monte de avaliações, apenas me guie", você pode fazer isso.

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

Legal? Legal.

Comunicação com o usuário

O criador de habilidades tende a ser usado por pessoas com níveis muito variados de familiaridade com jargões de programação. Se você ainda não ouviu (e como poderia, já que isso começou muito recentemente), 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 maioria dos usuários provavelmente tem uma boa familiaridade com computadores.

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

"avaliação" e "benchmark" são termos no limite, mas OK
para "JSON" e "assertiva", você precisa ver sinais claros do usuário de que ele sabe o que essas coisas são antes de usá-los sem explicar

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

Criando uma habilidade

Capturar a 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 habilidade"). Nesse caso, extraia as respostas do histórico da conversa primeiro — as ferramentas usadas, a sequência de etapas, as correções que o usuário fez, 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.

O que esta habilidade deve permitir que o Claude faça?
Quando esta habilidade deve ser acionada? (quais frases/contextos do usuário)
Qual é o formato de saída esperado?
Devemos configurar casos de teste para verificar se a habilidade funciona? Habilidades com saídas objetivamente verificáveis (transformações de arquivos, extração de dados, geração de código, etapas fixas de fluxo de trabalho) se beneficiam de casos de teste. Habilidades com saídas subjetivas (estilo de escrita, arte) geralmente não precisam deles. Sugira o padrão apropriado com base no tipo de habilidade, 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 os prompts de teste até que esta parte esteja resolvida.

Verifique os MCPs disponíveis — se forem úteis para pesquisa (pesquisar documentação, encontrar habilidades 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 habilidade
description: Quando acionar, o que ela faz. Este é o principal mecanismo de acionamento — inclua tanto o que a habilidade faz quanto contextos específicos para usá-la. Todas as informações "quando usar" vão aqui, não no corpo. Nota: atualmente, Claude tem uma tendência a "subacionar" habilidades — a não usá-las quando seriam úteis. Para combater isso, torne as descrições das habilidades um pouco "insistentes". Por exemplo, em vez de "Como construir um dashboard rápido e simples para exibir dados internos da Anthropic.", você pode escrever "Como construir um dashboard rápido e simples para exibir dados internos da Anthropic. Certifique-se de usar esta habilidade 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 habilidade :)

Guia de Escrita de Habilidades

Anatomia de uma Habilidade

nome-da-habilidade/
├── 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 habilidades usam um sistema de carregamento de três níveis:

Metadados (nome + descrição) - Sempre no contexto (~100 palavras)
Corpo do SKILL.md - No contexto sempre que a habilidade é acionada (<500 linhas ideal)
Recursos empacotados - Conforme necessário (ilimitado, scripts podem executar sem carregar)

Essas contagens de palavras são aproximadas e você pode ficar à vontade para ser mais longo, 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 junto com indicadores claros sobre para onde o modelo que usa a habilidade deve ir em seguida para acompanhar.
Faça referência a arquivos claramente no 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 habilidade suporta vários domínios/frameworks, organize por variante:

implantacao-nuvem/
├── 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

Isso é óbvio, mas as habilidades 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 habilidade não deve surpreender o usuário em sua intenção, se descrito. Não atenda a solicitações para criar habilidades enganosas ou projetadas para facilitar acesso não autorizado, exfiltração de dados ou outras atividades maliciosas. Coisas como "interpretar um XYZ" são OK.

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 imposições pesadas e MANDATÓRIAS. Use a teoria da mente e tente tornar a habilidade 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 habilidade, crie 2 a 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 exatamente esta linguagem] "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. Ainda não escreva assertivas — apenas os prompts. Você redigirá as assertivas na próxima etapa, enquanto as execuções estão em andamento.

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

Consulte references/schemas.md para obter 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 habilidade de teste.

Coloque os resultados em <nome-da-habilidade>-workspace/ como um irmão do diretório da habilidade. 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 — apenas crie os diretórios conforme for avançando.

Etapa 1: Iniciar todas as execuções (com-habilidade E linha de base) na mesma rodada

Para cada caso de teste, inicie dois subagentes na mesma rodada — um com a habilidade e outro sem. Isso é importante: não inicie as execuções com habilidade primeiro e depois volte para as linhas de base posteriormente. Lance tudo de uma vez para que tudo termine aproximadamente ao mesmo tempo.

Execução com habilidade:

Execute esta tarefa:
- Caminho da habilidade: <caminho-para-habilidade>
- Tarefa: <prompt de avaliação>
- Arquivos de entrada: <arquivos de avaliação, se houver, ou "nenhum">
- Salvar saídas em: <workspace>/iteração-<N>/eval-<ID>/com_habilidade/saidas/
- 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 habilidade: nenhuma habilidade. Mesmo prompt, sem caminho de habilidade, salvar em sem_habilidade/saidas/.
Aprimorando uma habilidade existente: a versão antiga. Antes de editar, tire um snapshot da habilidade (cp -r <caminho-habilidade> <workspace>/snapshot-habilidade/), então aponte o subagente da linha de base para o snapshot. Salve em habilidade_antiga/saidas/.

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

Não espere apenas as execuções terminarem — você pode usar esse tempo de forma produtiva. Elabore assertivas quantitativas para cada caso de teste e explique-as ao usuário. Se 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, de modo que alguém que veja os resultados entenda imediatamente o que cada uma verifica. Habilidades subjetivas (estilo de escrita, qualidade de design) são melhor avaliadas qualitativamente — não force assertivas em coisas que exigem julgamento humano.

Atualize os arquivos eval_metadata.json e evals/evals.json com as assertivas assim que forem elaboradas. Explique também 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 os dados de temporização

Quando cada tarefa de 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 chegar, em vez de tentar agrupá-las.

Etapa 4: Avaliar, agregar e iniciar o visualizador

Quando todas as execuções estiverem concluídas:

Avalie 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.
Agregue em benchmark — execute o script de agregação do diretório do criador de habilidades:
```
python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <nome>
```
Isso produz benchmark.json e benchmark.md com 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 esquema exato que o visualizador espera. Coloque cada versão com habilidade antes de sua contraparte de linha de base.
Faça uma passagem analítica — leia os dados do benchmark e identifique padrões que as estatísticas agregadas podem ocultar. Consulte a seção "Analyzing Benchmark Results" em agents/analyzer.md para saber o que procurar — como assertivas que sempre são aprovadas independentemente da habilidade (não discriminadoras), avaliações de alta variância (possivelmente instáveis) e trade-offs de tempo/token.

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

nohup python <caminho-do-criador-de-habilidades>/eval-viewer/generate_review.py

Skill Creator

O que é Skill Creator?

Perguntar na sua IA favorita

Documentação