Como usar habilidades da OpenAI com segurança

Um fluxo de trabalho reutilizável para agentes pode começar como um prompt, mas a repetição logo expõe os limites de copiar instruções entre conversas. Etapas importantes são omitidas, os formatos de saída se desviam e o raciocínio por trás de um processo se torna difícil de revisar. Uma habilidade da OpenAI resolve esse problema ao reunir instruções operacionais e materiais de apoio em uma pasta estruturada que pode ser versionada e inspecionada.

Essa conveniência não deve ser confundida com uma barreira de segurança. Uma habilidade pode influenciar quais ferramentas um agente seleciona, quais arquivos lê, quais scripts executa e quais serviços externos contata. Portanto, a adoção segura exige dois tipos de revisão: avaliar o fluxo de trabalho como conhecimento legível e avaliar suas possíveis ações como entrada da cadeia de suprimentos de software.

Este guia explica o formato, seu lugar dentro dos plugins da OpenAI, os limites reais da portabilidade e um processo prático para decidir se uma habilidade deve ficar em experimentos pessoais ou em um ambiente de produção aprovado.

Entenda a unidade que você está instalando

A especificação aberta de Habilidades de Agentes define uma habilidade como um diretório centrado em um arquivo SKILL.md. Esse arquivo usa metadados YAML para campos como nome e descrição da habilidade, seguidos de instruções em Markdown. Diretórios opcionais podem conter scripts, referências, ativos, modelos, esquemas ou outros recursos necessários ao fluxo de trabalho.

Essa estrutura é deliberadamente modesta. O nome e a descrição ajudam um agente compatível a identificar quando a habilidade pode ser aplicável. As instruções completas podem ser carregadas quando o fluxo de trabalho é ativado, enquanto recursos de apoio maiores permanecem disponíveis até serem necessários. Esse carregamento progressivo permite manter muitos procedimentos especializados acessíveis sem inserir todas as instruções em todas as conversas.

Uma habilidade, portanto, é mais do que um prompt salvo. Ela pode definir entradas, etapas ordenadas, evidências obrigatórias, restrições de saída, condições de falha e verificações de aceitação. Uma habilidade de revisão pode exigir detecção de framework, execução de testes, verificações de segurança e um relatório fixo. Uma habilidade de publicação pode exigir metadados completos, fontes verificadas, procedência das imagens e validação antes do lançamento.

O formato também separa a capacidade geral do modelo do procedimento local. Especialistas no assunto podem expressar seu julgamento em instruções legíveis, enquanto engenheiros podem adicionar scripts determinísticos quando o comportamento exato for importante. Ambas as partes podem ser revisadas no controle de versão. A orientação da OpenAI Academy sobre habilidades apresenta essa reutilização como uma forma de deixar de explicar o mesmo processo recorrente desde o início.

Trate os metadados de descoberta como roteamento executável

A descrição em SKILL.md não é um texto decorativo. Muitas vezes, ela ajuda o agente a decidir se a habilidade corresponde à tarefa atual. Uma descrição ampla demais pode encaminhar trabalhos não relacionados para o fluxo; uma descrição vaga pode impedir a ativação quando a habilidade é necessária. Qualquer uma dessas falhas pode mudar o comportamento do agente antes que uma pessoa veja as instruções detalhadas.

Revise o nome e a descrição com o mesmo cuidado dedicado às etapas. Eles devem indicar o que a habilidade faz, as situações que a acionam e exclusões relevantes. Se um fluxo de trabalho edita planilhas, mas não deve controlar uma sessão ativa do Excel, esse limite deve constar na linguagem de descoberta. Se ele só pode publicar conteúdo após aprovação explícita, essa condição precisa ser inequívoca.

Depois, inspecione a hierarquia de instruções. Uma habilidade não adquire autoridade apenas por ser ativada. A intenção do usuário, as políticas da plataforma, as restrições do ambiente isolado, as regras do projeto e os requisitos de aprovação continuam válidos. Instruções que mandam o agente ignorar esses controles são motivo para rejeitar o pacote, não um atalho para contorná-los.

Separe uma habilidade de seu contêiner de plugin

O catálogo de habilidades original da OpenAI foi descontinuado e direciona os desenvolvedores para exemplos e orientações atuais sobre plugins. Essa é uma mudança de distribuição, não uma evidência de que o formato subjacente das habilidades desapareceu. A unidade instrucional principal pode continuar sendo uma pasta com SKILL.md, enquanto o produto instalável passa a ser um plugin.

Segundo o guia de empacotamento de plugins da OpenAI, um plugin deve ter em sua raiz um manifesto obrigatório .codex-plugin/plugin.json. O pacote pode incluir habilidades junto com definições de servidores MCP, aplicativos, comandos, ganchos, metadados de agentes e ativos. Um plugin composto apenas por uma habilidade continua sendo possível quando as instruções e os recursos incluídos são suficientes.

