Guia Completo de Desenvolvimento de Skills

Este guia ensina como criar skills profissionais para OpenClaw — desde a estrutura básica até publicação no ClawHub.

O Que São Skills?

Skills são pacotes modulares que estendem as capacidades do OpenClaw. Pense nelas como “guias de integração” para domínios específicos — transformam o OpenClaw de um agente genérico em um especialista equipado com conhecimento procedural.

O Que Skills Fornecem

Componente	Descrição	Exemplo
Workflows especializados	Procedimentos multi-etapa para domínios específicos	Deploy para AWS em 5 passos
Integrações	Instruções para trabalhar com APIs ou formatos	Manipulação de PDFs
Conhecimento de domínio	Schemas, regras de negócio, políticas	Compliance LGPD
Recursos bundled	Scripts, referências e assets reutilizáveis	Templates de documentos

Anatomia de uma Skill

Toda skill consiste em um arquivo SKILL.md obrigatório e recursos opcionais:

nome-da-skill/
├── SKILL.md              # 📋 Obrigatório: instruções principais
├── scripts/              # 🔧 Código executável (Python/Bash)
│   └── processa_pdf.py
├── references/           # 📚 Documentação de referência
│   └── api-docs.md
└── assets/               # 🎨 Arquivos para output
    ├── template.docx
    └── logo.png

Estrutura do SKILL.md

O SKILL.md é o coração de toda skill. Possui duas partes:

1. Frontmatter YAML (Obrigatório)

---
name: minha-skill
description: Descrição clara do que faz e QUANDO usar. Inclua triggers específicos.
---

Campos obrigatórios:

name: Nome da skill (letras minúsculas, números e hífens)
description: O que faz + quando usar (este é o mecanismo de trigger!)

⚠️ Importante: A description é lida SEMPRE pelo OpenClaw para decidir quando ativar a skill. Seja específico sobre os casos de uso!

Exemplo de description eficaz:

description: |
  Manipulação de documentos PDF: extração de texto, rotação, 
  mesclagem e divisão. Use quando precisar:
  (1) Extrair texto de PDFs
  (2) Combinar múltiplos PDFs
  (3) Rotacionar páginas
  (4) Dividir documentos grandes

2. Body Markdown (Obrigatório)

O corpo contém instruções para usar a skill. É carregado APENAS quando a skill é ativada.

# Nome da Skill

## Início Rápido

Exemplo mínimo de uso...

## Workflows

### Workflow 1: Extrair Texto
1. Passo um
2. Passo dois

### Workflow 2: Mesclar PDFs
...

## Referências

- Para API completa: ver [API-DOCS.md](references/api-docs.md)
- Para exemplos: ver [EXAMPLES.md](references/examples.md)

Princípios de Design

1. Concisão é Essencial

A janela de contexto é um bem público. Skills compartilham espaço com:

System prompt
Histórico de conversa
Metadata de outras skills
O pedido do usuário

Regra de ouro: O OpenClaw já é muito inteligente. Adicione apenas informação que ele não possui.

❌ Evite:

## O Que É um PDF
PDF significa Portable Document Format. Foi criado pela Adobe em 1993...

✅ Prefira:

## Extração de Texto
Use pdfplumber para extrair texto:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    texto = pdf.pages[0].extract_text()


### 2. Graus de Liberdade Apropriados

Ajuste a especificidade conforme a fragilidade da tarefa:

| Liberdade | Quando Usar | Formato |
|-----------|-------------|---------|
| **Alta** | Múltiplas abordagens válidas | Instruções em texto |
| **Média** | Padrão preferido existe | Pseudocódigo parametrizado |
| **Baixa** | Operações frágeis/críticas | Scripts específicos |

**Analogia:** Uma ponte estreita precisa de guias específicos (baixa liberdade), enquanto um campo aberto permite muitas rotas (alta liberdade).

### 3. Divulgação Progressiva

Skills usam três níveis de carregamento:

Nível 1: Metadata (name + description) → Sempre em contexto (~100 palavras) ↓ Nível 2: Body do SKILL.md → Quando skill ativa (<5k palavras) ↓ Nível 3: Recursos bundled → Quando necessário (ilimitado)


