Skills para agentes de IA: procedimentos reutilizáveis

Skills para agentes de IA são procedimentos reutilizáveis, guardados em pacotes pequenos e nomeados, que o agente carrega apenas quando a tarefa pede. Em vez de um prompt longo que descreve todas as obrigações, as instruções centrais ficam curtas e cada procedimento recorrente vive em seu próprio arquivo, com gatilho, passos, limites e uma verificação. Assim, o comportamento do agente fica mais fácil de testar, revisar e alterar sem quebrar o que não tem relação com a mudança.

Principais pontos

• Uma skill é um procedimento nomeado, com gatilho, entradas, passos, ferramentas permitidas, formato de saída e condições de parada. Ela é carregada sob demanda, não fica sempre presente.
• Prompts longos se deterioram porque cada edição corre o risco de afetar tarefas que nada têm a ver com a mudança. As skills isolam essas edições.
• Escreva uma skill apenas para um trabalho que se repete e tem uma definição clara de resultado correto. Decisões pontuais de julgamento ficam na conversa.
• Toda skill precisa de um responsável, de um pequeno conjunto de casos de teste e de uma versão. Assim, a atualização é uma mudança revisada, e não uma reescrita silenciosa.
• Skills são conteúdo em que o agente confia. Por isso exigem o mesmo controle de acesso e a mesma revisão de qualquer outra fonte de instruções.

O que é uma skill de agente, na prática?

Pense na skill como o procedimento escrito que você entregaria a um colega novo e competente para uma tarefa específica, como preparar o resumo mensal de um cliente ou conferir a nota de um fornecedor com o pedido de compra. Ela é mais estreita que uma descrição de cargo e mais concreta que uma política. Diz quando usar, o que reunir primeiro, o que fazer e em que ordem, como deve ser o resultado e quando parar e perguntar a uma pessoa.

Uma skill útil tem poucas partes:

• Uma descrição curta que diz ao agente quando a skill se aplica e quando não se aplica.
• As entradas de que precisa e de onde elas vêm.
• Os passos, escritos como ações com um resultado visível em cada um.
• As ferramentas e permissões que o procedimento pode usar, e quais ações estão proibidas.
• O formato de saída, incluindo que evidências o agente deve anexar.
• As condições de parada: as situações em que o agente entrega a decisão a uma pessoa.

A ideia central do desenho é que o agente enxerga só a descrição curta até que a tarefa corresponda a ela. O procedimento completo entra no contexto de trabalho nesse momento. É uma forma do que a área chama de engenharia de contexto: dar ao modelo o menor conjunto de informações que permite executar bem o passo atual. Para entender o que mais disputa esse espaço, veja nosso guia sobre como compactar contexto sem perder decisões importantes.

Por que prompts longos deixam de funcionar quando a empresa cresce?

Um prompt longo costuma começar como uma página sensata de orientações. Depois uma reclamação de cliente acrescenta um parágrafo sobre tom, uma revisão do financeiro inclui uma regra de aprovação, e uma nova ferramenta traz uma nota sobre quando chamá-la. Passados alguns meses, ninguém sabe dizer qual frase produz qual comportamento.

Três problemas decorrem disso.

• Interferência. Uma regra escrita para reembolsos muda, sem aviso, a forma como o agente trata agendamentos, porque as duas estão no mesmo bloco de texto e o modelo lê tudo a cada vez.
• Ausência de fronteira de teste. Quando o prompt inteiro é uma unidade só, você só consegue testar o agente inteiro. Uma pequena edição obriga a rever tudo, e então as pessoas ou pulam a verificação ou evitam editar.
• Responsabilidade difusa. Quem no financeiro conhece a regra de aprovação não consegue alterar com segurança um documento que também contém orientações de tom comercial e caminhos de escalonamento do suporte.

Os textos de engenharia da Anthropic sobre como construir agentes eficazes recomendam começar simples e acrescentar estrutura só onde ela se justifica. Skills são uma forma de acrescentar estrutura sem criar um bloco ilegível. A pergunta certa não é se o seu prompt está longo, mas se você consegue mudar uma tarefa sem temer pelas outras. Nosso artigo sobre prompt engineering ou harness engineering explica por que isso é uma questão de harness tanto quanto de redação.

O que deve virar skill e o que não deve?

Nem toda instrução merece um pacote próprio. Empacotar tem custo: alguém precisa nomear, testar e manter atualizado. Use este guia de decisão.

