Pular para o conteúdo
Voltar para o blog
  • Governança de IA
  • Inteligência Artificial
  • Segurança da Informação
  • Arquitetura de Software
  • Automação
  • Claude Code

Hub de Skills

Governança de Skills de IA para Quem Não É Dev

Pixel art noturno: uma estufa de vidro geodésica protege mudas de circuito e distribui brotos por cabos roxos aos prédios em volta

Uma skill do Claude Code ou do Codex parece inofensiva: é uma pasta com um arquivo de instruções. Só que, muitas vezes, essa pasta também traz scripts que rodam na máquina de quem usa. Enquanto ela vive só no seu computador, tudo bem. Quando ela passa a chegar no computador de 35 pessoas de 7 equipes, ela vira software, com todas as perguntas que software traz: quem recebe, qual versão, e quem garante que ninguém alterou o que foi aprovado. No post Governança de IA na Prática eu prometi mostrar como algumas skills viraram sistemas internos na InBot. Começo pelo que sustenta todos eles: o Hub de Skills, e a governança de skills de IA que roda por baixo dele sem que quem não é dev precise saber que ela existe.

Quando a Skill Sai da Sua Máquina, Ela Vira Software

A própria Anthropic é direta sobre isso. Na documentação de Agent Skills, a recomendação é usar skills só de fontes confiáveis e tratar a instalação de uma skill como a instalação de um software, porque uma skill maliciosa pode executar código que não tem nada a ver com o propósito declarado.

Isso não é cuidado exagerado. Em fevereiro de 2026, a Snyk analisou 3.984 skills publicadas num marketplace aberto e encontrou 534 com problemas críticos de segurança e 76 maliciosas confirmadas. E o caso do pacote postmark-mcp mostra como isso acontece na prática: 15 versões limpas, ganhando confiança, até que na versão seguinte uma única linha passou a mandar uma cópia oculta de todos os e-mails para o atacante.

Como a gente começou (e por que não dava para continuar)

Na InBot, as skills nasceram boas. O que estava em volta delas, não. Quando a área de IA começou a entregar para a empresa inteira, o ritmo era muito acelerado: muitas tarefas na sprint e pouco tempo para montar a parte de software do jeito certo.

O hub que usávamos na época não tinha sido desenvolvido pela nossa equipe. Era um protótipo criado antes, para validar a ideia, e ele cumpriu bem esse papel: provou que distribuir skills para o time inteiro funcionava. Só que o protótipo acabou ficando em uso. Ele não tinha autenticação, e subir conteúdo exigia apenas uma senha de administrador. Quem descobrisse essa senha poderia publicar algo malicioso.

A atualização nas máquinas tinha o mesmo perfil. Cada equipe tinha o próprio instalador, que deixava no computador da pessoa a identificação da equipe e uma credencial de leitura do repositório de skills. O conteúdo era auditado antes de chegar às máquinas, mas o mecanismo era frágil.

Quando o ritmo de entregas diminuiu, o time de desenvolvimento, que é a equipe mais técnica da empresa, levantou os riscos de segurança, e levantou com toda a razão. A diretoria tomou uma decisão que eu considero o ponto mais maduro dessa história: reduzir a velocidade de entregas de skills, automações e plataformas para arrumar a base. No dia 3 de outubro fizemos o que internamente chamamos de "big bang": num único dia, o backend, o login, a assinatura e o fluxo de revisão mudaram de uma vez.

Antes de entrar em como isso funciona, uma definição importante: quando eu falo "Hub de Skills", não estou falando só de um site. O Hub é o app web, o backend e as próprias skills que conversam com ele, como a que instala, a que faz login e a que publica.

Quem Recebe: SSO, Grupos e "Ver = Receber"

A primeira pergunta de qualquer sistema de distribuição é quem recebe o quê. A resposta foi tirar a decisão de qualquer senha compartilhada e colocá-la no SSO (login único corporativo), o mesmo login que as pessoas já usam para os outros sistemas da empresa.

No terminal, o login usa o Device Authorization Grant: o script mostra um código, a pessoa abre o navegador, entra com a conta da empresa e pronto. Com PKCE, ninguém que intercepte esse fluxo consegue reaproveitar o código. O provedor de identidade é o Keycloak, que já oferecia o fluxo de dispositivo, sessões offline e grupos prontos.

Grupos por equipe, e o que fica fora do alcance não existe

