📁 Estrutura de repo pra publicar
Para uma skill ser instalável e indexável, o repo precisa seguir a convenção: uma pasta skills/ na raiz, e dentro dela cada skill com seu SKILL.md mais os resources opcionais. Fora dessa estrutura, o CLI e o skills.sh não encontram nada.
layout de um repo publicável:
meu-repo-de-skills/
├── README.md
└── skills/
├── react-component-scaffold/
│ ├── SKILL.md # frontmatter + corpo (<500 linhas)
│ ├── scripts/ # scripts executáveis sob demanda
│ │ └── scaffold.sh
│ ├── references/ # docs longas carregadas só quando preciso
│ │ └── patterns.md
│ └── assets/ # templates, imagens
│ └── component.tpl
└── git-commit-style/
└── SKILL.md
Progressive disclosure em 3 níveis
Metadata (name + description)
~100 palavras, sempre no contexto. É o gatilho. Custo permanente — mantenha enxuto.
Corpo do SKILL.md (<500 linhas)
Carregado só quando a skill dispara. As instruções de fato.
Bundled resources
scripts/, references/, assets/ — lidos sob demanda, quando o corpo aponta para eles.
💡 Dica de repo
Um único repo pode hospedar várias skills atômicas — é assim que vercel-labs/skills e anthropics/skills funcionam. Quem instala escolhe o repo (owner/repo) e o CLI puxa as skills da pasta skills/.
🔀 Versionar via git
Skills vivem em git e são instaladas como symlinks, não cópias. Isso muda tudo: quando você dá git push e o usuário roda npx skills update, sua nova versão se propaga para todos. Você não controla só seu repo — controla o comportamento de quem instalou.
Commit + push
A fonte da verdade é o git. Edite o SKILL.md, commite com uma mensagem clara, faça push. Pronto — a versão publicada mudou.
Symlink no lado do usuário
Por padrão a skill é symlinkada do repo clonado. Não há cópia congelada — a instalação aponta para a fonte.
npx skills update
Um comando puxa as últimas versões de todas as skills instaladas. É o que torna o ecossistema vivo — e o que exige cuidado seu.
✗ Versionamento descuidado
- ✗Push direto na main sem testar o gatilho
- ✗Mudar a description e quebrar quem dependia dela
- ✗Sem changelog — ninguém sabe o que mudou
✓ Versionamento responsável
- ✓Rodar evals antes do push
- ✓Mudanças de gatilho documentadas
- ✓CHANGELOG.md com cada release
💡 O poder do symlink
O symlink é por que skills se atualizam de graça — mas também por que um push ruim afeta todo mundo imediatamente. Trate a main do repo de skills como produção.
🌐 Aparecer no skills.sh
O skills.sh indexa repos públicos e mostra o install count como métrica social — o sinal de descoberta e confiança. Mas as contas são duras: das 39.366 skills do catálogo (5.075 repos fonte, 53,9M instalações somadas), a distribuição segue uma lei de potência brutal.
As top 100 = 43,7% de todos os installs
A concentração é extrema. find-skills sozinha tem 1.802.925 installs (vercel-labs). frontend-design 488.299 (anthropics), vercel-react-best-practices 443.261. Estar no topo é raro — mas o install count ainda é seu melhor sinal de descoberta.
A lição: não persiga o leaderboard. Resolva um problema real bem, com naming e description claros, e a descoberta acontece dentro do seu nicho.
📊 Medir triggering
A pergunta que separa skill amadora de skill profissional: a description dispara nos casos certos? Você não adivinha — você mede, com evals de gatilho. Liste queries que deveriam disparar, queries que não deveriam, e os near-misses traiçoeiros.
eval de gatilho (exemplo):
skill: react-component-scaffold should_trigger: - "cria um componente de card" - "preciso de uma nova tela de login em React" - "refatora esse JSX em componentes" should_not_trigger: - "qual a sintaxe de um for em Python?" - "explica o que é o virtual DOM" # near-miss: fala de React mas não pede componente # meça: % de acerto em cada lista
✓ Should-trigger
Os casos em que a skill precisa aparecer. Se ela some aqui, sua description está vaga ou tímida demais.
Falha aqui = subdisparo (recall baixo).
✗ Should-not-trigger
Os casos em que ela precisa ficar quieta. Os near-misses (tocam no tema mas não no gatilho) são os mais reveladores.
Falha aqui = disparo errado (precisão baixa).
💡 O loop de afinar o gatilho
Rode os evals → veja onde errou → ajuste só a description (não o corpo) → rode de novo. Os near-misses te dizem exatamente quais palavras adicionar ou remover. Triggering é o KPI que quase ninguém mede — e o que mais determina se a skill é útil.
🛡️ Princípio da não-surpresa
Skills rodam com a confiança do usuário. O princípio de ouro: a skill não deve fazer nada que o usuário não esperaria ao ler a description. Nada de deletar arquivos, enviar dados para fora ou rodar comandos destrutivos como efeito colateral silencioso.
✗ Surpresa (quebra a confiança)
- ✗"formata o código" e de quebra faz
git push --force - ✗Script em scripts/ que envia telemetria oculta
- ✗
rm -rfescondido num passo de "limpeza" - ✗Acessa segredos sem o usuário pedir
✓ Não-surpresa (confiável)
- ✓Faz exatamente o que a description promete
- ✓Ações destrutivas pedem confirmação explícita
- ✓Least privilege: só toca no que precisa
- ✓Scripts auditáveis e transparentes
Por que isso é existencial pro ecossistema
Como skills se instalam via symlink e atualizam com um comando, um repo malicioso ou descuidado pode afetar muita gente de uma vez. A reputação do skills.sh inteiro depende de cada autor respeitar a não-surpresa. Audite seus próprios resources como se fosse um usuário desconfiado instalando.
♻️ O ciclo de vida
Publicar não é o fim — é o começo do ciclo. A skill é um produto vivo: você publica → observa installs e feedback → itera na description e no corpo → republica. E repete. O catálogo de 53,9M instalações é feito de skills que iteraram.
Publicar
Repo com pasta skills/, push para o GitHub, indexação no skills.sh. A v1 está no mundo.
Observar
Acompanhe install count, issues, e como a skill se comporta em uso real. Os dados te dizem onde o gatilho falha e onde o corpo confunde.
Iterar
Afine a description com base nos near-misses reais, enxugue o corpo, extraia scripts repetidos. Commit, push, e o ciclo recomeça.
💡 Onde aprender mais
Você fechou as 5 trilhas: panorama, qualidade, anatomia, o loop de criação e os modelos mentais. O próximo passo é publicar sua primeira skill de verdade — e continuar evoluindo. Encontre mais cursos, exemplos e a comunidade no INEMA.CLUB.
✅ Resumo do Módulo · Fim do Curso
Você concluiu o curso! 🎉
Cinco trilhas, da visão do ecossistema até a publicação e medição. Agora é com você: escolha um workflow repetível do seu dia a dia, escreva a primeira skill, publique e itere. Continue aprendendo no portal.