🧭 O checklist de decisão
Antes de abrir um editor, responda quatro perguntas. Se a maioria for "não", você não precisa de uma skill — precisa de outra ferramenta, ou de nada. Este é o filtro que separa skill útil de poluição de catálogo.
Vale a pena criar?
- 1.É um workflow repetível, não um one-off?
- 2.Carrega conhecimento de contexto que o modelo não tem por default?
- 3.O output é verificável (dá pra dizer se ficou certo)?
- 4.É uma tarefa multi-step, não uma query de 1 passo?
≥2 sins → vale empacotar. 0–1 sim → provavelmente over-engineering.
CLAUDE.md
Regra/preferência que vale SEMPRE no projeto. Custa contexto sempre.
MCP
Conectar a um serviço externo (API, DB, browser). É conexão, não conhecimento.
Subagente
Trabalho isolado/paralelo com contexto próprio. É delegação.
Skill ✦
Conhecimento/processo que dispara SOB DEMANDA pelo gatilho. É o nosso caso.
📁 Estruturar o repo
Decidiu que é skill. Agora o repo precisa seguir a convenção que o CLI e o skills.sh entendem: uma pasta skills/ na raiz, e cada skill com seu SKILL.md mais resources opcionais. Um repo pode hospedar várias skills atômicas.
template de estrutura de repo:
meu-repo-de-skills/
├── README.md
├── LICENSE
├── CHANGELOG.md
└── skills/
└── minha-primeira-skill/
├── SKILL.md # frontmatter YAML + corpo (<500 linhas)
├── scripts/ # executáveis sob demanda
│ └── run.sh
├── references/ # docs longas, lidas só quando preciso
│ └── deep-dive.md
└── assets/ # templates, imagens
└── template.tpl
SKILL.md — o frontmatter é o gatilho:
--- name: minha-primeira-skill description: O QUE faz E QUANDO usar. Acione quando o usuário pedir X, mencionar Y, ou precisar de Z. Seja um pouco pushy — o modelo tende a subdisparar. --- # Minha Primeira Skill Corpo em Markdown. Explique o PORQUÊ, não só os passos. Aponte para references/ e scripts/ quando precisar de detalhe.
💡 O frontmatter mínimo
Só name e description são obrigatórios. A description (~100 palavras) fica sempre no contexto — é o único nível que o modelo sempre vê, então é onde mora o gatilho. Diga o que faz E quando usar.
🔀 Versionar via git
Git é a fonte da verdade da skill. Skills são instaladas como symlinks para o repo clonado — não cópias congeladas. Um git push seu, mais um npx skills update de quem instalou, propaga sua nova versão para todos. Trate a main como produção.
o fluxo git de uma release:
git checkout -b ajuste-gatilho # edita skills/minha-primeira-skill/SKILL.md git add skills/minha-primeira-skill/SKILL.md CHANGELOG.md git commit -m "fix(trigger): cobre o near-miss de refactor" git push origin ajuste-gatilho # abre PR, roda evals de gatilho, merge na main → publicado
✗ Descuidado
- ✗Push direto na main sem testar o gatilho
- ✗Mudar a description e quebrar quem dependia
- ✗Sem CHANGELOG — ninguém sabe o que mudou
✓ Responsável
- ✓Branch + PR + evals antes do merge
- ✓Mudanças de gatilho documentadas
- ✓CHANGELOG.md com cada release
📟 npx skills add / update
Os comandos que fazem a skill existir na máquina. Para testar localmente antes de publicar, você instala a partir do caminho do diretório; depois de no GitHub, instala por owner/repo. E update puxa as últimas versões.
comandos essenciais:
# instalar do diretório local (teste antes de publicar) npx skills add ./skills/minha-primeira-skill # instalar de um repo público no GitHub npx skills add owner/meu-repo-de-skills # puxar a última versão de tudo que está instalado npx skills update
O loop local de teste
Antes de publicar: rode npx skills add ./..., abra uma sessão com 2-3 prompts realistas, compare o comportamento com-skill vs baseline (sem skill). Ajustou o SKILL.md? Roda npx skills update e testa de novo. Só publica quando o gatilho e o output convencerem.
💡 Symlink = iteração grátis
Como a instalação é um symlink para a pasta, editar o SKILL.md no local já reflete na próxima sessão — sem reinstalar. Isso torna o loop de afinação rápido. O mesmo symlink, depois de publicado, é por que um push ruim afeta todo mundo na hora.
🌐 Ir ao ar e aparecer no skills.sh
Publicar é deixar o repo público no GitHub com a pasta skills/ na convenção certa. O skills.sh indexa repos públicos e expõe o install count. A timeline do zero ao ar:
Crie o repo público no GitHub
Com README, LICENSE e a pasta skills/ na raiz. Nome do repo claro — ele vira parte do owner/repo que as pessoas instalam.
Push da v1 testada
SKILL.md com frontmatter validado, resources no lugar, evals de gatilho passando. git push na main.
Indexação no skills.sh
O diretório varre repos públicos e sua skill aparece na busca. name e description são o que as pessoas leem na vitrine.
Instalações começam a contar
Cada npx skills add owner/repo incrementa o install count — seu sinal social de descoberta. Lembre da lei de potência: só 0,3% passam de 100k.
Naming e description vendem
Na vitrine do skills.sh, a pessoa decide instalar lendo só name + description. Um nome específico (git-commit-conventional) e uma description que diz o que faz e quando vence um nome genérico (git-helper) sempre. É o mesmo texto que serve de gatilho — dois pássaros.
⏱️ A timeline completa, do zero ao publish
Juntando tudo numa sequência única que você pode seguir hoje. Sete passos, da decisão ao install count rodando:
Decidir — passe pelo checklist de 4 perguntas e pela árvore skill/CLAUDE.md/MCP/subagente.
Estruturar — crie skills/nome/SKILL.md com frontmatter + corpo enxuto.
Testar local — npx skills add ./... e compare com-skill vs baseline em prompts reais.
Afinar o gatilho — rode evals should-trigger / should-not-trigger, ajuste a description.
Versionar — commit, CHANGELOG, branch + PR. git push na main = publicado.
Ir ao ar — repo público, indexação no skills.sh, aparece na busca.
Medir — install count e feedback começam a fluir. Entra o ciclo de vida (próximo módulo).
💡 Ponte pro 5.5
Publicar a primeira skill é o passo 6. O 5.5 fecha o curso com o que vem depois em escala: skills internas, segurança, rollout em time e como manter skills vivas sem virar caos.
✅ Resumo do Módulo
Próximo:
Módulo 5.5 — 🚀 Dicas Avançadas: Governança, Segurança e Escala. Skills internas, não-surpresa, rollout em time e medir adoção. Fecha o curso.