Modificado para DeepSeek Harness. Original: Anthropic's skill-creator (Apache-2.0, veja LICENSE.txt).
O que Criador de Habilidades faz?
Uma habilidade para criar novas habilidades e melhorá-las iterativamente.
Em um nível alto, o processo de criação de uma habilidade funciona assim:
- Decida o que você quer que a habilidade faça e aproximadamente como ela deve fazer
- Escreva um rascunho da habilidade
- Crie alguns prompts de teste e execute o modelo com eles com a habilidade instalada
- Ajude o usuário a avaliar os resultados tanto qualitativa 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 mudar). Em seguida, explique-as ao usuário (ou se já existiam, explique as que já existem)
- Use o script
eval-viewer/generate_review.pypara mostrar ao usuário os resultados para que ele possa examiná-los, 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 nos 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á neste processo e então intervir e ajudá-lo a progredir por essas etapas. Por exemplo, talvez eles estejam tipo "Quero criar uma habilidade para X". Você pode ajudar a definir o que eles querem dizer, escrever um rascunho, escrever os casos de teste, descobrir como eles querem avaliar, executar todos os prompts e repetir.
Por outro lado, talvez eles já tenham um rascunho da habilidade. Neste 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, apenas me oriente", 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 da habilidade, para o qual temos um script separado, para otimizar o acionamento da habilidade.
Legal? Legal.
Comunicando-se com o usuário
O criador de habilidades pode ser usado por pessoas com uma ampla gama de familiaridade com jargão de programação. Se você não ouviu (e como poderia, já que é algo muito recente), há uma tendência agora em que o poder do DSH está inspirando encanadores a abrir seus terminais, pais e avós a pesquisar no Google "como instalar o npm". Por outro lado, a maioria dos usuários provavelmente é razoavelmente experiente em computação.
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" são termos limítrofes, mas OK
- para "JSON" e "asserção", você precisa ver sinais sérios do usuário de que ele sabe o que são esses termos antes de usá-los sem explicá-los
Tudo bem explicar brevemente os termos se você estiver em dúvida, e sinta-se à vontade para esclarecer termos com uma breve definição se não tiver certeza se o usuário entenderá.
Criando uma habilidade
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, eles dizem "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 DSH 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 de fluxo de trabalho fixas) 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 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ível, caso contrário, em linha. Venha preparado com contexto para reduzir a carga sobre o usuário.
Escrever o SKILL.md
Com base na entrevista com o usuário, preencha estes componentes:
- nome: Identificador da habilidade
- descrição: Quando acionar, o que faz. Este é o mecanismo de acionamento primário - inclua tanto o que a habilidade 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 modelo tende a "subacionar" habilidades — 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 painel rápido e simples para exibir dados internos da empresa.", você pode escrever "Como construir um painel rápido e simples para exibir dados internos da empresa. Certifique-se de usar esta habilidade sempre que o usuário mencionar painéis, visualização de dados, métricas internas ou quiser exibir qualquer tipo de dado da empresa, mesmo que não peça explicitamente um 'painel'."
- quandoUsar / metadados / desabilitar-invocacao-do-modelo / invocavel-pelo-usuario: as chaves opcionais de frontmatter que o DSH reconhece. O DSH lê
nome,descrição,quandoUsar,metadados,desabilitar-invocacao-do-modeloeinvocavel-pelo-usuariodo frontmatter; coloque qualquer outra coisa que você queira registrar (uma licença, uma versão) emmetadadosem vez de como uma chave de nível superior. - o resto da habilidade :)
Guia de Escrita de Habilidades
Anatomia de uma Habilidade
skill-name/
├── SKILL.md (obrigatório)
│ ├── Frontmatter YAML (nome, descrição 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 em contexto (~100 palavras)
- Corpo do SKILL.md - Em contexto sempre que a habilidade aciona (<500 linhas ideal)
- Recursos empacotados - Conforme necessário (ilimitado, scripts podem ser executados sem carregar)
Essas contagens de palavras são aproximadas e você pode ficar à vontade para ir mais longe se necessário.
Padrões principais:
- Mantenha o SKILL.md abaixo de 500 linhas; se estiver se aproximando deste limite, adicione uma camada adicional de hierarquia junto com ponteiros claros sobre para onde o modelo que usa a habilidade deve ir a seguir para acompanhar.
- Faça referência a arquivos claramente no SKILL.md com orientação sobre quando lê-los
- Para arquivos de referência grandes (>300 linhas), inclua um índice
Organização de domínio: Quando uma habilidade 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 DSH 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 for descrito. Não aceite solicitações para criar habilidades enganosas ou habilidades 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, você pode querer 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 MUSTs pesados e imperativos. Use a teoria da mente e tente tornar a habilidade geral e não super-estreita a exemplos específicos. Comece escrevendo um rascunho e depois olhe para ele com novos olhos e melhore-o.
Casos de Teste
Depois de escrever o rascunho da habilidade, crie 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ê redigirá as asserções na próxima etapa enquanto as execuções estão em andamento.
{
"skill_name": "exemplo-habilidade",
"evals": [
{
"id": 1,
"prompt": "Prompt da 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á depois).
Executando e avaliando casos de teste
Esta seção é uma sequência contínua — não pare no meio. NÃO use /skill-test ou qualquer outra habilidade de teste.
Coloque os resultados em <skill-name>-workspace/ como um irmão do diretório da habilidade. Dentro do espaço de trabalho, 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 antecipadamente — apenas crie diretórios conforme avança.
Passo 1: Inicie todas as execuções (COM habilidade E linha de base) no mesmo turno
Para cada caso de teste, inicie dois subagentes no mesmo turno — um com a habilidade, um sem. Isso é importante: não inicie as execuções com habilidade primeiro e depois volte para as linhas de base. Lance tudo de uma vez para que termine mais ou menos 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>/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 habilidade: nenhuma habilidade. Mesmo prompt, sem caminho de habilidade, salvar em
without_skill/outputs/. - Melhorando uma habilidade existente: a versão antiga. Antes de editar, tire um instantâneo da habilidade copiando o diretório com
shutil.copytree(por exemplo<workspace>/skill-snapshot/de<skill-path>), em seguida, aponte o subagente de linha de base para o instantâneo. Salve emold_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 usa prompts de avaliação novos ou modificados, crie estes arquivos para cada novo diretório de avaliação — não presuma que eles são transportados de iterações anteriores.
{
"eval_id": 0,
"eval_name": "nome-descritivo-aqui",
"prompt": "O prompt da tarefa do usuário",
"assertions": []
}
Passo 2: Enquanto as execuções estão em andamento, redija as asserções
Não espere apenas as execuções terminarem — você pode usar este tempo produtivamente. Redija asserções quantitativas para cada caso de teste e explique-as ao usuário. Se as asserções já existirem 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. Habilidades 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 depois de redigidas. Explique também ao usuário o que ele verá no visualizador — tanto as saídas qualitativas quanto o benchmark quantitativo.
Passo 3: Conforme as execuções são concluídas, capture os dados de tempo
Quando cada tarefa de subagente é concluída, você recebe uma notificação, mas ela não carrega nem contagens de tokens nem tempo decorrido. Obtenha a duração do relógio de parede você mesmo e leia os totais de tokens do registro da sessão filha em ~/.dsh/storages/session_projcache/sessions/<childId>.json (tokenUsage.val.totals — uncachedInputTokens, outputTokens, cacheReadTokens, cacheWriteTokens). Salve estes dados imediatamente em timing.json no diretório da execução:
{
"total_tokens": 84852,
"duration_ms": 23332,
"total_duration_seconds": 23.3
}
Se esse registro de sessão estiver ausente ou não tiver uso de tokens, deixe os campos de token de fora em vez de inventar números. Processe cada notificação à medida que chega, em vez de tentar agrupá-las.
Passo 4: Avalie, agregue e inicie o visualizador
Depois que todas as execuções forem concluídas:
-
Avalie cada execução — inicie um subagente avaliador (ou avalie em linha) que leia
agents/grader.mde avalie cada asserção em relação às saídas. Salve os resultados emgrading.jsonno diretório de cada execução. A matriz de expectativas do grading.json deve usar os campostext,passedeevidence(nãoname/met/detailsou 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 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 dsh-skill-creator:
python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <nome>Isso produz
benchmark.jsonebenchmark.mdcom taxa de aprovação, tempo e tokens para cada execução, além de um resumo. Inclua o nome da habilidade para que o visualizador possa processar os resultados. -
Inicie o visualizador — execute o script de visualização subjacente a partir do diretório dsh-skill-creator:
python eval-viewer/generate_review.py <workspace> <caminho-dos-arquivos-de-resultado>(Os resultados geralmente estão em
<workspace>/iteration-<N>, a menos que você tenha mudado a estrutura.) Isso gera um arquivo de resumo interativo que você pode mostrar ao usuário.
Melhorando a descrição da habilidade
Depois que a habilidade estiver pronta, você pode executar o melhorador de descrição para otimizar o acionamento. Isso está em scripts/optimize_description.py no diretório dsh-skill-creator:
python -m scripts.optimize_description <caminho-para-habilidade> --prompt "Descreva o que você quer melhorar"
O script analisará a descrição atual e sugerirá melhorias para torná-la mais acionável e específica. Você pode executá-lo várias vezes para refinar a descrição.
Observações finais
Lembre-se: o Criador de Habilidades é uma ferramenta para tornar o processo de criação de habilidades mais eficiente e robusto. Ele não substitui o julgamento humano — ele o amplifica. Use-o com sabedoria e divirta-se criando!