Como Criar e Revisar Skills do OpenClaw

O Que Você Vai Construir

Um fluxo de desenvolvimento e revisão de skills que permite:

1. Criar skills personalizados — desenvolver novos skills do OpenClaw sob medida para suas necessidades específicas
2. Revisar skills da comunidade — avaliar skills do ClawHub quanto à qualidade, segurança e confiabilidade
3. Decompor tarefas complexas — dividir fluxos de trabalho multi-etapas em cadeias de skills reutilizáveis
4. Iterar e melhorar — testar, debugar e refinar skills com feedback assistido por IA

Ao final deste guia, você vai conseguir criar skills de qualidade para produção e avaliar com confiança qualquer skill antes de instalá-lo.

Por Que Criar Skills Personalizados

O ClawHub tem centenas de skills da comunidade, mas às vezes você precisa de algo específico:

• Ferramentas internas — as APIs, dashboards e fluxos de trabalho da sua empresa não são cobertos por skills públicos
• Integrações personalizadas — você usa ferramentas de nicho ou sistemas proprietários que precisam de conectores customizados
• Otimização de fluxo — combinar múltiplos skills em um único skill simplificado economiza tempo
• Controle de qualidade — construir seus próprios skills significa que você sabe exatamente o que eles fazem
• Vantagem competitiva — fluxos de automação únicos que seus concorrentes não têm

Por Que Revisar Skills Antes de Instalar

Nem todo skill no ClawHub está pronto para produção. Antes de instalar um skill da comunidade:

• Segurança — um skill pode acessar seu sistema de arquivos, rede ou credenciais de formas que você não espera
• Qualidade — alguns skills são protótipos ou provas de conceito, não soluções para produção
• Manutenção — skills abandonados podem não funcionar com versões mais recentes do OpenClaw
• Dependências — um skill pode exigir serviços externos ou API keys que você não tem
• Permissões — entenda exatamente quais acessos um skill solicita antes de concedê-los

Pré-requisitos

• OpenClaw instalado e configurado (Guia de Introdução)
• Familiaridade com YAML e scripting básico
• Node.js 18+

Passo 1: Instalar as Ferramentas de Desenvolvimento de Skills

# 1. Skill builder — guia você na criação de skills bem estruturados
npx clawhub@latest install skill-builder

# 2. Skill reviewer — análise de qualidade e estrutura
npx clawhub@latest install skill-reviewer

# 3. Task decomposer — divide tarefas complexas em cadeias de skills
npx clawhub@latest install task-decomposer

Passo 2: Criar Seu Primeiro Skill Personalizado

Entendendo a Estrutura de um Skill

Um skill do OpenClaw é centrado em um arquivo SKILL.md — este é o documento de instruções principal que diz ao agente de IA como executar uma tarefa. O skill Skill Builder guia você na criação de skills bem estruturados seguindo as melhores práticas.

A estrutura típica de um skill é:

my-custom-skill/
  ├── SKILL.md             # Instruções principais para o agente
  ├── [topic].md           # Arquivos de detalhe sob demanda (carregados quando necessário)
  ├── references/          # Documentação pesada, exemplos
  └── scripts/             # Scripts de automação opcionais

Escrevendo Seu SKILL.md

O SKILL.md é o coração do seu skill. Peça ao OpenClaw (com o skill Skill Builder instalado) para ajudar você a escrever um:

Me ajude a criar um skill que pesquisa uma API personalizada de produtos.
A API está em https://api.example.com/search e requer uma API key.

O Skill Builder guia você por:

• Estrutura modular — manter o SKILL.md principal focado e usar arquivos separados para tópicos detalhados
• Divulgação progressiva — carregar arquivos de detalhe apenas quando o agente precisar
• Design eficiente em tokens — minimizar o uso da janela de contexto
• Entrada/saída claras — definir o que o skill espera e retorna

Exemplo de SKILL.md

# Product Search Skill

Search the product catalog API for items matching a query.

## Configuration
- `API_URL`: Base URL of the product API
- `API_KEY`: API key for authentication (set as environment variable)

## Usage
When the user asks to search for products, use the API:

GET {API_URL}/search?q={query}
Authorization: Bearer {API_KEY}

## Response Format
Return results as a structured list with name, price, and URL for each product.

Testando o Skill

Instale seu skill localmente e teste:

clawhub install ./my-custom-skill

Depois tente usá-lo no OpenClaw para verificar se funciona como esperado.

Passo 3: Revisar um Skill da Comunidade

Antes de instalar qualquer skill do ClawHub, revise-o:

clawhub run skill-reviewer --skill "clawhub-username/skill-name"

