OpenClaw skills: como criar e restringir as ferramentas do agente

OpenClaw skills: como criar e restringir as ferramentas do agente

Para criar uma skill no OpenClaw, escreva instruções curtas para uma única função (quando usar, passos, limites e formato da resposta) e, separadamente, configure uma lista pequena de ferramentas permitidas para o agente que vai executá-la. A skill orienta o comportamento, mas quem impõe o limite é a configuração de ferramentas e permissões. Por isso as duas coisas precisam ser desenhadas juntas e testadas antes de o agente tocar em dados reais.

Principais pontos

• Uma skill descreve como executar uma função. A lista de ferramentas permitidas define o que o agente consegue fazer de fato. Uma não substitui a outra.
• Comece por uma função estreita, com início, fim e responsável humano definidos, e não por um agente genérico.
• Libere ferramentas por negação padrão: tudo fechado, e abra só o que a função exige, de preferência em modo leitura primeiro.
• Ações que mudam algo no mundo (enviar mensagem, alterar cadastro, mover dinheiro) pedem aprovação humana e registro.
• Teste a skill com casos normais, casos de borda e tentativas de desvio antes de ampliar o uso.

O que é uma skill e o que ela não faz

No OpenClaw, uma skill é um pacote de instruções reutilizável que o agente carrega quando a tarefa pede. Em geral, ela é uma pasta com um arquivo de instruções em markdown e, se necessário, materiais de apoio. O formato exato, os campos aceitos e o local onde as skills ficam variam conforme a versão instalada, então confirme tudo na documentação oficial do projeto antes de padronizar na empresa. Quem já conhece o conceito no Claude Code encontra uma ideia parecida, descrita em Skills no Claude Code: o que são e como criar as da sua equipe.

O ponto que mais gera problema em implantações é confundir instrução com controle. Escrever na skill que o agente nunca deve apagar um registro é uma orientação. Ela ajuda, mas um modelo de linguagem pode falhar em seguir uma instrução, principalmente diante de texto malicioso vindo de uma mensagem ou de um documento. O controle real acontece quando a ferramenta de apagar registros simplesmente não está disponível para aquele agente.

Pense nas duas camadas assim:

• Skill: contexto, procedimento, tom, critérios de decisão, quando pedir ajuda humana.
• Ferramentas e permissões: o que o agente pode ler, escrever, executar e acessar, e o que exige aprovação.

Essa separação aparece nas boas práticas de segurança para LLMs. A lista OWASP Top 10 para aplicações com LLM trata, por exemplo, de agência excessiva: dar ao agente mais funções, permissões ou autonomia do que a tarefa exige.

Como criar uma skill para uma função específica, passo a passo

O roteiro abaixo funciona para qualquer função. O exemplo mental é uma tarefa repetitiva e bem delimitada, como triar pedidos de orçamento ou responder dúvidas de status.

• Defina a função em uma frase. Exemplo: classificar pedidos de orçamento recebidos e preparar um rascunho de resposta para revisão. Se a frase precisa de um e, provavelmente são duas skills.
• Escreva o gatilho. Diga quando a skill deve ser usada e quando não deve. Um bom nome e uma boa descrição ajudam o agente a escolher a skill certa entre várias.
• Liste as entradas esperadas. Que informação chega (texto do cliente, número do pedido, anexo) e o que fazer se algo estiver faltando.
• Descreva os passos em ordem. Verbos claros, um passo por linha, com o critério de saída de cada um.
• Defina os limites. O que o agente não faz, quais dados não deve repetir na resposta, quais assuntos sempre vão para uma pessoa.
• Defina o formato da saída. Rascunho, campos estruturados, resumo para o responsável. Saída previsível facilita revisão e medição.
• Escreva o ponto de transferência humana. Quem recebe, com qual resumo, em que canal.
• Inclua dois ou três exemplos curtos de entrada e saída esperada, inclusive um caso em que a resposta correta é recusar ou escalar.

Sobre o texto, valem os mesmos cuidados de qualquer instrução para agente: seja direto, evite regras contraditórias e prefira poucas regras claras a muitas regras vagas. O guia Como escrever prompt para atendimento ao cliente com IA detalha esse tipo de redação para atendimento.

Um erro comum é transformar a skill em manual da empresa inteira. Skills longas gastam contexto, diluem a atenção do modelo e escondem regras importantes. Se a função precisa de uma política extensa, mantenha o documento à parte e faça a skill apontar para ele, deixando claro quando consultá-lo.

Como escolher uma lista curta de ferramentas permitidas?