• Vire skill se o trabalho se repete em um ritmo ou gatilho, como relatórios semanais, entrada de um novo tipo de documento ou uma resposta padrão a um pedido comum.
• Vire skill se existe uma definição clara de resultado correto que um colega consiga conferir.
• Vire skill se hoje pessoas diferentes explicam o procedimento de maneiras diferentes e você quer uma versão acordada.
• Mantenha nas instruções centrais o que vale para quase toda tarefa, como a identidade do agente, o tom e a regra de parar quando houver dúvida.
• Fique fora das duas opções e use um roteiro fixo se os passos nunca variam e não exigem julgamento. Nesse caso, um fluxo determinístico é mais seguro, e nosso guia para decidir entre agente e fluxo determinístico ajuda a traçar essa linha.
• Deixe na conversa o que é um pedido pontual que não vai se repetir.

Um bom teste é perguntar se você consegue escrever a primeira linha da descrição. Se não consegue dizer em uma frase quando a skill se aplica, o procedimento provavelmente são dois procedimentos, ou ainda não é um procedimento.

Como escrever uma skill, passo a passo?

Este é um plano prático que serve para qualquer tarefa recorrente. Funciona com qualquer ferramenta, porque trata do conteúdo do procedimento.

• Passo 1: escolha um exemplo real. Pegue um caso recente e concluído da tarefa e reúna as entradas, o resultado e as decisões que uma pessoa tomou no caminho.
• Passo 2: escreva o gatilho. Redija uma descrição de uma ou duas frases dizendo quando usar a skill e uma frase sobre quando não usar.
• Passo 3: liste as entradas. Nomeie cada uma, diga de onde vem e diga o que o agente faz se ela faltar (em geral: parar e perguntar).
• Passo 4: escreva os passos como ações. Cada passo deve gerar algo observável, como um rascunho, uma consulta ou uma comparação. Evite passos como “considere a situação”.
• Passo 5: defina os limites. Liste as ferramentas que a skill pode usar e as ações que não pode executar. Separe ler, preparar e enviar, pois cada uma tem um risco diferente, como explicamos em ler, preparar e enviar: três permissões diferentes de IA.
• Passo 6: defina a saída e a evidência. Indique o formato e exija que o agente anexe o que conferiu, para que quem revisa consiga verificar sem refazer o trabalho.
• Passo 7: acrescente condições de parada. Nomeie os casos que vão para uma pessoa e diga o que a passagem deve conter.
• Passo 8: inclua dois ou três exemplos, entre eles um caso incômodo, e registre o resultado esperado de cada um.
• Passo 9: atribua um responsável e uma etiqueta de versão, e anote o que mudou sempre que a skill for editada.

Mantenha o arquivo curto o bastante para que o responsável o leia por inteiro a cada edição. Se ele crescer além do que uma pessoa consegue ter em mente, divida por resultado, não por assunto.

Como fica uma skill em um cenário real?

Este é um cenário ilustrativo, não a descrição de um cliente real.

Imagine uma pequena equipe de operações que pede ao agente, toda segunda-feira, um resumo das entregas de fornecedores. O prompt original mistura o formato do resumo, regras sobre quais atrasos sinalizar, instruções para redigir e-mails aos fornecedores e um aviso de nunca contatar fornecedores diretamente. Toda vez que alguém ajusta a regra de sinalização, o tom dos e-mails também muda, e ninguém sabe por quê.

A equipe divide o trabalho em duas skills. A primeira, de resumo de entregas, lê os dados dos pedidos, agrupa os itens atrasados, aplica a regra de sinalização e produz uma tabela com uma nota sobre quais registros foram conferidos. A segunda, de acompanhamento de fornecedores, redige um e-mail para cada atraso sinalizado, mas seu limite diz que são apenas rascunhos, com uma pessoa aprovando cada mensagem. As instruções centrais ficam só com a identidade do agente, o tom e a regra de parar quando faltarem dados.

Agora o responsável por operações altera a regra de sinalização editando um arquivo curto, roda os três exemplos salvos e vê se a saída continua correta. A skill de e-mail não foi tocada, então não precisa de novo teste. A mudança é pequena, revisada e reversível.

Como testar uma skill antes de confiar nela?

Uma skill só é mais fácil de manter se você percebe quando ela quebra. No começo, testar não exige ferramentas pesadas. Exige um conjunto pequeno e honesto de casos e uma regra do que conta como aprovado.

