Como criar uma Skill personalizada no OpenClaw

Eu tinha 127 fotos exportadas do celular, todas com mais de 5 MB. Queria que o OpenClaw comprimisse tudo em lote, mas ele devolveu uma série de comandos do ImageMagick que eu precisava copiar, colar e executar manualmente. Se fosse possível fazê-lo “lembrar” desse processo, bastaria pedir “comprima as imagens” da próxima vez para ele saber o que fazer. É exatamente esse o tipo de situação em que uma Skill personalizada faz sentido.

Depois descobri que o OpenClaw já havia previsto essa necessidade: ao criar uma Skill personalizada, você pode ensiná-lo a executar qualquer fluxo de trabalho específico seu. É como instalar um app no iPhone: você configura uma vez e continua usando.

Neste tutorial, vou usar uma Skill completa de processamento de imagens como exemplo e percorrer todo o desenvolvimento desde o início.

Guia econômico para “criar sua lagosta”: ArkClaw torna os agentes de IA realmente acessíveis

O OpenClaw, também conhecido como “lagosta”, está em alta, mas sua configuração pode afastar muita gente. O ArkClaw, da Volcano Engine, da ByteDance, reduz bastante essa barreira. Sem precisar configurar servidor ou token, você obtém com um clique um agente de IA disponível 24 horas por dia, capaz de controlar o navegador, executar scripts e gerenciar o calendário.

O principal atrativo é o preço: a mensalidade custa apenas 9,9 yuans. Com meu código de convite ZLKUK54M (cadastre-se aqui), o valor cai para 8,9 yuans. Se você é programador, também pode assinar diretamente o Coding Plan Pro e usá-lo sem custo adicional.

Entenda o que é uma Skill em 5 minutos

Afinal, o que é uma Skill?

Quando vi o termo “Skill” pela primeira vez, pensei em vários conceitos técnicos: plugin, extensão, middleware? Nenhum deles parecia explicar direito.

Uma forma simples de entender é esta: uma Skill é um “app especializado” instalado no OpenClaw.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

O funcionamento de uma Skill do OpenClaw segue essa lógica. Os recursos nativos resolvem 80% das tarefas comuns, mas os 20% restantes envolvem necessidades específicas — como o processo de imagens usado pela sua empresa ou sua convenção pessoal para nomes de arquivos. Para isso, você precisa instalar seu próprio “app”.

O que uma Skill contém?

Uma Skill completa é bastante simples e tem apenas três partes:

1. SKILL.md (obrigatório): arquivo de configuração que informa ao OpenClaw o que a Skill faz e quando deve ser acionada
2. Pasta scripts/ (opcional): scripts que executam o trabalho, em Python, Bash ou outra linguagem
3. Pasta references/ (opcional): documentação complementar, como uma lista de formatos de arquivo compatíveis

No exemplo da Skill de processamento de imagens que vamos criar, a estrutura de pastas fica assim:

~/.openclaw/skills/image-processor/
├── SKILL.md              # Arquivo principal de configuração
├── scripts/
│   └── compress.py       # Script de compressão de imagens
└── references/
    └── formats.md        # Documentação dos formatos compatíveis

Por que criar uma Skill personalizada?

O valor de uma Skill personalizada está justamente em transformar processos repetitivos em uma rotina definida: configure uma vez e continue usando.

Como uma Skill funciona: Progressive Disclosure

O mecanismo é bem pensado. O OpenClaw não carrega de uma vez todas as instruções detalhadas de todas as Skills na memória, pois isso consumiria tokens demais. Em vez disso, o processo ocorre em três etapas:

1. Primeira camada (frontmatter): lê apenas o nome e uma descrição curta da Skill para decidir se ela é necessária para a tarefa
2. Segunda camada (corpo): se a Skill for necessária, carrega as instruções de uso completas
3. Terceira camada (scripts): chama os arquivos de script somente no momento da execução

Skills pessoais versus Skills de projeto

• Pessoal: ~/.openclaw/skills/nome-da-skill/, disponível para todos os projetos
• Do projeto: raiz-do-projeto/.openclaw/skills/nome-da-skill/, válida apenas nesse projeto

Minha recomendação é começar com uma Skill pessoal. Depois que ela estiver funcionando bem no seu dia a dia, avalie se vale a pena isolá-la por projeto.

Processo completo para criar uma Skill de processamento de imagens

Etapa 1: criar a estrutura de pastas

Primeiro, crie as pastas no local adequado. Se quiser usar a Skill em todos os projetos, coloque-a no diretório pessoal:

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

mkdir -p ~/.openclaw/skills/image-processor
cd ~/.openclaw/skills/image-processor
mkdir scripts references

Etapa 2: escrever o arquivo de configuração SKILL.md

Esse é o núcleo da Skill. Crie o arquivo SKILL.md com o seguinte conteúdo:

---
name: image-processor
description: Ferramenta de processamento de imagens em lote. Use quando o usuário precisar comprimir imagens, converter formatos, redimensionar arquivos ou adicionar marcas d'água. Compatível com JPG, PNG e WebP.
tools: Bash, Read, Write
---

Essas três linhas de YAML são essenciais:

• name: identificador exclusivo da Skill; o usuário pode chamá-la manualmente com /image-processor
• description: esse texto determina diretamente quando o OpenClaw aciona a Skill de forma automática
• tools: declara as permissões necessárias

Etapa 3: desenvolver o script em Python

Crie scripts/compress.py. Esse é o script que realmente executa o trabalho. Para atender ao caso descrito no início do artigo, ele precisa oferecer compressão, conversão de formato e redimensionamento.

(Por limitação de espaço, consulte o documento original ou o exemplo no GitHub para ver o código do script. A lógica principal usa a biblioteca Pillow para processar as imagens.)

Etapa 4: adicionar documentação complementar (opcional)

Para deixar a Skill mais completa, você pode registrar os formatos compatíveis em references/formats.md.

Dicas de teste e depuração

Método 1: testar com uma chamada explícita

O teste mais simples é digitar diretamente no OpenClaw: /image-processor

Método 2: testar o acionamento automático

Abra uma pasta que contenha imagens e diga ao OpenClaw: “Comprima as imagens da pasta ~/Downloads/photos”.

Método 3: verificar os logs de execução

Se o script falhar, examine a saída do terminal para localizar o erro.

Segurança e práticas recomendadas

Três princípios para uma configuração segura

1. Privilégio mínimo: declare apenas as ferramentas realmente necessárias; não conceda tools: *.
2. Validação de entrada: o script deve verificar os dados fornecidos pelo usuário e rejeitar parâmetros inválidos.
3. Restrição de caminhos: o script não deve acessar diretórios sensíveis do sistema.

Recomendações de desempenho

• Use Progressive Disclosure: mantenha a description curta e precisa.
• Estratégia de cache: coloque no SKILL.md as configurações consultadas com frequência.

Resumo

O essencial pode ser resumido em três pontos:

1. Uma Skill é um app especializado para o OpenClaw — o arquivo de configuração SKILL.md informa o que o recurso faz e quando deve ser usado
2. O desenvolvimento é simples — crie as pastas, escreva a configuração e adicione o script opcional
3. Comece pequeno — não tente deixar tudo perfeito de uma vez; resolva primeiro um problema específico e faça a Skill funcionar

Comece agora

Não pare apenas na leitura. Faça o seguinte agora:

1. Copie o código do artigo
2. Teste o funcionamento
3. Adapte-o ao seu caso

Comece agora. Em 30 minutos, você poderá ter sua primeira Skill personalizada para o OpenClaw.