Este é um guia prático sobre como fazer isso corretamente.
Resumindo: Criar uma equipe com habilidades compartilhadas é o primeiro passo mais fácil para se tornar uma empresa nativa de IA. Este é um guia prático sobre como fazer isso corretamente.
Introdução
As habilidades são um dos aspectos mais poderosos dos fluxos de trabalho de agentes e se tornaram o formato padrão para o armazenamento do conhecimento institucional. Pense nas habilidades como os Procedimentos Operacionais Padrão (POPs) que seus agentes podem de fato executar.
Este guia abrange tudo o que você precisa saber para desenvolver suas próprias habilidades, incluindo uma biblioteca de habilidades compartilhada que se potencializa dentro da sua empresa.
Este guia aborda o que são habilidades, como usá-las (com segurança), opções para implementar uma capacidade de compartilhamento de habilidades em sua equipe ou empresa, como gerenciar habilidades e de onde vem o verdadeiro valor.
O que são habilidades e por que compartilhá-las é importante.
Uma habilidade de agente é um pacote portátil de conhecimento procedimental — pense nelas como instruções, roteiros, referências, diretrizes, etc., que ensinam um agente a executar uma tarefa específica de forma confiável.
Basicamente, pegue qualquer tarefa repetitiva – “fazer com que este código esteja em conformidade com nossos padrões”, “fechar os livros contábeis do mês”, “redigir este texto de acordo com a voz da nossa marca” – e a habilidade descreve em detalhes como essa tarefa deve ser executada.
O maior desafio é que as habilidades geralmente são criadas individualmente e não são tratadas como um ativo ou recurso essencial dentro de uma empresa. Isso significa que o trabalho realizado para criar uma habilidade não é aproveitado por todas as pessoas que deveriam usá-la. Ou pior, várias pessoas reinventam a roda, criando diversas versões da mesma habilidade.
O compartilhamento transforma habilidades em ativos corporativos versionados e facilmente localizáveis, mudando o foco do jogo de individual para colaborativo. É aqui que você obtém vantagem como equipe ou empresa, e geralmente é a melhoria mais simples que você pode implementar no caminho para se tornar uma empresa nativa de IA.
O argumento de Hiten Shah de que a primeira estratégia de IA de toda empresa deve ser uma biblioteca de habilidades, a definição de Atlan de que “as habilidades fazem pelo conhecimento procedimental o que as funções fizeram pela lógica” e o conceito de Inteligência Própria do Índice de Tendências de Trabalho da Microsoft convergem para o mesmo ponto a partir de ângulos diferentes: sua biblioteca de habilidades privada é uma forma de inteligência própria que se multiplica.
Uma ressalva importante: o “fosso” não é o arquivo em si. Um arquivo SKILL.md é trivialmente simples. O recurso duradouro é a biblioteca privada, juntamente com o loop de avaliação e telemetria que a envolve. Mais detalhes na seção 6.
O padrão de competências abertas
O formato Agent Skills foi criado pela Anthropic – anunciado em 16 de outubro de 2025 em seu blog de engenharia, e lançado como um padrão aberto independente em 18 de dezembro de 2025 em agentskills.io, com um validador de referência (skills-ref) em github.com/agentskills/agentskills.
O formato:
Uma pasta com o nome da habilidade
É necessário um arquivo SKILL.md: cabeçalho YAML + instruções em Markdown. Apenas o nome e a descrição são campos obrigatórios; o nome deve corresponder à pasta, somente em letras minúsculas e com hífen; a descrição deve ter até 1.024 caracteres.
Scripts opcionais/, referências/, recursos/
Informações iniciais opcionais: licença, compatibilidade, metadados e uma lista experimental de ferramentas permitidas.
O mecanismo que torna viáveis as bibliotecas em escala organizacional é que os agentes carregam apenas o nome e a descrição na inicialização (cerca de 100 tokens por habilidade), e então extraem o conteúdo completo do arquivo SKILL.md somente na ativação (recomendado menos de 5.000 tokens), lendo os arquivos agrupados apenas sob demanda. Isso significa que você pode ter centenas de habilidades sem esgotar a janela de contexto — algo extremamente importante para empresas que buscam controlar os custos com tokens.
Esse formato foi adotado por praticamente todas as principais plataformas de agentes e arquitetura de agentes, então o risco de você investir tempo na criação de uma biblioteca de habilidades apenas para ver algo novo surgir e substituí-la é muito pequeno.
Segurança – leia isto antes de construir qualquer coisa
As skills representam uma superfície de ataque muito real se você as baixar da internet sem as devidas precauções. Como as skills são essencialmente instruções que seus agentes seguem, ocultar intenções maliciosas dentro delas é uma ameaça real.
A taxa básica de habilidades deficientes é alta, com base em dois estudos independentes:
Estudo ToxicSkills da Snyk (5 de fevereiro de 2026, n=3.984 habilidades do ClawHub e skills.sh): 37% apresentavam pelo menos uma falha de segurança de qualquer gravidade e 76 foram confirmadas como maliciosas.
Liu et al., “Agent Skills in the Wild” (acadêmico, n=31.132 habilidades): 26% continham pelo menos um padrão perigoso. A descoberta mais reutilizável: habilidades que agrupam scripts executáveis têm 2,0 vezes mais probabilidade de serem vulneráveis do que habilidades que contêm apenas instruções.
Dois pontos importantes que devem nortear sua arquitetura:
A injeção de código está presente no próprio texto do arquivo SKILL.md. Não é necessária a execução de código — a instrução maliciosa só precisa entrar na janela de contexto do agente.
As habilidades atuam dentro do raciocínio do modelo, invisíveis para a observabilidade em nível de API que monitora as chamadas da ferramenta MCP. Seu monitoramento de agentes atual pode não detectar o comportamento das habilidades.
Ok, isso pode parecer assustador, mas as implicações práticas são bem óbvias: trate as skills exatamente como pacotes de código aberto (analise, revise, fixe), aplique um escrutínio extra a tudo que tenha uma pasta scripts/, nunca importe automaticamente de marketplaces públicos para a biblioteca interna sem revisão e exija que o autor não seja o revisor em todas as aprovações.
Pessoalmente, eu uso o SkillSpector da Nvidia quando baixo habilidades externas.
Melhor ainda, desenvolva as habilidades você mesmo e evite baixar habilidades de terceiros.
Opções de implementação
A. Repositório privado no GitHub (ponto de partida mais fácil)
Um repositório privado de pastas de habilidades é gratuito, possui controle de versão, funciona com todos os agentes que leem o padrão e permite a revisão de pull requests como forma de governança, sem custos adicionais. Adicione CI para verificação de lint de YAML e varredura de segredos, e todo o processo fica concluído rapidamente.
A distribuição é feita através de qualquer convenção de ferramenta utilizada (caminhos .claude/skills/, lojas de plugins, vários instaladores de linha de comando) – a especificação em si é agnóstica em relação aos mecanismos de instalação.
O fluxo é o seguinte: rascunhos individuais -> revisão do PR -> mesclagem -> todos recebem na próxima sessão. E qualquer pessoa pode simplesmente pegar o link interno do GitHub, passar para seu agente e dizer “instale isso”.
A desvantagem: gerenciar habilidades dessa forma pode levar a um cemitério de habilidades obsoletas se ninguém for responsável por elas e pela sua manutenção, então o melhor é nomear um responsável pela manutenção de cada habilidade desde o primeiro dia.
B. Registros corporativos (se você quiser ferramentas de verdade)
Se você busca uma opção mais robusta e específica para ajudar equipes/organizações a gerenciar habilidades, estas podem ser do seu interesse. Os principais benefícios são recursos de digitalização, assinatura, controle de acesso e auditoria para habilidades compartilhadas.
Existem várias opções atualmente. Não afirmo saber quais são as melhores, mas aqui está o panorama atual para você explorar:
Registro de Habilidades de Agentes JFrog – “Modelo de Consumo de Confiança Zero” em duas fases com varredura de código malicioso e envenenamento de prompts, evidências de atestação e assinatura opcional.
Registro de Habilidades TrueFoundry – Escreva uma vez, conecte-se a todos os agentes; carregamento sob demanda; interface gráfica ou linha de comando; controle de versão e acesso.
Agentman – Níveis de equipe/compartilhados, permissões granulares, incluindo “Somente uso” (invocar uma habilidade sem ler seu código interno – realmente útil para proteger detalhes de processos proprietários).
SkillRepo – Biblioteca gerenciada com classificação de habilidades, escopo de versão por repositório e rastreamento de conformidade.
Scalefocus skilly – Opção auto-hospedada para “um ambiente centralizado para cada habilidade do agente”.
Agent Skill Harbor – Opção de código aberto com licença MIT, nativa do GitHub, catálogo sem servidor com um scanner e classes recomendadas/desencorajadas/proibidas.
C. Implementações reais de empresas (basta copiá-las)
Às vezes, você só quer replicar o que outras boas empresas estão fazendo. Felizmente, muitas empresas publicaram suas configurações em fóruns ou blogs corporativos, então há muita coisa de onde se inspirar.
A Anthropic, em sua própria publicação sobre como utiliza habilidades, descreve centenas de habilidades em uso interno ativo, distribuição em dois níveis (repositório Git que evolui para um marketplace interno de plugins), nove categorias internas de habilidades e telemetria do gancho PreToolUse, que mede quais habilidades são acionadas, quais são populares e quais são subutilizadas. Essa última parte é importante: é o único caso observado de uma empresa instrumentando o ciclo de habilidades e é o padrão a ser copiado.
Red Hat – coleções de agentes com 7 pacotes de habilidades, aproximadamente 68+ habilidades que abrangem conhecimento operacional de RHEL/OpenShift/Ansible. Seu gerenciador de pacotes Lola agrupa habilidades, comandos, instruções de agentes e servidores MCP em módulos versionados. Não há dados de adoção publicados.
WorkOS – workos/skills usa um padrão de roteador-skill bastante sofisticado (2 habilidades de roteador em mais de 40 arquivos de referência abrangendo AuthKit/SSO/RBAC). Usos em produção, conforme o estudo de caso da ZenML: um instalador de linha de comando que detecta frameworks e configura o AuthKit, relatórios de recrutamento, revisão de código e automação Slack-to-Linear. Sua prática de avaliação verificada é a comparação de linha de base – o mesmo prompt com e sem a habilidade, e a pontuação da diferença. Parece complexo, mas basta jogar os artigos no seu LLM e dizer “crie um plano como este para mim”.
CloudQuery – baseado no relato de Joe Karlsson sobre um repositório de habilidades pessoais que se tornou uma ferramenta interna padrão para uma equipe de marketing não técnica. Suas lições: disciplina CLAUDE.md em primeiro lugar, nomeie um responsável pela manutenção e ele deixa claro que não mediu nada rigorosamente. Uma visão refrescantemente honesta.
Operações – avaliações, versionamento, ciclo de vida
Caso ainda não tenha ouvido falar disso, tudo gira em torno das avaliações. É isso que diferencia uma biblioteca de habilidades realmente eficaz, que desenvolve a inteligência internamente, de uma que se torna apenas um diretório obsoleto de itens que talvez algumas pessoas usem ocasionalmente.
Avaliações
As melhores práticas oficiais da Anthropic para criação de habilidades prescrevem o desenvolvimento orientado por avaliação: execute o agente sem a habilidade para encontrar a lacuna, crie pelo menos 3 cenários de teste, estabeleça a linha de base sem a habilidade, escreva instruções mínimas e itere em relação à linha de base. Toda equipe séria usa avaliações para se autoavaliar; caso contrário, você estará apenas operando com base em impressões.
Duas dicas rápidas: a eficácia das habilidades depende do modelo (teste em diferentes modelos e níveis, não apenas no padrão) e tente usar modelos diferentes para design e teste. Caso contrário, você pode descobrir que “Claude A” cria algo que “Claude B” testa como perfeito, mas que não funciona tão bem no ChatGPT. É melhor usar Claude para o design e o ChatGPT para os testes, a fim de descobrir as nuances.
Controle de versão e ciclo de vida
As duas melhores estruturas que encontrei para ajudar na gestão de competências são:
Ciclo de vida de 7 etapas da Atlan: # Um guia de governança para profissionais em 2026
AWS Well-Architected Agentic AI Lens (AGENTOPS03-BP01): Defina um ciclo de vida de agente com propriedade, testes e governança claramente definidos por especialistas no assunto.
Basta ler estes documentos ou, pelo menos, fornecê-los aos seus agentes como guias de referência.
Medição – o estado da arte honesto
Não encontrei uma métrica rigorosa, baseada em metodologia, para avaliar a adoção ou a economia de tempo no compartilhamento interno de habilidades. O mais próximo de um método concreto é a pontuação delta com/sem habilidades do WorkOS e a telemetria de hooks da Anthropic. Se você incorporar a instrumentação de uso à sua biblioteca, provavelmente terá dados melhores do que os que toda a indústria publica atualmente; esse é o caminho para se manter na vanguarda dessa área.
Habilidades versus MCP, e onde realmente está a vantagem competitiva.
Segundo a própria definição da Anthropic: o MCP conecta o agente aos dados e sistemas; as habilidades ensinam o que fazer com eles. O acesso fornece contexto, as habilidades fornecem discernimento.
Na prática, a regra é que qualquer coisa que exija dados em tempo real ou ações autenticadas é um servidor MCP, qualquer coisa que codifique procedimentos ou padrões é uma habilidade, e habilidades consolidadas frequentemente acionam ferramentas MCP durante o procedimento.
Sobre o fosso: o arquivo de habilidades é o artefato que todos podem ver, então é tentador tratar a biblioteca como o ativo. O que compõe o sistema é privado: a biblioteca mais o conjunto de testes que comprova o funcionamento de cada habilidade, a telemetria que mostra quais habilidades realmente são ativadas e o ciclo de melhoria que retroalimenta o uso nas revisões. Esse ciclo é o motivo pelo qual a Anthropic implementa habilidades com ganchos e por que os fornecedores de registro que mencionei em 4B estão tentando controlar o plano de controle — o fosso tem tudo a ver com os dados.
Roteiro para começar
Adote o padrão aberto SKILL.md. Não tente usar outras soluções criativas.
Crie um repositório Git privado. A revisão de pull requests será sua governança inicial. Uma maneira muito fácil de começar.
Selecione de 5 a 10 habilidades de alto valor de especialistas da área — pessoas cujo conhecimento, de outra forma, seria perdido. Nomeie um responsável por cada habilidade.
Elabore avaliações desde o primeiro dia: linha de base sem nenhuma habilidade, 3 ou mais cenários por habilidade, repita a avaliação a cada mudança. Esta é a etapa que a maioria das pessoas ignora e a etapa mais importante.
Analise tudo (use o SkillSpector da Nvidia se estiver usando habilidades externas) e preste atenção especial aos scripts que agrupam as habilidades. O autor nunca é o revisor.
Utilize instrumentos (telemetria de gancho) antes de escalar. Você não pode controlar o que não vê, e terá dados de adoção melhores do que a maioria das empresas que usam habilidades.
Avalie as ferramentas de registro externas somente quando o volume ou a conformidade assim o exigirem; até lá, mantenha-se fiel a uma solução interna.
As habilidades são incrivelmente simples, porém poderosas, e representam a maneira mais fácil de aprimorar uma equipe com IA. Não há desculpas para não dar esse passo.
Se você implementou habilidades compartilhadas na sua empresa, adoraria saber mais sobre isso. E se precisar de ajuda para fazer isso, minhas mensagens diretas estão abertas.
Post Original: https://x.com/KSimback/status/2092565062850318824
