🔒 Skills internas (privadas)
Nem toda skill deve ir para o catálogo público. Conhecimento proprietário, convenções internas e fluxos do seu time vivem como skills internas — marcadas com metadata.internal e instaladas só com a flag INSTALL_INTERNAL_SKILLS. Ficam fora do skills.sh e do install count público.
marcar uma skill como interna:
--- name: deploy-runbook-acme description: Runbook interno de deploy da Acme. Acione em deploy, rollback ou incidente em produção. metadata: internal: true --- # só instala com a flag explícita: INSTALL_INTERNAL_SKILLS=1 npx skills add acme/skills-privadas
Boas candidatas a interna
- ›Runbooks de deploy/incidente do time
- ›Convenções de código proprietárias
- ›Integrações com sistemas internos
Por que separar do público
- ›Evita vazar contexto sensível no catálogo
- ›Não polui o skills.sh com ruído só-seu
- ›Instala por opt-in explícito, nunca por acidente
🛡️ Não-surpresa e segurança
O princípio de ouro: a skill nunca faz o que a description não promete. Como skills se instalam via symlink e atualizam com um comando, um repo malicioso ou descuidado contamina muita gente de uma vez. A confiança do ecossistema inteiro depende disso.
✗ Surpresa / risco
- ✗Script que exfiltra dados ou envia telemetria oculta
- ✗
rm -rfougit push --forceescondido num passo - ✗Acessa segredos/credenciais sem o usuário pedir
- ✗Baixa e executa código de fonte externa em runtime
✓ Confiável
- ✓Faz exatamente o que a description diz
- ✓Ação destrutiva pede confirmação explícita
- ✓Least privilege: toca só no necessário
- ✓Scripts auditáveis, sem dependências obscuras
💡 Audite como quem instala
Antes de publicar, leia seus próprios scripts/ com os olhos de um usuário desconfiado. Sem malware, sem exfiltração, sem efeito colateral surpresa. Uma quebra de confiança queima a reputação do repo inteiro — e respinga no skills.sh.
🏷️ Estratégia de versionamento
Em escala, "push na main" sem estratégia vira instabilidade. Porque o symlink propaga toda mudança na hora, você precisa de uma disciplina de versionamento que separe o que é seguro do que é arriscado.
O que cada tipo de mudança exige
Correção de texto, clarificação do corpo. Baixo risco — pode ir direto, com eval rápido.
Novo comportamento aditivo. Ainda compatível — rode evals completos antes.
Mudança de gatilho ou de comportamento esperado. Quebra quem dependia — comunique e documente no CHANGELOG.
tag a release e mantenha um CHANGELOG:
## [1.2.0] - 2026-06 ### Changed - description agora cobre o near-miss de "refatorar" (minor) ### Fixed - corpo: removido MUST que causava overfit em projetos sem testes git tag v1.2.0 && git push --tags
A regra da mudança de gatilho
Mexer na description é a mudança mais perigosa que existe: ela altera quando a skill dispara para todos que instalaram. Trate toda edição de description como potencial major até os evals provarem o contrário.
👥 Rollout em time
Distribuir skills para um time é diferente de publicar para o mundo. Você quer consistência (todo mundo com o mesmo conjunto), controle de versão e um caminho de adoção que não pegue ninguém de surpresa.
Um repo curado do time
Centralize as skills aprovadas num repo só, público ou interno. Vira a fonte única — ninguém instala skills aleatórias direto no projeto compartilhado.
Pilote antes do rollout geral
Um subgrupo instala, usa por uma semana e reporta. Ajuste gatilho e corpo com feedback real antes de expandir para todo mundo.
Comunique antes de cada update
Como npx skills update propaga tudo, avise o time antes de mudanças de gatilho. Um changelog num canal compartilhado evita o "por que a skill começou a disparar nisso?".
💡 Pro tip de onboarding
Documente o conjunto de skills do time no README do repo curado, com um npx skills add por linha. Quem entra roda a lista e está produtivo no dia um, com o mesmo comportamento de agente que todo mundo.
📈 Medir adoção
Skill em escala é produto — e produto se mede. Duas métricas que importam: install count (quantos adotaram) e triggering (se dispara nos casos certos). Uma alta e a outra baixa contam histórias bem diferentes.
Install count
Mede descoberta e adoção. Baixo com bom triggering = problema de naming/description ou de nicho, não de qualidade. Não persiga o leaderboard.
Triggering
Mede se a skill aparece na hora certa. Alto install + triggering ruim é o pior cenário: muita gente frustrada. Meça com evals should-trigger / should-not-trigger / near-miss.
♻️ Manter skills vivas em escala
Uma skill é fácil de manter. Vinte skills viram um portfólio — e portfólio sem manutenção apodrece. Os pro tips para manter dezenas de skills úteis sem virar caos:
✗ Portfólio que apodrece
- ✗Skills duplicadas com gatilhos que colidem
- ✗Nenhum eval — quebras passam despercebidas
- ✗Skills mortas que ninguém usa, poluindo busca
- ✗Corpos que incharam para 800 linhas com o tempo
✓ Portfólio vivo
- ✓Cada skill atômica, gatilhos sem sobreposição
- ✓Suite de evals roda no CI a cada push
- ✓Revisão periódica: aposenta o que não dispara
- ✓Corpo enxuto; detalhe vai pra references/
Pro tips finais
- ★Evals no CI: rode should-trigger / should-not-trigger automaticamente em cada PR — pega regressão de gatilho cedo.
- ★Audite sobreposição: duas skills que disparam no mesmo prompt competem e confundem. Funda ou diferencie os gatilhos.
- ★Aposente sem dó: skill com install count parado e triggering ruim só polui. Deprecie no CHANGELOG e remova.
- ★Mantenha enxuto: a cada release, pergunte o que dá pra cortar. Corpo <500 linhas não é meta, é higiene.
💡 O fechamento
Você percorreu as 5 trilhas: panorama do ecossistema, qualidade e as melhores, anatomia, o loop de criação e os modelos mentais de decisão, publicação e escala. Daqui é prática: escolha um workflow repetível, escreva, publique, meça e itere.
✅ Resumo do Módulo · Fim do Curso
Você concluiu o curso! 🎉
Cinco trilhas, da visão do ecossistema até governança e escala. Agora é com você: escolha um workflow repetível do seu dia a dia, escreva a primeira skill, publique, meça e itere. Continue aprendendo no portal.