THE CLAUDESKILLS HUB
Escreva sua primeira skill

Escreva sua primeira skill do Claude, da pasta vazia até instalada

Uma skill é uma pasta com um arquivo SKILL.md dentro. Este guia constrói uma skill real de ponta a ponta e para em cada ponto onde é fácil errar. Ele não pressupõe nada além de você já ter um fluxo que fez na mão mais de uma vez.

Os sete passos

  1. 1. Parta de um fluxo que você já repetiu

    Não parta de uma ideia. Parta de algo que você fez na mão pelo menos três vezes, porque só assim você sabe quais passos são reais e quais você imaginou. Se não dá para descrever o trabalho sem dizer depende, ainda é cedo para codificar.

  2. 2. Crie a pasta e nomeie com exatidão

    O nome da pasta e o campo name precisam bater, e o nome tem restrições: só minúsculas, números e hifens, sem hífen no início ou no fim, sem hífen duplo e no máximo 64 caracteres. Renomear depois significa renomear os dois, então escolha um nome com que você consiga conviver.

    my-skill/
├── SKILL.md          # required
├── references/
│   └── REFERENCE.md  # loaded only when needed
└── scripts/
    └── check.py
    Só o SKILL.md é obrigatório. O resto carrega sob demanda.

  3. 3. Escreva a descrição antes do corpo

    A descrição decide se a sua skill chega a carregar, então escreva primeiro, enquanto você lembra da tarefa nas palavras que uma pessoa usaria. Diga o que ela faz e quando usar, e inclua os jeitos de falar que um colega usaria, não só os seus.

  4. 4. Escreva o corpo como procedimento, não como ensaio

    O corpo só é lido depois que o agente decidiu ativar a skill, então ele deve conter passos, pontos de decisão e o formato do resultado. Deixe de fora o conhecimento geral que o modelo já tem: custa contexto e não acrescenta nada.

    ---
name: release-notes
description: Writes release notes from merged pull requests, grouped by user facing change. Use when preparing a release, writing a changelog, or when the user mentions release notes.
---

# Release notes

## Steps
1. List merged pull requests since the previous tag.
2. Group them by user facing change, not by author or by file.
3. Drop internal refactors unless they change behaviour.
4. Write one line per change, in the present tense.

## Output
A Markdown list under a version heading. No emoji. No marketing language.
    Uma skill completa e válida. A seção de saída é o que impede o formato de desviar.

  5. 5. Adicione campos opcionais só quando valerem

    A maioria das skills não precisa de nada além de name e description. Adicione license ao publicar, compatibility só quando o ambiente importar de verdade, e metadata para o que a especificação não define. allowed-tools é experimental, então trate o suporte como incerto.

    ---
name: release-notes
description: Writes release notes from merged pull requests, grouped by user facing change. Use when preparing a release, writing a changelog, or when the user mentions release notes.
license: MIT
compatibility: Requires git and network access to the repository host
metadata:
  author: example-org
  version: "1.2"
---

  6. 6. Quebre o que for longo em referências

    O corpo carrega inteiro toda vez que a skill ativa, então mantenha abaixo de umas 500 linhas e mova o detalhe para references/. Mantenha essas referências a um nível de profundidade, porque uma cadeia de arquivos que apontam uns para os outros é mais lenta e mais fácil de perder.

    See [the full grouping rules](references/GROUPING.md).

Run the collector first:
scripts/collect.py --since v1.4.0

  7. 7. Valide e teste o disparo com as palavras dos outros

    Rode o validador primeiro, porque erros de nome e frontmatter aparecem como uma skill que nunca carrega. Depois teste o que nenhum validador confere: peça a tarefa como um colega pediria e veja se a skill ativa. Se não ativar, o problema é a descrição, não o corpo.

    skills-ref validate ./my-skill

Os cinco erros que mais custam

Todos produzem uma skill que parece certa na revisão e falha no uso, e é por isso que eles sobrevivem tanto.

Uma descrição escrita no seu próprio vocabulário
Ela combina com o seu jeito de falar e com o de mais ninguém. É o motivo mais comum de uma boa skill nunca ser usada.
Um ensaio em vez de um procedimento
Contexto e justificativa queimam tokens toda vez que a skill ativa sem mudar o que o agente faz.
Codificar conhecimento que o modelo já tem
Explicar o que é um pull request adiciona tokens e nenhum comportamento. Codifique suas convenções, não o domínio.
Duas skills instruindo a mesma decisão
O agente recebe instruções contraditórias e resolve sem você ver. Uma fonte de verdade por trabalho.
Nunca testar o disparo
Todo mundo testa o corpo ativando a skill na mão. Quase ninguém testa se ela ativa sozinha.

Distribuindo

Uma skill é uma pasta, então distribuir é publicar essa pasta em algum lugar instalável, no mais simples um repositório público que as pessoas adicionam com o CLI de skills. Antes de publicar, leia o mapa de compatibilidade: se a sua skill instrui sobre uma decisão que outra skill popular já governa, diga isso na sua própria descrição em vez de deixar o usuário descobrir o conflito.

npx skills add owner/repo

Referência do SKILL.mdVerificador de descriçõesConflitos e combinações