Cada equipe é um grupo: comercial, desenvolvimento, marketing, planejamento, projetos, QA e UX. Existem ainda grupos para homologação, para quem edita e para administração. Daí sai uma regra simples, que eu chamo de "ver = receber": a mesma função decide o que o sync baixa para a sua máquina e o que o Hub mostra para você. Não existe uma tela que mostra uma coisa e um instalador que entrega outra.

E se você pedir uma skill que não é da sua equipe, a resposta não é "acesso negado". É "não existe". Parece detalhe, mas evita que alguém descubra, por tentativa, quais skills as outras equipes têm. Do outro lado, tirar o acesso de alguém vale rápido de verdade. O login gera dois tokens: um token de acesso, que dura só 5 minutos, e um refresh token, que serve para pedir um token de acesso novo e expira depois de 2 dias sem uso. Quando o acesso de uma pessoa é revogado, o refresh token pode até continuar válido, mas fica inútil: ele não consegue mais gerar um token de acesso, e o que ela tinha deixa de funcionar em, no máximo, 5 minutos. Se você leu o post sobre autorização ReBAC, vai reconhecer a ideia: acesso é relação, e relação tem que poder ser desfeita rápido.

A fonte da verdade é o repositório, não o banco

Tem uma decisão de desenho que pesa em tudo o que vem depois: os arquivos são a fonte da verdade. A versão da skill e quem tem acesso a ela ficam registrados na própria skill, dentro do repositório. O backend lê isso, mas não é o dono disso.

Na prática, se amanhã trocarmos de plataforma, sairmos do Hub ou até perdermos os dados do backend, continuamos sabendo exatamente como tudo está organizado, e o histórico do Git dá a rastreabilidade de cada mudança. A recomendação de Skills for enterprise da Anthropic vai na mesma linha: usar o controle de versão como fonte da verdade das skills.

O que Chega é o que Foi Aprovado: Assinatura Ed25519 e Revisão Humana

Agora o cenário que mudou a minha forma de pensar sobre isso. Imagine que alguém consiga acesso ao GitHub da empresa, por qualquer meio, e suba uma skill com um script malicioso. Num modelo ingênuo, o sync faz exatamente o trabalho dele: entrega esse script nas 35 máquinas na manhã seguinte.

Isso não é paranoia, é o padrão dos maiores incidentes recentes de cadeia de suprimentos de software. No xz utils, em 2024, as versões 5.6.0 e 5.6.1 saíram com um backdoor direto do repositório oficial. No tj-actions/changed-files, em 2025, uma GitHub Action comprometida expôs os segredos de quem a executava. E o worm Shai-Hulud comprometeu mais de 500 pacotes do npm, publicados em nome dos próprios desenvolvedores. Em todos, a origem confiável foi o que entregou o código malicioso.

Assinatura: a máquina só aceita o que um humano aprovou

A resposta foi separar "estar no repositório" de "estar aprovado". Toda versão liberada é assinada digitalmente, e a máquina de quem usa se recusa a instalar o que não confere.

  • O que é assinado: os scripts de instalação, de sync e de login, nas versões para Linux/macOS e Windows, e uma lista com o hash (a impressão digital) de cada skill liberada. Se um único arquivo da skill mudar, o hash muda e a assinatura deixa de bater.
  • Como: com o próprio ssh-keygen, que assina e verifica arquivos desde o OpenSSH 8.1, usando uma chave Ed25519 protegida por senha. Escolhemos SSH porque já está instalado em todo lugar; até a documentação do GitHub diz que assinaturas SSH são as mais simples de gerar. E o Ed25519 é rápido, tem chaves e assinaturas pequenas e não depende de gerar um número aleatório a cada assinatura.
  • Onde é conferido: na máquina de quem usa, no servidor e até no navegador. Quando alguém baixa o instalador pela página do Hub, o próprio navegador confere a assinatura com WebCrypto, recurso que só chegou a todos os navegadores grandes em 2025, com o Chrome 137. Para entregar um instalador falso, alguém precisaria invadir o servidor e o Hub ao mesmo tempo.

Com isso, o cenário do GitHub invadido muda completamente. A alteração entra no repositório, mas não chega a nenhuma máquina, porque ninguém assinou. E, no mesmo momento, um e-mail é disparado para a equipe de IA e para a diretoria, avisando que algo errado está acontecendo.

A IA prepara, um humano assina

