Você encontra uma skill excelente. Instala.

Encontra outra que parece fazer a mesma coisa, mas tem uma etapa de revisão melhor. Instala também.

Depois aparece uma terceira, com exemplos mais claros e uma descrição que parece ter sido escrita para o seu problema. Pronto: agora você tem mais opções e uma pergunta a mais.

Qual delas eu deveria usar?

Uma skill é um pacote de instruções e recursos reutilizáveis para orientar uma classe de tarefa. O agente de IA é o sistema que recebe contexto, escolhe etapas e usa ferramentas para executá-la. Ter várias skills disponíveis deveria ampliar a capacidade do agente. Mas, sem critério, pode ampliar também a confusão.

Foi pensando nessa gestão que construí o I-9 Skills, um projeto público da I-9.ai para descobrir, criar, avaliar, organizar, manter e distribuir skills. Estou utilizando a ferramenta no meu ambiente local e abri o projeto para quem quiser experimentar, avaliar suas próprias skills e contribuir com melhorias.

Também criei o site do I-9 Skills, disponível em português, inglês e espanhol, para apresentar a biblioteca. O código e a documentação estão no repositório público.

Minha intenção é aproveitar o que existe de melhor nas skills que encontramos por aí — a crème de la crème — e transformar essas contribuições em pacotes melhores para um trabalho definido. Escolher o que funciona, entender por que funciona, combinar quando fizer sentido e conseguir melhorar depois.

Porque instalar uma skill é fácil. Difícil é saber se ela continua sendo a certa.

Três skills para o mesmo trabalho. Nenhuma decisão clara

Imagine que você quer revisar uma aplicação. Uma skill prioriza arquitetura. Outra procura problemas de segurança. Uma terceira também se chama “revisão”, mas foi escrita para verificar estilo de código.

Os nomes parecem equivalentes. As entregas não são.

Se o agente escolher pelo rótulo mais parecido com o pedido, você pode receber uma resposta impecável para uma pergunta que não fez. Se carregar tudo, pode juntar critérios que competem entre si e gastar contexto — o material disponível para orientar o modelo — sem esclarecer o trabalho.

O I-9 Skills trata descoberta e roteamento como responsabilidades diferentes. Descobrir é encontrar e qualificar candidatos. Rotear é escolher o procedimento adequado ao objetivo e às restrições daquela execução.

A entrada skill-routing pode recomendar uma skill, uma sequência curta com entregas distintas, uma lista limitada de alternativas que precisam de esclarecimento ou none, quando nenhuma for necessária. O catálogo ajuda a encontrar candidatos; a escolha exige ler o SKILL.md, o arquivo com as instruções e os limites do pacote.

Isso retoma uma questão que já explorei sobre skills disponíveis que não chegam ao trabalho: a pessoa não deveria precisar decorar um menu invisível para a capacidade certa aparecer.

A skill que faz tudo, inclusive o que você não pediu

Outro cenário: você pede uma análise, mas a skill também contém pesquisa, implementação, testes, instalação e publicação. Tudo no mesmo pacote, com uma descrição abrangente o bastante para servir em quase qualquer conversa.

Ela virou um pequeno departamento. Só esqueceu de definir os cargos.

Isso pode tornar sua seleção ambígua: o procedimento inteiro talvez não se aplique, embora uma parte seja útil. Também dificulta perceber onde termina a análise e começa uma ação que precisa de autorização.

No I-9 Skills, uma responsabilidade por skill e uma entrega principal revisável orientam o desenho. skill-design delimita o trabalho; skill-authoring produz o pacote; skill-evaluator avalia o comportamento. Auditoria e refatoração — reorganização que preserva o que precisa continuar funcionando — ajudam a identificar sobreposições e propor divisões.

A ideia é permitir que uma peça seja escolhida, testada ou corrigida sem obrigar você a reescrever o conjunto inteiro. É também por isso que a biblioteca usa meta-skills: skills cujo trabalho é cuidar de outras skills e de sua coleção.

No outro agente, a mesma skill virou outra coisa

Considere uma skill instalada no projeto, outra cópia no ambiente do usuário e uma adaptação em outro agente. Todas carregam o mesmo nome. Uma recebeu uma correção. Outra preservou uma regra antiga. A terceira ganhou uma etapa específica daquele aplicativo.

Quando o comportamento diverge, onde você começa a procurar?

“Mas eu já tinha corrigido isso” vira uma frase pouco útil quando ninguém sabe qual cópia executou o trabalho.

A proposta do projeto combina catálogo, origem e histórico. O catálogo torna a coleção inspecionável; os registros permitem distinguir fontes e revisões, inclusive quando nomes coincidem. Instalação e migração têm responsabilidades próprias, para que mover um pacote não signifique perder seus recursos ou sua procedência.