A distinção é útil ao definir o escopo. Uma habilidade descreve um procedimento repetível. Um plugin pode fornecer a capacidade mais ampla necessária para distribuir e operar esse procedimento, incluindo ferramentas externas, requisitos de autenticação, elementos de interface e metadados do pacote. O plugin é a fronteira de instalação; a habilidade permanece como um componente dentro dele.

Para novas distribuições voltadas à OpenAI, siga o caminho atual dos plugins em vez de criar um processo de instalação em torno do catálogo descontinuado. Sempre que for prático, preserve o próprio fluxo de trabalho em uma habilidade compatível com padrões. Isso mantém as instruções duráveis separadas da integração específica do ambiente e facilita revisões ou migrações futuras.

Seja preciso sobre a portabilidade

Markdown simples, um esquema obrigatório pequeno e pastas de recursos opcionais tornam as habilidades mais fáceis de mover entre agentes compatíveis. A especificação fornece uma estrutura comum, e arquivos legíveis funcionam bem com práticas conhecidas de controle de versão e revisão de código. Isso representa uma portabilidade significativa na camada de instruções.

Não é uma garantia de que a mesma pasta se comportará de forma idêntica em todos os lugares. Os ambientes podem interpretar metadados opcionais de maneiras diferentes. Nomes de ferramentas, sistemas operacionais, dependências, caminhos do sistema de arquivos, conectores, limites de contexto e fluxos de aprovação podem variar. Um fluxo que chama um comando local não funcionará automaticamente em um ambiente limitado ao navegador. Um fluxo que precisa de dados privados falhará sem um conector disponível e autorização adequada.

Avalie a portabilidade em camadas:

1. Procedimento principal: Outro ambiente compatível consegue entender os objetivos, a sequência, as entradas e o contrato de saída?
2. Recursos incluídos: As referências a arquivos são relativas, documentadas e estão disponíveis com a habilidade?
3. Premissas de execução: Comandos, pacotes, requisitos de sistema operacional e mensagens de falha estão explícitos?
4. Ações conectadas: Quais ferramentas, métodos de autenticação e interfaces são específicos de um ambiente ou plugin?
5. Resultados comportamentais: O fluxo é ativado e conclui tarefas representativas de maneira consistente em cada ambiente pretendido?

Um bom projeto mantém o procedimento durável na habilidade e coloca conectores específicos do produto, metadados de interface, permissões e comportamento de instalação no pacote ao redor. Isso não torna todas as ações portáveis, mas impede que detalhes incidentais de integração obscureçam o conhecimento reutilizável.

Revise permissões pelas consequências, não pelo tipo de arquivo

Markdown legível é mais fácil de inspecionar do que um binário opaco, mas as instruções ainda podem provocar o uso de ferramentas com consequências. A pergunta relevante não é apenas se o pacote contém código. Pergunte o que ele pode persuadir ou instruir o agente a fazer.

Associe cada capacidade solicitada a uma etapa concreta. O acesso de leitura a arquivos pode ser necessário para analisar documentos, mas o acesso amplo de gravação não. O acesso à rede pode ser justificável para um fluxo de pesquisa, enquanto o acesso a credenciais ou serviços não relacionados não é. Uma ferramenta capaz de enviar mensagens, publicar conteúdo, alterar sistemas de produção ou excluir dados merece uma barreira de confirmação explícita.

Scripts exigem inspeção direta. Verifique todos os arquivos executáveis e de apoio, não apenas SKILL.md. Identifique comandos, dependências, variáveis de ambiente, destinos de rede, caminhos de arquivos e qualquer operação que altere o estado externo. Prefira o menor conjunto de permissões que conclua a tarefa pretendida e teste com dados descartáveis ou em um ambiente isolado antes de permitir acesso a sistemas valiosos.

Examine também as entradas indiretas. Referências, páginas obtidas e dados conectados podem conter instruções próprias. Um fluxo seguro deve tratar esses materiais como conteúdo a ser analisado, não como autoridade de prioridade superior. As instruções do pacote devem indicar onde entra conteúdo não confiável e como o agente deve tratá-lo.

Gerencie habilidades como dependências da cadeia de suprimentos

A popularidade de um repositório público não comprova revisão de segurança, confiabilidade em produção nem adoção bem-sucedida. Uma habilidade maliciosa ou comprometida pode tentar obter segredos, alterar arquivos, contatar um serviço inesperado ou ampliar seu escopo por meio de scripts e referências. Um fluxo benigno pode se tornar arriscado após uma atualização ou ficar obsoleto quando uma API, uma interface de produto ou uma regra de conformidade muda.