Toda publicação vira um pull request de revisão, e quem aprova é a equipe de IA, com um script que mostra exatamente o que vai ser liberado, pede a senha da chave uma única vez, faz o merge e assina. O framework SLSA resume bem o porquê: uma revisão feita por uma segunda pessoa poderia ter detectado a mudança não autorizada. A Anthropic diz o mesmo, com todas as letras, no guia de skills para empresas:

"Skill authors should not be their own reviewers."

Ou seja: quem escreve a skill não deve ser quem a revisa.

E aqui tem uma regra que não negocio: um agente de IA nunca assina nem aprova. A IA faz quase todo o caminho (prévia, ficha, PR, card no ClickUp), mas a assinatura é sempre de uma pessoa.

Primeiro por responsabilidade: alguém precisa responder pelo que chega no computador da equipe inteira. Segundo por defesa: se um agente pudesse assinar, uma instrução maliciosa escondida num arquivo poderia convencê-lo a liberar algo.

Isso não virou gargalo, justamente porque a revisão chega pronta: diff, ficha preenchida e testes rodados. Se quiser entender por que eu gosto tanto de PR com regra de proteção na branch principal, escrevi sobre isso em Git Flow para GitHub Flow.

Quem Não É Dev Nem Percebe: Login Único, Sync Diário e Canais de Homologação

Tudo isso seria inútil se pesasse para quem usa. Segurança que atrapalha vira gambiarra, e gambiarra com IA tem nome: shadow AI, o uso de IA fora de qualquer controle. Segundo a Gartner, em dado reportado pela Infosecurity Magazine, 69% das organizações já suspeitam desse uso e mais de 40% devem ter um incidente ligado a ele até 2030. Então a regra foi clara: o custo do rigor fica com quem constrói, não com quem usa.

Para quem usa, a experiência é esta:

  • Uma instalação, com login. Depois disso, a pessoa não pensa mais no assunto.
  • Atualização sozinha. O sync roda todo dia de manhã e também quando a pessoa abre o Claude Code ou o Codex, se ainda não tiver rodado. Só baixa o que mudou.
  • Funciona onde a pessoa estiver: Claude Code e Codex, em Linux, macOS e Windows.
  • Canais de homologação e produção. Quem participa dos testes recebe a versão de homologação por padrão, e pode pedir a de produção para uma skill específica.

Onde a complexidade apareceu: em quem publica

Para a equipe em geral, o sistema continua simples. A complexidade apareceu para os líderes que publicam skills, e não é técnica: são muitas opções e um fluxo com regras. Como os arquivos são a fonte da verdade, publicar uma skill mexe nos arquivos dela, e muitos líderes não são técnicos.

A solução foi uma skill. A mesma que atualiza as skills na máquina ganhou a capacidade de publicar: a pessoa pede em linguagem natural, a skill monta a prévia com o diff (o que é novo, o que mudou, o que saiu), ajuda a preencher uma ficha de 7 campos (problema, quem usa, entrada, saída, critério de sucesso, riscos e origem) e envia para revisão. A resposta vem em até 2 dias úteis. É IA automatizando a própria governança.

Testar uma skill como um usuário de verdade

Antes de uma skill chegar à revisão, ela passa por uma bateria de testes feita por outra skill, a testar-skill. Ela monta 10 cenários (5 ideais, 3 ambíguos e 2 extremos), variando o quanto de informação a pessoa dá, a qualidade dos documentos e o tom da mensagem. O gabarito de cada cenário é escrito antes de rodar, no mesmo espírito do que contei em minha jornada com TDD.

Depois, a testar-skill dispara subagentes em paralelo, cada um com o contexto zerado e falando como um usuário real, sem saber que é um teste. Se a skill testada faz uma pergunta, o "usuário" responde no mesmo tom; se ela não chega a lugar nenhum em 5 rodadas, o resultado é "não converge". Qualquer ação externa é adiada, e os arquivos da pessoa são protegidos durante a bateria. Já são mais de 70 relatórios de teste de skills guardados.

Medir o uso, mostrando exatamente o que sai

A última peça veio de fora. No Lovable Day, ouvi de outra empresa que faz um trabalho parecido com o nosso que eles medem o que é realmente usado. A gente já media instalações e atualizações, mas não o uso das skills em si. O desafio foi descobrir como medir isso sem invadir o trabalho de ninguém.