As skills são escritas em inglês e seguem o formato da especificação Agent Skills. Cada pacote leva sua licença Apache-2.0, referências, recursos e scripts aplicáveis — pequenos programas auxiliares. Esses recursos são encontrados a partir do próprio diretório da skill; os resultados vão para o espaço escolhido por quem solicitou o trabalho.

Essa autossuficiência permite levar o pacote para outro ambiente sem depender de um arquivo esquecido na máquina de quem o criou. Ferramentas e configurações necessárias ainda precisam ser declaradas e preparadas.

A skill nasceu com um contexto limitado. E ficou presa nele

Uma skill pode ter sido ótima para o problema que a originou. Depois aparecem exceções, uma documentação muda, você encontra uma abordagem melhor ou o agente falha em uma situação que ninguém havia previsto.

Se a correção fica apenas na conversa, o próximo agente pode repetir o erro. Se cada tentativa altera a skill sem comparação, fica difícil saber se você melhorou o procedimento ou apenas acomodou o último caso.

É aqui que eu quero gestão de evolução.

skill-evidence-collection organiza evidências; skill-evolution produz uma candidata baseada nelas; skill-optimization trabalha melhorias mensuráveis em iterações delimitadas. A avaliação compara o comportamento com casos e critérios definidos antes do veredito. A decisão de adotar a nova candidata continua sendo uma etapa própria.

Um snapshot, cópia identificável de um estado, ajuda a preservar a versão anterior. skills-snapshot trata criação, verificação e restauração; skills-maintenance-scheduling prepara propostas de manutenção recorrente. Você consegue organizar a revisão e manter um caminho de volta, sem transformar um calendário em autorização para alterar tudo.

Essa é a mesma preocupação de aprender sem reescrever o passado: uma falha pode justificar uma investigação. A investigação precisa sustentar a mudança.

Tem coisa boa em várias skills. Eu preciso escolher só uma?

Nem sempre.

Imagine uma skill com boas perguntas para levantar requisitos, outra com casos de teste úteis e uma terceira que explica bem quando interromper o trabalho. São contribuições diferentes para um mesmo objetivo.

É esse tipo de aproveitamento que quero viabilizar. skills-discovery qualifica as fontes; skill-domain-research pesquisa o assunto em referências confiáveis e no conhecimento de quem responde pelo processo. Quando há contribuições distintas de duas ou mais skills, skills-synthesis organiza o que combinar, o que descartar e por quê.

A síntese não é colar três textos e torcer para o tamanho virar qualidade. É preservar procedimentos úteis, compatibilidade de licenças, referências e limites, resolvendo contradições antes de desenhar a nova skill. Uma única fonte contribuinte pode seguir para o desenho sem uma síntese artificial; a pesquisa do assunto continua necessária.

“O melhor do melhor”, para mim, é essa ambição de selecionar e testar contribuições. Não uma certificação de que encontramos a melhor skill de todo o mercado.

Instalada, esquecida ou acionada na hora errada?

Uma skill pode ficar disponível e nunca ser escolhida. Outra pode aparecer em situações nas quais não deveria. Uma terceira pode ser lida com frequência sem produzir uma entrega útil.

Esses problemas pedem observação. Foi também por isso que trabalhei o projeto com hooks, integrações acionadas por eventos do aplicativo, e telemetria, registros delimitados do que foi observado.

Os hooks de sessão podem fornecer um mapa compacto das skills disponíveis. A observação de leituras é opcional e depende do host, da configuração e do armazenamento escolhido. O adaptador documentado para Claude distingue tentativas e leituras nativas bem-sucedidas; os hooks de Codex fornecem contexto, sem prometer contagem nativa de leituras.

Para investigar consumo e recorrência, é essencial separar as perguntas:

• Foi encontrada ou lida? É um sinal de disponibilidade ou consulta.
• Seu procedimento foi utilizado? É uma declaração de ativação que precisa de registro próprio.
• O trabalho terminou e o resultado foi bom? Conclusão registrada e qualidade avaliada são evidências diferentes.

Os registros de ciclo de vida permitem registrar seleção, ativação e desfechos, com identidade da fonte e limites de cobertura. São sinais informados por quem registra. Uma contagem de leitura não demonstra compreensão; ausência de registro não demonstra ausência de uso.

Isso ajuda a formular perguntas melhores sobre efetividade. Não transforma frequência em qualidade nem faz a skill evoluir sozinha.

Um pacote completo, com identidade para cada peça

A gestão atravessa descoberta, pesquisa, desenho, síntese, autoria, avaliação, segurança, catálogo, evolução, instalação e publicação. Cada responsabilidade tem seu lugar.

As skills seguem orientações e modelos de estrutura para declarar entradas, saídas, limites, recursos e verificações. Os validadores conferem formato e critérios adicionais da coleção. A avaliação comportamental procura erros que um arquivo bem formado não revela.