**Benefício:** Economia de tokens! Referências são carregadas apenas quando necessárias.

---

## Recursos Bundled

### Scripts (`scripts/`)

Código executável para tarefas determinísticas ou repetitivas.

**Quando incluir:**
- Mesmo código é reescrito repetidamente
- Confiabilidade determinística é necessária
- Operações complexas com muitos passos

**Exemplo: `scripts/rotate_pdf.py`**
```python
#!/usr/bin/env python3
"""Rotaciona páginas de um PDF."""
import sys
from pypdf import PdfReader, PdfWriter

def rotate_pdf(input_path, output_path, angle=90):
    reader = PdfReader(input_path)
    writer = PdfWriter()
    
    for page in reader.pages:
        page.rotate(angle)
        writer.add_page(page)
    
    with open(output_path, "wb") as f:
        writer.write(f)

if __name__ == "__main__":
    rotate_pdf(sys.argv[1], sys.argv[2], int(sys.argv[3] or 90))

Referenciando no SKILL.md:

## Rotacionar PDF

Para rotacionar páginas, execute:
```bash
python scripts/rotate_pdf.py entrada.pdf saida.pdf 90


### References (`references/`)

Documentação carregada sob demanda.

**Quando incluir:**
- Schemas de banco de dados
- Documentação de APIs
- Conhecimento de domínio
- Políticas e regras
- Guias detalhados de workflow

**Estrutura recomendada para arquivos grandes (>100 linhas):**
```markdown
# API Reference

## Sumário
- [Autenticação](#autenticação)
- [Endpoints](#endpoints)
- [Exemplos](#exemplos)
- [Erros](#erros)

## Autenticação
...

Referenciando no SKILL.md:

## API

Para autenticação: ver [AUTH.md](references/auth.md)
Para endpoints completos: ver [API-REFERENCE.md](references/api-reference.md)

Assets (`assets/`)

Arquivos usados no output, não carregados em contexto.

Quando incluir:

Templates (DOCX, PPTX, HTML)
Imagens e ícones
Boilerplate de código
Fontes

Exemplo de uso:

## Criar Apresentação

Use o template base:
```bash
cp assets/slide-template.pptx ~/apresentacao.pptx

Então edite conforme necessário.


---

## Padrões de Organização

### Padrão 1: Guia com Referências

Para skills com documentação extensa:

```markdown
# Processamento de PDFs

## Início Rápido

Extraia texto com pdfplumber:
```python
import pdfplumber
texto = pdfplumber.open("doc.pdf").pages[0].extract_text()

Funcionalidades Avançadas

Formulários: Ver FORMS.md
API completa: Ver REFERENCE.md
Exemplos: Ver EXAMPLES.md


### Padrão 2: Organização por Domínio

Para skills com múltiplos domínios:

bigquery-skill/ ├── SKILL.md └── references/ ├── finance.md # Receita, billing ├── sales.md # Oportunidades, pipeline ├── product.md # API usage, features └── marketing.md # Campanhas, atribuição