A resposta foram ganchos do Claude Code e do Codex que registram só três coisas: qual skill foi usada, em que dia e em quantas sessões. Nunca são coletados prompts, respostas, conversas, conteúdo ou nome de arquivos, comandos ou skills de terceiros. Isso segue os princípios de necessidade e transparência da LGPD: coletar o mínimo para a finalidade e deixar claro o que é coletado.

A transparência é concreta. A pessoa vê um aviso na primeira vez e tem um comando que mostra exatamente o que sai da máquina dela, como o VS Code e o Homebrew fazem com a telemetria deles. Com esses dados, vamos aposentar as skills que ninguém usa e priorizar melhorias nas que mais rodam, que é justamente o que a Anthropic recomenda para skills em empresas.

O que Deu Errado: o Custo do Rigor Fica com Quem Constrói

Suportar duas ferramentas de IA em três sistemas operacionais tem um preço, e ele aparece nos bugs. Quatro deles merecem ser contados.

  • O travessão que virou "erro de rede". O Windows PowerShell 5.1 lê scripts sem BOM (uma marca no início do arquivo que indica a codificação) usando a página de código "ANSI" antiga, como a documentação da Microsoft explica. Um único travessão (o caractere U+2014) num comentário quebrava a leitura do script inteiro, e o erro chegava para o usuário como "erro de rede". Ou seja, o bug ainda mentia sobre a própria causa.
  • O bash antigo do macOS. O macOS ainda traz o bash 3.2, e a explicação mais aceita é a licença: as versões novas são GPLv3. Arrays associativos só existem a partir do bash 4.0, e o sync usava um. Resultado: no Mac, ele quebrava em silêncio.
  • O alarme falso de "versão sem assinatura". A assinatura acontece segundos depois do merge, e, às vezes, a leitura desse commit se perdia no backend. Aí disparava o e-mail de alerta para todo mundo. A correção foi uma carência de 30 minutos e uma releitura da branch antes de alertar. Alarme que dispara à toa ensina as pessoas a ignorar alarme.
  • O chaveiro que assinava sozinho. No Linux, o chaveiro da sessão desbloqueava a chave de assinatura para qualquer processo. Na prática, qualquer programa rodando na minha sessão poderia assinar sem pedir a senha. A assinatura passou a usar um agente SSH isolado, só para ela.

Todos eles reforçam a mesma lição: o rigor custa, e esse custo tem que ficar com quem constrói.

Por Onde Começar a Governança de Skills no Seu Time

Em cerca de quatro meses, do primeiro commit em junho ao big bang de outubro, foram 382 commits e 186 versões. Hoje são 55 skills em produção chegando a 7 equipes, todas assinadas, revisadas e testadas. Conto esses números com o mesmo cuidado do post anterior: eles são resultado de um time que topou frear as entregas para arrumar a base, e de líderes que publicam skills mesmo sem ser técnicos.

Você não precisa de tudo isso para começar. Se você compartilha skills ou prompts com o seu time, o mínimo de software é este:

  • Versione. Skill em repositório, com histórico. Se ninguém sabe qual versão está rodando na máquina de quem, você não tem uma skill, tem várias.
  • Tenha alguém que revisa. Quem escreve não aprova. Pode ser um PR com uma regra simples na branch principal.
  • Saiba quem recebe o quê. Mesmo que seja só uma pasta por equipe, no começo.
  • Deixe a assinatura para depois, mas não deixe para nunca. Ela entra quando a skill passa a chegar em muitas máquinas, e o ssh-keygen que você já tem resolve.

E, desde o primeiro dia, a simplicidade para quem usa. Se eu tiver que escolher entre uma regra a mais para mim e um passo a mais para quem usa, fico com a regra a mais para mim.

Conclusão

Uma skill é software no momento em que sai da sua máquina. Tratá-la assim significa responder três perguntas: quem recebe, qual versão e quem garante que ninguém alterou o que foi aprovado. No Hub de Skills, as respostas são SSO com grupos, os arquivos como fonte da verdade e uma assinatura que só um humano faz.

O que torna isso viável é o que quem usa não vê. A pessoa faz login uma vez e pronto; a complexidade fica com a equipe que constrói, e até a parte difícil de publicar virou uma conversa com uma skill. Se você está começando a compartilhar skills com o seu time, comece pelo versionamento e pela revisão, e pergunte a cada decisão: isso pesa para mim ou para quem usa? No próximo post da série, quero mostrar como uma dessas skills virou um sistema inteiro.

Referências