• Reúna exemplos reais de trabalhos passados: um caso típico, um caso com entrada faltando, um caso que deve acionar a passagem a uma pessoa e um caso que tenta o agente a ultrapassar seu limite.
• Escreva o resultado esperado de cada um em linguagem simples, incluindo o que o agente não deve fazer.
• Rode a skill contra esse conjunto sempre que a skill, o modelo ou uma ferramenta conectada mudar.
• Analise as falhas lendo o que o agente de fato fez, e não apenas a resposta final. Os textos da Anthropic sobre avaliação de agentes fazem o mesmo ponto: examine os passos que o agente deu, não só o resultado.
• Transforme cada falha real em um novo caso de teste, para que o mesmo erro não volte despercebido.

É a mesma disciplina descrita em nosso guia sobre como avaliar agentes de IA em tarefas de negócio. O arquivo da skill define o procedimento, e o conjunto de testes define como é o correto. Juntos, permitem que alguém sem formação técnica aprove uma mudança com confiança.

Como carregar skills sem aumentar o risco nem a bagunça?

Skills resolvem o problema da bagunça, mas trazem duas questões de desenho: qual skill é carregada e o que o texto carregado tem permissão de fazer.

Sobre a seleção, mantenha as descrições distintas. Se duas skills têm gatilhos parecidos, o agente vai escolher de forma inconsistente. Revise as descrições em conjunto, como se revisa um cardápio, e elimine as sobreposições. Mantenha também o número de skills disponíveis para um único papel de agente em um nível administrável, porque um cardápio lotado dificulta a escolha.

Sobre autoridade, lembre que a skill é uma instrução confiável. Quem pode editá-la pode mudar o que o agente faz, então o direito de edição merece o mesmo cuidado que o acesso aos sistemas que o agente usa. Revise as mudanças antes de entrarem em vigor e guarde o registro de quem alterou o quê. Não deixe que skills sejam montadas a partir de conteúdo que o agente buscou em fontes externas, porque texto não confiável promovido a instrução é exatamente como a injeção de prompt tem sucesso. As orientações da OWASP sobre prevenção de injeção de prompt são uma boa referência para separar instruções confiáveis de entradas não confiáveis.

Mantenha também as aprovações fora do texto da skill. Uma linha dizendo “pergunte antes de enviar” é um pedido ao modelo. Uma configuração de permissão que bloqueia o envio até uma pessoa aprovar é um controle. Use as duas, mas conte com a segunda. Se suas skills têm pontos de aprovação, nosso guia sobre escalonamento humano em IA ajuda a posicioná-los.

Como a Be Human trata skills em uma operação gerenciada?

A Be Human trata skills como parte do harness do agente, ao lado de identidade, memória, ferramentas e permissões. Em um primeiro projeto, definimos um papel útil e empacotamos seus procedimentos recorrentes como skills, com um responsável nomeado do lado da empresa, um conjunto salvo de casos de teste e limites de aprovação aplicados na ferramenta, e não apenas no texto. Durante a operação gerenciada, repetimos os casos de teste após mudanças em uma skill, em um modelo ou em uma integração, revisamos quem pode editar as skills e fazemos as melhorias como atualizações controladas e versionadas. A empresa mantém a palavra final sobre o que cada skill pode fazer.

Perguntas frequentes

Qual a diferença entre uma skill e um modelo de prompt? Um modelo preenche lacunas em uma mensagem, enquanto a skill é um procedimento completo, com gatilho, limites de ferramentas, exigência de evidência e condições de parada. O agente decide quando carregar uma skill, e o harness aplica seus limites. Um modelo de prompt não faz nenhuma das duas coisas.

Quantas skills um agente deve ter? As necessárias para cobrir suas tarefas recorrentes, e poucas o bastante para que as descrições continuem claramente distintas entre si. Se você está escrevendo skills quase idênticas, una-as ou aperte os gatilhos. Um papel restrito com um punhado de skills bem testadas costuma ser mais fácil de confiar do que um papel amplo.

Quem deve ser o responsável por uma skill? A pessoa dona do processo de negócio correspondente, porque é quem sabe quando a regra está errada. Um colega técnico pode ajudar com ferramentas e testes, mas não deve ser o único a entender o procedimento. Ser responsável também significa aprovar cada mudança.

Skills podem substituir um fluxo fixo? Não quando os passos nunca variam e não exigem julgamento, porque um fluxo determinístico é mais barato de rodar e mais fácil de garantir. Skills servem para trabalhos em que o agente precisa ler entradas variadas e decidir, dentro de limites que você deixou escritos. Muitos bons sistemas combinam os dois: um fluxo fixo para as partes previsíveis e uma skill para o julgamento dentro delas.

Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.