skills — ateliê de criação de skills

Você está aqui (L0). Este diretório é o ateliê onde skills do Claude Code são criadas e amadurecidas. Não é um projeto de produto: é a forja. O ciclo é sempre o mesmo — surge uma ideia de skill, o escopo é fechado, e a skill é escrita aqui.

Por padrão toda skill criada fica neste diretório (inerte — não ativa em lugar nenhum) até que seja importada para o projeto onde faz sentido. A skill que faz essa importação é a install-skill — e ela é a única exceção à regra "fica só aqui": por ser global, vive também em ~/.claude/skills/.

O fluxo de trabalho (ideia → skill)

1. Ideia. Descreva, em linguagem natural, o que a skill deveria fazer.
2. Amadurecer + fechar escopo. O que a skill habilita o Claude a fazer, quando deve disparar (frases/contextos reais), formato de saída, edge cases, dependências/ferramentas, e se vale ter casos de teste. Convergir antes de escrever — escopo aberto demais vira skill ruim.
3. Escrever a skill. Criar <nome>/SKILL.md no formato Claude Code (ver convenções abaixo). Recursos opcionais (scripts/, references/, assets/) na própria subpasta da skill.
4. (Opcional) Avaliar e iterar. Para skills com saída objetivamente verificável, montar 2–3 prompts de teste e iterar (ver skill-eval).
5. Disponibilizar. A skill fica aqui. Para usá-la num projeto, rode /install-skill <nome> lá dentro (ou de qualquer lugar apontando para o projeto).

Convenções de skill

• Uma skill = uma subpasta <nome>/ contendo SKILL.md. O nome da pasta = o name do frontmatter (kebab-case). Copiar essa subpasta inteira para o .claude/skills/ de um projeto é tudo que "instalar" significa — por isso cada skill é auto-contida.
• Frontmatter mínimo: name e description. A description é o gatilho — escreva-a "pushy", dizendo o que a skill faz e quando usá-la, com frases-gatilho concretas (o Claude tende a subdisparar skills; combata isso). Toda informação de "quando usar" vai na description, não no corpo.
• Skills user-invocáveis (um /comando): adicionar user-invocable: true, argument-hint e allowed-tools.
• Convenção própria do ateliê — scope: campo opcional no frontmatter, project (default) ou global.
  • scope: project → importada sob demanda para o .claude/skills/ de um projeto específico. Não fica ativa em lugar nenhum até ser instalada. É o caso comum.
  • scope: global → mora em ~/.claude/skills/ e fica disponível em qualquer workspace. Usar com parcimônia (só para skills genuinamente transversais, como a própria install-skill).
• Pacote completo, não só o .md. Toda parte determinística e repetitiva (varrer arquivos, chamar APIs, copiar/clonar, parsear, transformar) vira script bundled em scripts/, cujo resultado (de preferência JSON) o modelo consome — em vez de reescrever os comandos a cada execução. O modelo fica com o que é julgamento/interação (decidir, perguntar, ranquear). Recursos auxiliares: scripts/ (executáveis), references/ (docs lidos sob demanda), assets/ (templates/ícones). Os scripts deste repo são PowerShell (pwsh -NoProfile -File ...).
• Progressive disclosure: mantenha o SKILL.md enxuto (idealmente < 200 linhas). Detalhe pesado e material de referência vão em references/ e são lidos sob demanda; lógica pesada vai para scripts/.
• Princípio da não-surpresa: skills não contêm malware nem fazem nada que o usuário não esperaria pela descrição.

A exceção global: install-skill

A install-skill precisa estar disponível de qualquer workspace para conseguir importar as demais skills — por isso é scope: global. A cópia canônica/de desenvolvimento vive aqui no ateliê (install-skill/); a cópia ativa vive em ~/.claude/skills/install-skill/. Para ressincronizar, rode de qualquer lugar:

/install-skill install-skill --global