A pergunta útil não é quais ferramentas o agente poderia usar, e sim qual é o mínimo para cumprir a função. Esse é o princípio do menor privilégio, descrito em materiais de autorização como o guia de autorização da OWASP, e ele vale para agentes como vale para pessoas.

Um guia de decisão simples, para cada ferramenta candidata:

• A função falha sem ela? Se não, deixe de fora.
• Ela só lê ou também escreve? Se escreve, comece com uma versão somente leitura e adicione a escrita depois do piloto.
• Ela alcança dados além do necessário? Se sim, restrinja por pasta, tabela, conta ou campo, em vez de liberar o sistema inteiro.
• Ela tem efeito externo (envia mensagem, cria cobrança, publica)? Se sim, exija aprovação humana por ação.
• Ela é reversível? Ações irreversíveis ficam fora do alcance automático.
• Ela executa comandos ou acessa a rede de forma aberta? Em geral, mantenha desligada para funções de negócio, a menos que exista isolamento e justificativa.

Depois de decidir, escreva a lista final em um lugar que a equipe consiga revisar. Uma tabela mental de três colunas ajuda: ferramenta, motivo de existir, tipo de acesso. Se alguém não consegue preencher o motivo, a ferramenta sai.

Também vale cuidar da qualidade das próprias ferramentas. A Anthropic publica orientações sobre como escrever ferramentas para agentes, com ênfase em nomes claros, descrições precisas e respostas enxutas. Ferramentas ambíguas levam a chamadas erradas mesmo quando a skill está boa. Para entender o mecanismo por trás dessas chamadas, veja Function calling: o que é e como a IA usa ferramentas e APIs.

Se a ferramenta vem de um servidor MCP de terceiros, a revisão tem que ser ainda mais cuidadosa, porque você herda o que ele expõe. O MCP é um protocolo aberto para conectar agentes a ferramentas e dados, e instalar um servidor sem auditar é uma forma comum de ampliar o acesso sem perceber.

Cenário ilustrativo: triagem de pedidos de orçamento

Este é um cenário ilustrativo, sem relação com nenhuma empresa real. Imagine uma pequena empresa de serviços que recebe pedidos de orçamento por e-mail e WhatsApp. O responsável comercial quer que o agente leia o pedido, identifique o tipo de serviço, verifique se faltam informações e prepare um rascunho de resposta.

A skill, em linguagem simples, diria:

• Use esta skill quando chegar um pedido novo de orçamento. Não use para reclamações, cobranças ou dúvidas sobre pedidos já em andamento.
• Identifique o serviço pedido, o local e o prazo desejado. Se faltar algum desses itens, liste as perguntas necessárias no rascunho.
• Nunca informe valores, descontos ou prazos firmes. Valores são definidos por uma pessoa.
• Entregue um rascunho e um resumo de três linhas para o responsável. Não envie nada ao cliente.
• Se o pedido mencionar dado sensível, urgência de segurança ou ameaça jurídica, transfira imediatamente para uma pessoa.

A lista de ferramentas permitidas seria curta:

• Leitura da caixa de entrada ou da conversa em que o pedido chegou.
• Consulta somente leitura ao catálogo de serviços.
• Criação de um rascunho interno para revisão, sem envio.
• Registro da decisão em um log.

Ficam de fora: envio direto ao cliente, edição de cadastro, acesso ao financeiro, execução de comandos e navegação aberta na internet. Quando o piloto mostrar que os rascunhos são bons, a empresa pode avaliar liberar o envio com aprovação humana por mensagem, nunca de uma vez.

Observe que a skill e as ferramentas dizem a mesma coisa de formas diferentes. A skill afirma que o agente não envia nada. A configuração garante que ele não consegue enviar. Se uma das duas camadas falhar, a outra ainda protege.

Como testar a skill e as restrições antes de liberar

Teste em duas frentes: o comportamento da skill e a barreira das ferramentas.

Para o comportamento, monte um conjunto pequeno de casos reais anonimizados ou inventados:

• Casos típicos, que a skill deveria resolver bem.
• Casos incompletos, em que falta informação.
• Casos fora do escopo, em que o certo é recusar ou transferir.
• Casos ambíguos, em que um humano também hesitaria.