**SKILL.md:**
```markdown
# BigQuery Analytics

## Navegação por Domínio

- **Finanças** (receita, custos): ver [finance.md](references/finance.md)
- **Vendas** (pipeline, deals): ver [sales.md](references/sales.md)
- **Produto** (uso, features): ver [product.md](references/product.md)

Padrão 3: Organização por Variante

Para skills com múltiplas implementações:

cloud-deploy/
├── SKILL.md
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

SKILL.md:

# Deploy na Nuvem

## Escolha seu Provedor

1. **AWS**: Ver [aws.md](references/aws.md)
2. **GCP**: Ver [gcp.md](references/gcp.md)
3. **Azure**: Ver [azure.md](references/azure.md)

Convenções de Scripts

Nomenclatura

Use snake_case: processa_pdf.py, envia_email.sh
Prefixe com ação: extract_, convert_, validate_
Seja descritivo: merge_pdfs.py > pdf.py

Estrutura Python

#!/usr/bin/env python3
"""Descrição curta do que o script faz."""

import sys
import argparse

def main(input_file: str, output_file: str, option: str = "default"):
    """Função principal com docstring."""
    # Implementação
    pass

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("input", help="Arquivo de entrada")
    parser.add_argument("output", help="Arquivo de saída")
    parser.add_argument("--option", default="default", help="Opção opcional")
    args = parser.parse_args()
    
    main(args.input, args.output, args.option)

Estrutura Bash

#!/bin/bash
# Descrição curta do que o script faz
# Uso: ./script.sh <input> <output>

set -euo pipefail  # Fail fast

INPUT="${1:?Erro: input necessário}"
OUTPUT="${2:?Erro: output necessário}"

# Implementação
echo "Processando $INPUT → $OUTPUT"

Tratamento de Erros

import sys

def main():
    try:
        # Operação principal
        result = process_file(sys.argv[1])
        print(f"Sucesso: {result}")
    except FileNotFoundError:
        print(f"Erro: arquivo não encontrado: {sys.argv[1]}", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"Erro inesperado: {e}", file=sys.stderr)
        sys.exit(2)

O Que NÃO Incluir

Skills devem conter apenas o essencial. NÃO crie:

❌ README.md
❌ CHANGELOG.md
❌ INSTALLATION_GUIDE.md
❌ CONTRIBUTING.md
❌ Testes unitários
❌ Configurações de CI/CD

A skill é para um agente de IA fazer seu trabalho — não precisa de documentação auxiliar para humanos ou processos de desenvolvimento.

Processo de Criação

Etapa 1: Entender com Exemplos Concretos

Antes de criar, responda:

Quais tarefas a skill deve suportar?
O que um usuário diria para ativá-la?
Quais são 3-5 exemplos de uso real?

Exemplo para skill de PDF:

“Extraia o texto deste contrato”
“Combine esses 3 relatórios em um PDF”
“Rotacione a página 5 para paisagem”

Etapa 2: Planejar Recursos Reutilizáveis

Para cada exemplo, analise:

Como executar do zero?
Que código/referência seria útil repetidamente?

Exemplo	Análise	Recurso
Rotacionar PDF	Mesmo código sempre	`scripts/rotate_pdf.py`
Consultar vendas	Preciso saber schema	`references/sales-schema.md`
Criar apresentação	Preciso template base	`assets/slide-template.pptx`

Etapa 3: Criar Estrutura

mkdir -p minha-skill/{scripts,references,assets}
touch minha-skill/SKILL.md

Etapa 4: Implementar

Escreva frontmatter com name e description
Escreva body com workflows principais
Crie scripts necessários
Adicione referências
Inclua assets

Etapa 5: Testar

# Copie para skills locais
cp -r minha-skill ~/clawd/skills/

# Reinicie gateway
openclaw gateway restart

# Teste com conversa real
openclaw chat "Use minha skill para..."

Etapa 6: Iterar

Após testar, identifique:

Onde o OpenClaw teve dificuldade?
Que informação faltou?
O que pode ser simplificado?

Publicação no ClawHub

Preparação

Valide a estrutura:
- SKILL.md com frontmatter correto
- Nome em lowercase com hífens
- Description clara e completa
Teste localmente:
```
openclaw skill validate ./minha-skill
```

Publicar

# Login (primeira vez)
clawdhub login

# Validar
clawdhub validate ./minha-skill

# Publicar
clawdhub publish ./minha-skill

Atualizar

# Edite a skill
# Incremente versão se necessário

# Publique atualização
clawdhub publish --update ./minha-skill

Exemplos Completos

Skill Simples: Pomodoro

pomodoro/
└── SKILL.md

SKILL.md:

---
name: pomodoro
description: |
  Técnica Pomodoro para produtividade. Use quando o usuário 
  quiser focar em trabalho com timers e pausas estruturadas.
---

# Pomodoro

## Comandos

### Iniciar Sessão
Quando pedido para "iniciar pomodoro" ou "focar":
1. Confirmar tarefa a ser trabalhada
2. Iniciar timer de 25 minutos
3. Notificar quando acabar
4. Perguntar se quer pausa de 5 minutos

### Pausa
Quando pedido "pausa":
1. Timer de 5 minutos (ou 15 se 4ª pausa)
2. Notificar quando acabar
3. Perguntar se quer continuar

## Estatísticas
Ao final do dia, posso resumir:
- Quantos pomodoros completados
- Tempo total focado
- Tarefas concluídas

Skill com Scripts: Imagens

image-processor/
├── SKILL.md
└── scripts/
    ├── resize_image.py
    └── convert_format.py

SKILL.md:

---
name: image-processor
description: |
  Processamento de imagens: redimensionar, converter formatos, 
  comprimir. Use para manipulação de arquivos de imagem.
---

# Processador de Imagens

## Redimensionar

```bash
python scripts/resize_image.py input.jpg output.jpg 800 600

