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-guide sã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 chamada pr-review-checklist deve viver em uma pasta chamada pr-review-checklist/, não pr-review/ ou checklist/ - incompatibilidades tornam uma biblioteca mais difícil de escanear e pesquisar.
• Evite substantivos genéricos como nome completo. helper, assistant, utility e tool nã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-update do que process-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-draft e pr-changelog-entry se 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.md e ticket-schema.md são claros por si só; notes.md ou data.md exigem 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.py nã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.md torna a conexão mais difícil de verificar de relance.

FAQs

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.