O reviewer analisa o SKILL.md e os arquivos de suporte do skill, verificando:

=== Skill Review: awesome-slack-bot ===

## Structure Assessment
✓ SKILL.md is well-organized with clear sections
✓ Description is specific and actionable
✓ Input/output expectations are documented
✓ Usage examples included
⚠ Missing on-demand detail files — all content is in one large SKILL.md

## Quality Score
✓ Frontmatter is complete (name, description, version)
✓ Instructions are token-efficient — progressive disclosure used
✓ Error handling guidance included
⚠ No rate limiting guidance — may hit API limits under heavy use

## Description Quality: 8.5/10
Recommendation: Well-structured skill, ready for use

O Que Procurar

Sinais de Alerta

• O skill solicita permissões que não deveria precisar (ex.: um skill de busca pedindo acesso de escrita em arquivos)
• Sem testes ou documentação
• Última atualização há mais de 6 meses
• URLs ou credenciais hardcoded no código-fonte
• Código ofuscado ou minificado

Sinais Positivos

• Declarações de permissão claras que correspondem ao uso real
• Cobertura de testes abrangente
• Manutenção ativa e engajamento da comunidade
• Código-fonte transparente
• Configuração bem documentada

Passo 4: Decompor Tarefas Complexas

O skill Task Decomposer ajuda a dividir solicitações complexas em etapas executáveis. Peça ao OpenClaw:

Decomponha esta tarefa: Monitorar páginas de preços de concorrentes diariamente e me alertar quando os preços mudarem

Exemplo de saída:

=== Task Decomposition ===

Task: Monitor competitor pricing pages daily and alert when prices change

## Skill Chain

1. **browser-use** — Navigate to each competitor's pricing page
   Input: List of competitor URLs
   Output: Page content / screenshots

2. **web-scraper** — Extract pricing data from each page
   Input: Page content
   Output: Structured pricing data (JSON)

3. **file_read** — Load yesterday's pricing data for comparison
   Input: File path to stored data
   Output: Previous pricing data

4. **summarize** — Compare current vs. previous pricing and identify changes
   Input: Current data + previous data
   Output: Change report

5. **telegram** (or email) — Send alert if changes detected
   Input: Change report
   Output: Notification sent

## Required Skills
- browser-use (installed: yes)
- web-scraper (installed: yes)
- summarize (installed: yes)
- telegram (installed: no — install with: npx clawhub@latest install telegram)

## Estimated Setup Time: 20 minutes

Da Decomposição ao Fluxo de Trabalho

Transforme a decomposição em um fluxo de trabalho reutilizável:

# .openclaw/price-monitor.yml
name: competitor-price-monitor
schedule: "0 9 * * *"
steps:
  - skill: browser-use
    action: navigate
    urls:
      - "https://competitor1.com/pricing"
      - "https://competitor2.com/pricing"

  - skill: web-scraper
    action: extract
    format: json
    target: "pricing tables"

  - skill: summarize
    action: compare
    current: "{{step_2.output}}"
    previous: "./data/last-pricing.json"

  - skill: telegram
    action: send
    condition: "changes_detected"
    message: "{{step_3.output}}"

  - action: save
    data: "{{step_2.output}}"
    path: "./data/last-pricing.json"

Passo 5: Publicar Seu Skill

Quando seu skill estiver pronto, publique-o no ClawHub:

clawhub publish my-custom-skill

Antes de publicar, garanta que:

• O SKILL.md está completo e bem estruturado
• A descrição é específica e acionável
• Não há secrets hardcoded em nenhum arquivo
• O número da versão segue semver

Solução de Problemas

Skill não funciona como esperado

• Verifique se as instruções do SKILL.md são claras e específicas
• Teste com diferentes prompts para ver se o agente interpreta o skill corretamente
• Consulte as diretrizes do Skill Builder para armadilhas comuns em instruções

"Permission denied" durante a execução do skill

• Revise o que o skill acessa — arquivos, rede, credenciais
• Verifique se você concedeu as permissões necessárias ao instalar
• Algumas permissões exigem aprovação explícita do usuário na primeira execução

O skill reviewer mostra falsos positivos

• O reviewer é conservador — ele sinaliza qualquer coisa que possa ser uma preocupação
• Revise os avisos específicos e decida se se aplicam ao seu caso de uso
• Nem todo aviso é um problema real — use seu julgamento

Skill publicado não aparece no ClawHub

• A publicação pode levar alguns minutos para propagar
• Verifique se sua conta no ClawHub está verificada
• Confira se o nome do skill não conflita com um skill existente