add-skill
Constrói uma habilidade de qualidade de produção em skills/<nome>/, com avaliação em primeiro lugar, no repositório em que você está atualmente. Leia references/skill-authoring.md e references/evals.md uma vez por sessão antes de começar – eles são o conjunto de regras que este workflow impõe (repositórios gerados por create-skill-repo também os trazem em docs/). Se invocado como /add-skill <args>, trate $ARGUMENTS como o nome ou ideia da habilidade para definir o escopo na etapa 1.
Quando NÃO usar
- Criar um repositório de novas habilidades →
create-skill-repo. - Transformar um pacote de pesquisa em uma ou mais habilidades →
skill-from-research(ele conduz este workflow por habilidade após destilar o pacote). - Trabalho de infraestrutura (hooks, CI, validadores) → edição simples, revisão em nível de PR.
- Uma "habilidade" que meramente reafirma o que o modelo já faz bem → não a construa; uma habilidade deve corrigir uma falha específica e observável.
Workflow
- Escopo. Declare em uma frase o que a habilidade faz e a falha concreta que ela corrige. Se a frase precisar de "e", divida em múltiplas habilidades, uma de cada vez. Verifique o catálogo de habilidades existente no repositório para sobreposição – descrições de vizinhos próximos roubam os gatilhos umas das outras; planeje uma redação disjunta.
- Coleta. Leia o
.local/do repositório recursivamente, se presente (pesquisa, exemplos, restrições – nunca cite caminhos de.local/em uma habilidade). Pesquise além dele: buscas na web por fatos atuais, documentação oficial e trabalhos relacionados; verifique qualquer coisa estrutural contra fontes primárias. Fatos verificados dos quais a habilidade depende vão paraskills/<nome>/references/como arquivos limpos e commitados. - Avaliações primeiro. Crie
skills/<nome>/evals/evals.jsonconformereferences/evals.md: ≥8should_trigger(varie formalidade, erros de digitação, concisão), ≥8should_not_trigger(quase-acertos compartilhando palavras-chave), 3–5 casos dequalitycom asserçõesexpected_behaviorem linguagem natural. Se você não conseguir escrever estes, o escopo não está claro – volte para a etapa 1. - Rascunho do SKILL.md. Frontmatter:
name== nome da pasta;descriptionem uma única linha, terceira pessoa,[o que] + [use quando …] + [não para …], 150–400 caracteres, palavras-chave de gatilho nos primeiros ~120. Corpo conformereferences/skill-authoring.md: propósito → quando/quando-não → workflow numerado → especificação de saída → pegadinhas → ponteiros. Abaixo de 500 linhas; etapas determinísticas comoscripts/(saída não-zero em falha); material longo comoreferences/com um sumário. Faça referência a arquivos empacotados via${CLAUDE_SKILL_DIR}para que cópias instaladas funcionem. - Valide. Se o repositório tiver um validador (
make check/scripts/validate_skills.py), ele deve sair com 0 – corrija todos os erros, trie todos os avisos. Se não tiver nenhum, faça uma auto-verificação contra as regras de frontmatter na referência de autoria (descrição em linha única, nome==pasta, limites de comprimento). - Auto-teste do gatilho. Para ≥3 prompts that should-trigger e ≥2 should-not-trigger, raciocine explicitamente: a descrição sozinha encaminharia este prompt para cá contra todas as outras habilidades instaladas? Corrija a descrição, não as avaliações.
- Registre. Atualize o catálogo README do repositório,
CHANGELOG.mde agrupamentosskills.sh.jsonquando existirem. Re-verifique as descrições dos skills irmãos para nova sobreposição.
Especificação de saída (Definição de Pronto)
skills/<nome>/com SKILL.md + evals/evals.json (+ scripts/references conforme necessário)- Validador do repositório verde (ou a auto-verificação documentada quando não houver validador)
- Catálogo/CHANGELOG/agrupamentos atualizados onde presente
- Um resumo de 3 linhas: propósito, exemplos de frases de gatilho, limitações conhecidas
Pegadinhas
- Mantenha
descriptionem UMA única linha física – valores multilinha falharam ao carregar em alguns runtimes; nunca contorne o validador de um repositório. - Não cole prompts de avaliação com falha literalmente na descrição (sobreajuste); generalize o verbo/substantivo ausente.
- Correção de super-disparo = adicione frases nominais direcionadas "Não para …" da sobreposição real de falsos positivos; não remova gatilhos positivos.
- Atualizações de modelo mudam o roteamento – note que as avaliações devem ser re-executadas após o próximo lançamento de modelo.
Arquivos
references/skill-authoring.md— anatomia, regras de frontmatter, fórmula da descrição, estrutura do corpo, pegadinhas, anti-padrões.references/evals.md— formato do evals.json e o protocolo de gatilho/qualidade.