Convenções de Nomenclatura e Padrões de Metadados para Habilidades Descobertaveis
Uma única Habilidade pode se safar com um nome improvisado. Uma biblioteca de trinta Habilidades não pode.
Padrões de nomenclatura e metadados importam menos para como qualquer Habilidade é acionada - esse é o trabalho do campo description - e mais para como uma equipe inteira mantém sua biblioteca de Habilidades organizada, escaneável e livre de duplicatas próximas à medida que cresce.
Esta página reúne os padrões que mantêm uma biblioteca de Habilidades legível: para Claude e para as pessoas que a constroem e mantêm. Esta é uma lista de propósito geral de hábitos de nomenclatura e metadados, em vez de um único checklist fixo - nem todo item se aplicará à configuração de cada equipe.
Como Usar Esta Lista
- Aplique esses padrões ao nomear novas Habilidades, não como uma auditoria única de uma biblioteca existente (embora seja um checklist de auditoria razoável também).
- Trate os itens de nomenclatura como quase obrigatórios e os itens organizacionais como decisões que escalam com o tamanho da biblioteca.
- Revisite esta página sempre que o número de Habilidades de uma equipe crescer além do que cabe confortavelmente em uma listagem de pasta.
Nomeando a Habilidade em Si
- Use kebab-case de verbo-substantivo para o campo
name.format-release-notes,summarize-support-transcript,apply-style-guidesão lidos claramente de relance e descrevem uma ação, não uma categoria vaga. - Faça o nome da pasta corresponder exatamente ao campo
name. Uma Habilidade chamadapr-review-checklistdeve viver em uma pasta chamadapr-review-checklist/, nãopr-review/ouchecklist/- incompatibilidades tornam uma biblioteca mais difícil de escanear e pesquisar. - Evite substantivos genéricos como nome completo.
helper,assistant,utilityetoolnão descrevem nada sobre o que a Habilidade realmente faz, e colidem facilmente assim que uma segunda Habilidade "helper" aparece. - Nomeie o resultado, não o processo, quando os dois divergirem. Uma Habilidade que lê notas de reunião e produz uma atualização de status é melhor nomeada
draft-status-updatedo queprocess-meeting-notes- o resultado é geralmente o que um colega de equipe se lembra de querer. - Mantenha os nomes curtos o suficiente para serem escaneados em uma listagem de pasta. Um nome como
summarize-and-format-and-tag-support-conversations-for-reviewé preciso, mas ilegível; corte para a ação e objeto essenciais.
Escrevendo o Campo description
- Trate a descrição como o principal sinal de descoberta, não o nome. O nome ajuda um humano a escanear uma pasta; a
descriptioné o que Claude realmente corresponde a uma tarefa. Veja Escrevendo uma Descrição de Habilidade Eficaz que Claude Acionará para o padrão completo. - Declare a saída concreta na primeira frase. "Resume um transcrito de suporte ao cliente em um ticket estruturado" é melhor do que "ajuda com suporte", tanto para um humano que escaneia descrições quanto para corresponder a solicitações reais.
- Inclua uma cláusula "Use quando..." nomeando a linguagem de gatilho real. Esta é a frase de maior alavancagem em todo o arquivo para manter a Habilidade descoberta.
- Mantenha a descrição livre de detalhes de implementação interna. Nomes de ferramentas, nomes de arquivos e contagens de etapas internas pertencem ao corpo das instruções, não à descrição - eles adicionam comprimento sem adicionar descoberta.
Organizando uma Biblioteca de Habilidades em Crescimento
- Agrupe Habilidades relacionadas com um prefixo de nome compartilhado.
pr-review-checklist,pr-summary-draftepr-changelog-entryse ordenam juntos em uma listagem de pasta e sinalizam de relance que fazem parte de uma família. - Verifique se há descrições quase duplicadas antes de adicionar uma nova Habilidade. Se a descrição de uma nova Habilidade corresponder plausivelmente às mesmas tarefas de uma existente, essa sobreposição precisa ser resolvida - ou restrinja uma, ou incorpore a nova tarefa à Habilidade existente como um ramal.
- Mantenha um índice curto do que cada Habilidade faz, separado das Habilidades em si. À medida que uma biblioteca cresce além de uma dúzia de Habilidades, uma lista simples - nome, propósito de uma linha - economiza a um colega de equipe o trabalho de abrir cada pasta para encontrar a correta.
- Aposente ou mescle Habilidades que param de ser usadas. Uma Habilidade não utilizada com um nome semelhante a uma ativa é uma fonte comum de colisões acidentais mais tarde; removê-la (ou mesclar suas partes úteis) mantém o espaço de nomenclatura da biblioteca limpo.
- Versionamento informal com um comentário curto, não um sufixo de nome.
pr-review-checklist-v2/fragmenta a biblioteca e quebra quaisquer referências existentes; um comentário de uma linha "última atualização" dentro de SKILL.md comunica a mesma coisa sem dividir o nome.
Nomeando Arquivos Agrupados de Forma Consistente
- Dê aos arquivos de referência agrupados nomes descritivos e autônomos.
style-guide.mdeticket-schema.mdsão claros por si só;notes.mdoudata.mdexigem a abertura do arquivo para saber o que ele contém. - Prefira scripts agrupados pelo que fazem, não pela Habilidade em que vivem.
normalize-dates.pyé reutilizável em espírito e claro em uma listagem de pasta;helper1.pynão é nenhum dos dois. - Referencie arquivos agrupados pelo nome exato dentro das instruções. Isso é tanto uma disciplina de nomenclatura quanto uma estrutural - uma etapa que diz "o arquivo de referência" em vez de nomear
reference.mdtorna a conexão mais difícil de verificar de relance.
FAQs
Por que a nomenclatura importa se a descrição é o que realmente aciona uma Habilidade?
A descrição impulsiona o acionamento, mas os nomes são o que um humano escaneia ao navegar por uma pasta de Habilidades, e nomes incompatíveis ou vagos tornam muito mais difícil identificar duplicatas, lacunas e a Habilidade existente correta para estender.
Qual é o formato padrão para o campo de nome de uma Habilidade?
- Verbo-substantivo, kebab-case:
format-release-notes,summarize-support-transcript. - O nome da pasta deve corresponder exatamente a ele.
Por que evitar nomes como "helper" ou "assistant"?
Eles descrevem uma categoria, não uma ação, então colidem facilmente à medida que uma biblioteca cresce e não dizem a um colega de equipe que está escaneando nada sobre o que a Habilidade realmente produz.
Devo incluir um número de versão no nome de uma Habilidade, como pr-review-checklist-v2?
- Geralmente não - isso fragmenta a biblioteca e quebra quaisquer referências existentes ao nome original. Um comentário curto de "última atualização" dentro do arquivo comunica o mesmo histórico sem dividir o espaço de nomenclatura.
Como evito que uma biblioteca de Habilidades em crescimento desenvolva Habilidades quase duplicadas?
Verifique as descrições de novas Habilidades em relação às existentes antes de adicioná-las, e mantenha um índice simples (nome mais propósito de uma linha) quando a biblioteca crescer além de cerca de doze Habilidades.
Os arquivos de referência e scripts agrupados devem seguir seu próprio padrão de nomenclatura?
- Sim. Nomes descritivos e autônomos como
style-guide.mdounormalize-dates.pysão claros sem abrir o arquivo, ao contrário de nomes genéricos comonotes.mdouhelper1.py.
O que pertence ao campo description versus o campo name?
O nome é um identificador curto e escaneável. A descrição carrega o sinal de descoberta real - o que a Habilidade faz e quando ela deve ser acionada - e deve permanecer livre de detalhes de implementação interna como nomes de ferramentas ou arquivos.
Como devo nomear um grupo de Habilidades intimamente relacionadas?
- Dê a elas um prefixo compartilhado, como
pr-review-checklist,pr-summary-draftepr-changelog-entry, para que elas se ordenem juntas em uma listagem de pasta e sinalizem visivelmente que fazem parte de uma família.
O que devo fazer com uma Habilidade que parou de ser usada?
Aposente-a ou mescle-a em vez de deixá-la no lugar. Uma Habilidade não utilizada com um nome semelhante a uma ativa é uma fonte comum de colisões acidentais e confusão mais tarde.
Existe um único checklist de nomenclatura obrigatório que toda equipe deve seguir?
- Não exatamente - os padrões de nomenclatura (kebab-case, nomes de pastas correspondentes, evitar substantivos genéricos) são quase universais, mas os padrões organizacionais (prefixar, indexar, aposentar) são decisões que escalam com quantas Habilidades uma equipe realmente tem.
Relacionado
- Escrevendo uma Descrição de Habilidade Eficaz que Claude Acionará - o campo que realmente impulsiona o acionamento, distinto da nomenclatura.
- Noções Básicas de Design e Empacotamento de Habilidades - um primeiro SKILL.md funcional com um nome e descrição corretamente formados.
- Erros Comuns que Tornam uma Habilidade Difícil para Claude Encontrar ou Usar - falhas de nomenclatura e metadados ao lado de falhas de descrição.
- Tipos Comuns de Habilidades de Agente que as Equipes Constroem Primeiro - Habilidades típicas que uma biblioteca de nomenclatura acaba organizando.
Versões da Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5. Nomes de modelos, preços e recursos do produto mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.