Parâmetros: largura, altura (mantém proporção se um for 0)

Converter Formato

python scripts/convert_format.py input.png output.webp

Formatos suportados: jpg, png, webp, gif, bmp

Comprimir

Para reduzir tamanho:

python scripts/resize_image.py input.jpg output.jpg 0 0 --quality 80


### Skill com Referências: BigQuery

bigquery/ ├── SKILL.md └── references/ ├── finance-schema.md └── common-queries.md


**SKILL.md:**
```markdown
---
name: bigquery
description: |
  Consultas BigQuery para analytics. Use quando precisar de 
  dados de vendas, finanças ou produto do data warehouse.
---

# BigQuery Analytics

## Início Rápido

```sql
SELECT * FROM `projeto.dataset.tabela` LIMIT 10

Domínios

Finanças (receita, custos): ver finance-schema.md
Queries comuns: ver common-queries.md

Conexão

Use credenciais do ambiente:

from google.cloud import bigquery
client = bigquery.Client()


---

## Checklist Final

Antes de publicar, verifique:

- [ ] SKILL.md tem frontmatter com `name` e `description`
- [ ] Nome usa apenas letras minúsculas, números e hífens
- [ ] Description explica O QUE faz e QUANDO usar
- [ ] Body tem menos de 500 linhas
- [ ] Scripts foram testados e funcionam
- [ ] Referências estão linkadas corretamente
- [ ] Não há arquivos desnecessários (README, CHANGELOG, etc.)
- [ ] Testei a skill localmente com casos reais

---

## Próximos Passos

- [ClawHub — Marketplace de Skills](https://clawdhub.com)
- [Contribuir com Skills](/contribuir/skills/)
- [Skills Disponíveis](/skills/)
- [Discord — Suporte da Comunidade](https://discord.com/invite/clawd)

Guia Completo de Desenvolvimento de Skills — OpenClaw

Guia Completo de Desenvolvimento de Skills

O Que São Skills?

O Que Skills Fornecem

Anatomia de uma Skill

Estrutura do SKILL.md

1. Frontmatter YAML (Obrigatório)

2. Body Markdown (Obrigatório)

Princípios de Design

1. Concisão é Essencial

Assets (assets/)

Funcionalidades Avançadas

Padrão 3: Organização por Variante

Convenções de Scripts

Nomenclatura

Estrutura Python

Estrutura Bash

Tratamento de Erros

O Que NÃO Incluir

Processo de Criação

Etapa 1: Entender com Exemplos Concretos

Etapa 2: Planejar Recursos Reutilizáveis

Etapa 3: Criar Estrutura

Etapa 4: Implementar

Etapa 5: Testar

Etapa 6: Iterar

Publicação no ClawHub

Preparação

Publicar

Atualizar

Exemplos Completos

Skill Simples: Pomodoro

Skill com Scripts: Imagens

Converter Formato

Comprimir

Domínios

Conexão

📚 Continue aprendendo

Contribuir com Skills — Publicar no ClawdHub

5 Skills Essenciais que Todo OpenClaw Precisa Ter

Como Criar Skills para OpenClaw - Guia Completo

Assets (`assets/`)