Há também skill-icon-design, dedicada à criação de ícones. Os pacotes da coleção incluem ícones distintos e metadados de interface para Codex, permitindo sua apresentação visual nos clientes que suportam esse recurso. Ao criar suas próprias skills, o fluxo também pode produzir essa identidade.

Sim, o ícone bonitinho faz parte. Ajuda a reconhecer a peça. Só não substitui descobrir se ela faz o trabalho direito.

O núcleo é agnóstico de agente: não exige um fornecedor específico para seguir os procedimentos. As integrações acrescentam recursos conforme o host, o aplicativo que executa o agente. Há manifestos para Codex, Claude Code e Copilot; descoberta, interface, hooks e permissões precisam ser verificados no ambiente escolhido. Portabilidade do pacote não promete comportamento idêntico em todos os clientes.

Experimente com um problema que você já tem

Você pode consumir o projeto como skills portáteis ou como plugin, que agrega a coleção e suas integrações ao aplicativo. Há ainda uma CLI, interface de comandos no terminal, para catálogo, validação e ferramentas de gerenciamento, além de um servidor MCP, protocolo que conecta aplicativos de IA a ferramentas e recursos.

Para instalar a coleção no projeto, o README usa a CLI externa Skills:

npx skills add i-9-ai/skills --yes

Nesse comando, --yes seleciona as skills disponíveis e dispensa os passos de seleção. A opção --global muda o destino para o usuário. Confira o escopo e o agente escolhido pelo instalador.

Como alternativa, para Codex, com os pré-requisitos do README preparados:

codex plugin marketplace add i-9-ai/skills --ref main
codex plugin add i9-skills@i9-skills
codex plugin list

O guia de instalação por plugin orienta habilitação, atualização e remoção. Reinicie a sessão ou o cliente conforme essa orientação.

A nossa CLI é outro pacote: @i-9.ai/skills. Node.js fornece o ambiente para executar esses programas, e npm gerencia seus pacotes. Com os pré-requisitos publicados preparados, npx permite executar a CLI sem instalação global; a primeira chamada pode baixar o pacote e suas dependências:

npx --yes @i-9.ai/skills --help
npx --yes @i-9.ai/skills catalog overview
npx --yes @i-9.ai/skills catalog read --skill skill-authoring

Esses comandos consultam a coleção incluída na CLI. Não instalam as skills no agente. Para descobrir os pacotes do projeto atual, sem incluir os globais:

npx --yes @i-9.ai/skills context available-skills --project . --no-global

Com as skills disponíveis no seu agente, comece por um pedido delimitado:

Use skills-audit para analisar minha coleção. Identifique skills com responsabilidades sobrepostas, versões divergentes, recursos ausentes e descrições que dificultam escolher o procedimento certo. Mostre as evidências e proponha uma prioridade de melhoria. Não altere arquivos, instale ou publique nada nesta etapa.

Depois escolha uma descoberta da auditoria. Se houver boas contribuições em fontes diferentes, peça um plano de síntese. Se o problema for uma responsabilidade excessiva, peça uma divisão. Se uma skill estiver falhando, leve casos concretos para sua avaliação e evolução.

O projeto é experimental. Quero que você consiga experimentar com um alvo pequeno, preservar o estado anterior e avaliar o resultado no seu ambiente.

Se isso fizer sentido para sua coleção, conheça o I-9 Skills no site, experimente a biblioteca e conte o que encontrou: qual era o problema, qual host utilizou, o que esperava e o que aconteceu. Um exemplo mínimo, sem credenciais, dados pessoais ou material de clientes, ajuda a transformar feedback em melhoria verificável.

Uma boa skill merece ser encontrada, escolhida no contexto certo e melhorada quando a realidade mostra seus limites. Foi para cuidar desse caminho que construí esta biblioteca.

Para se aprofundar

• O modelo é só o motor: situa skills no sistema que envolve o modelo.
• Especificação Agent Skills: explica a estrutura portável de instruções e recursos.

Referências e limites de uso

• Site do I-9 Skills: apresentação pública da biblioteca, no idioma deste artigo.
• Repositório e README: fonte dos comandos, responsabilidades, recursos de interface e caminhos de distribuição. Os pré-requisitos e integrações devem ser conferidos antes de instalar.
• Wiki, especialmente validação e pesquisa de fontes: documenta método e verificações. Conformidade estrutural não certifica qualidade em produção.
• Hooks e evidências de ciclo de vida: delimitam observação, configuração e registros declarados. Não provam ativação por leitura nem efetividade por frequência.
• Pilotos nativos: verificações delimitadas de integração, sem certificação universal de hosts ou de comportamento de modelos.

As situações deste artigo são exemplos ilustrativos dos problemas que motivaram o projeto. Minha utilização local é relato de uso; não substitui uma avaliação independente nem demonstra um ganho quantitativo de produtividade.