Registre a procedência antes da instalação: publicador, repositório, revisão ou versão exata, licença, data da revisão e arquivos aprovados. Fixe a revisão analisada quando o método de instalação permitir. Não aceite uma atualização apenas por ser mais recente; inspecione as diferenças, execute novamente os casos de avaliação e reavalie qualquer mudança de permissão.

Os sinais do ciclo de vida também importam. O antigo repositório de habilidades da OpenAI continua acessível, embora seu aviso informe que foi descontinuado. Resultados de busca e links salvos podem sobreviver à rota de instalação preferida. Verifique o aviso do repositório e a documentação atual em vez de presumir que um pacote acessível ainda recebe manutenção. Defina como uma equipe desativará, substituirá ou reverterá uma habilidade se sua fonte for comprometida ou seu comportamento mudar.

Para uso organizacional, a responsabilidade deve ser explícita. Alguém deve responder por atualizações, compatibilidade, casos de teste e retirada. Armazene o pacote aprovado em um local controlado, mantenha uma trilha de auditoria e separe os experimentos do conjunto que os agentes podem ativar no trabalho de produção.

Faça uma avaliação em etapas antes da aprovação

Um diretório válido apenas comprova que os arquivos estão organizados corretamente. Ele não mostra que a ativação é confiável, que as instruções são seguras ou que os resultados são úteis. Use uma avaliação em etapas, com tarefas representativas e condições claras de aprovação.

1. Estabeleça o propósito e os limites

Registre a tarefa recorrente, os usuários pretendidos, as entradas aceitas, as saídas esperadas e as ações que devem permanecer fora do escopo. Decida se instruções melhores são suficientes ou se o fluxo realmente precisa de um plugin com ferramentas e serviços conectados. Comece com a menor capacidade que resolva o problema.

2. Audite todos os componentes do pacote

Leia o manifesto, SKILL.md, scripts, referências, ativos e configurações. Verifique se os links e as dependências correspondem ao propósito declarado. Procure acesso a segredos, comandos destrutivos, chamadas de rede inesperadas, caminhos locais absolutos, downloads ocultos e instruções que contornem aprovações ou políticas.

3. Crie um mapa explícito de permissões

Liste cada ferramenta e fonte de dados, a operação que ela permite, se o acesso é somente leitura ou permite alterações e quando a confirmação humana é necessária. Remova capacidades sem uma etapa correspondente no fluxo. Use credenciais limitadas e recursos isolados durante a avaliação.

4. Teste o roteamento e o comportamento normal

Crie tarefas representativas que devem acionar a habilidade e tarefas semelhantes que não devem. Verifique se a descrição encaminha o trabalho corretamente. Nos casos positivos, verifique as etapas obrigatórias, as evidências, o formato de saída e as verificações de aceitação, em vez de julgar apenas se a resposta final parece plausível.

5. Teste o comportamento diante de falhas e recusas

Experimente entradas ausentes, ferramentas indisponíveis, arquivos inválidos, instruções conflitantes e solicitações fora do escopo. A habilidade deve parar com clareza, preservar os dados e solicitar a decisão necessária, em vez de improvisar autoridade. Confirme que conteúdo não confiável não consegue redefinir silenciosamente o fluxo.

6. Teste a portabilidade onde ela for alegada

Execute os mesmos casos em todos os ambientes pretendidos. Registre quais partes das instruções principais são transferidas e quais integrações exigem adaptação. Não classifique um plugin completo como portável quando apenas sua habilidade interna é compatível com padrões.

7. Aprove uma revisão e monitore mudanças

Fixe a versão avaliada, registre os resultados e as limitações conhecidas, nomeie um responsável e defina um intervalo de revisão. Reavalie após mudanças em instruções, scripts, permissões, dependências, ferramentas ou comportamento do ambiente. Mantenha um caminho de reversão e um processo claro de retirada.

Use a menor camada confiável

As habilidades são valiosas porque tornam o conhecimento operacional recorrente visível, reutilizável e passível de revisão. Os plugins acrescentam uma camada prática de distribuição quando o fluxo precisa de metadados de instalação, ferramentas, autenticação, interfaces ou controles organizacionais. Nenhuma das camadas é segura por padrão, e nenhuma elimina a necessidade de permissões impostas pelo ambiente.

A abordagem durável é manter o procedimento principal legível, isolar integrações específicas de produtos, conceder apenas o acesso exigido por cada etapa e testar o comportamento, não apenas a sintaxe. Quando procedência, permissões, casos de avaliação, responsabilidade e reversão são documentados em conjunto, uma habilidade se torna um fluxo governado em vez de um pacote de instruções não examinado.