Para a barreira, tente de propósito o que a skill proíbe. Peça ao agente, por mensagem, para enviar algo, consultar outro sistema ou ignorar as regras. Inclua texto malicioso embutido em um anexo ou em um e-mail, o que se chama injeção de prompt indireta. A OWASP mantém um guia de prevenção de injeção de prompt que ajuda a montar esses testes. O resultado esperado não é o agente recusar educadamente, e sim a ferramenta não existir para ele. Registre qualquer caso em que o agente conseguiu algo que não deveria e corrija na configuração, não só no texto da skill.

Depois, confira os registros. Cada execução deve mostrar qual skill foi usada, quais ferramentas foram chamadas, com quais parâmetros e o que foi decidido. Sem isso, não há como auditar nem melhorar. A leitura complementar sobre camadas de validação está em Guardrails para agentes de IA: entrada, saída e ação na prática.

Se o agente rodar em um gateway acessível por rede, a exposição do próprio gateway também entra na revisão. O Checklist de Segurança do OpenClaw Gateway cobre esse ponto, e o guia de implementação do OpenClaw para empresas mostra o contexto de produção.

No Brasil, vale lembrar que, se a função toca dados pessoais de clientes ou colaboradores, a LGPD se aplica: finalidade clara, minimização do que o agente enxerga e atenção ao que fica nos logs. Para orientação oficial, a página da ANPD é o ponto de partida. Quando houver dúvida jurídica, ela deve ir para o jurídico da empresa, não para a skill.

Como o método mapear, limitar, pilotar e transferir se aplica

O método que usamos para implantar agentes segue quatro movimentos, e cada um corresponde a uma decisão sobre skills e ferramentas.

• Mapear: descrever o processo atual e a linha de base, ou seja, como a tarefa é feita hoje, por quem e com que volume de exceções. Sem isso, a skill vira um palpite. O artigo sobre mapeamento de processos antes de aplicar IA detalha essa etapa.
• Limitar: reduzir dados e ações ao mínimo. É aqui que nasce a lista curta de ferramentas, com leitura antes de escrita e aprovação humana para efeitos externos.
• Pilotar: rodar um fluxo real, com logs e uma métrica de sucesso combinada antes de começar. A skill é ajustada com base no que os registros mostram.
• Transferir: entregar a operação com documentação, responsáveis e critério para decidir se amplia, ajusta ou encerra.

Nada disso exige promessa de resultado. O objetivo é que, ao final do piloto, a empresa tenha evidência para decidir, e não uma impressão.

Checklist de revisão antes de ativar

Use esta lista como porta de saída do piloto:

• A função cabe em uma frase e tem um responsável humano nomeado.
• A skill diz quando usar, quando não usar, o que entregar e para quem transferir.
• Cada ferramenta liberada tem um motivo escrito e um tipo de acesso (leitura ou escrita).
• Ações com efeito externo exigem aprovação humana.
• Segredos e chaves não estão dentro do texto da skill nem acessíveis ao agente além do necessário.
• Os testes incluíram tentativas de desvio e injeção de prompt.
• Os logs registram skill, ferramenta, parâmetros e decisão, e há prazo definido para guardá-los.
• Existe um jeito simples de desligar a skill ou revogar uma ferramenta.

Perguntas frequentes

Preciso escrever código para criar uma skill no OpenClaw? Em geral, o núcleo de uma skill é texto estruturado com instruções, e não código. Código só entra se a skill depender de scripts ou integrações próprias, e nesse caso a revisão de segurança precisa ser maior. Confirme o formato aceito na documentação da versão que você usa.

A skill sozinha garante que o agente não vai fazer algo proibido? Não. A skill orienta o modelo, mas o modelo pode errar ou ser induzido por texto malicioso. A garantia vem de restringir as ferramentas, permissões e credenciais disponíveis, de modo que a ação proibida não esteja ao alcance do agente.

Quantas ferramentas um agente deveria ter? Não existe número certo, e sim um critério: apenas as que a função não consegue cumprir sem elas. Se você não consegue explicar em uma frase por que uma ferramenta está liberada, retire e reavalie depois do piloto. Listas curtas também facilitam o agente escolher a ferramenta certa.

Quando faz sentido liberar ações de escrita, como enviar mensagens? Depois de um piloto com rascunhos revisados, logs consistentes e uma métrica de qualidade acordada. Mesmo assim, comece com aprovação humana por ação. Para mensagens ativas no WhatsApp, considere também as regras de templates e consentimento descritas em Mensagens ativas no WhatsApp: templates, opt-in e boas práticas.

Fontes

• OWASP: Top 10 for LLM Applications
• OWASP: Authorization Cheat Sheet
• OWASP: LLM Prompt Injection Prevention Cheat Sheet
• Anthropic: Writing effective tools for agents