--- title: "Guia Completo de Desenvolvimento de Skills — OpenClaw" url: "https://openclaw.ia.br/docs/skills-development/" markdown_url: "https://openclaw.ia.br/docs/skills-development.MD" description: "Documentação completa para criar skills para OpenClaw. Estrutura SKILL.md, scripts, assets, padrões de design e publicação no ClawHub." date: "2026-02-01" author: "" --- # Guia Completo de Desenvolvimento de Skills — OpenClaw Documentação completa para criar skills para OpenClaw. Estrutura SKILL.md, scripts, assets, padrões de design e publicação no ClawHub. # 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) ```yaml --- 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:** ```yaml 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. ```markdown # 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:** ```markdown ## O Que É um PDF PDF significa Portable Document Format. Foi criado pela Adobe em 1993... ``` ✅ **Prefira:** ```markdown ## 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:** ```markdown ## 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:** ```markdown ## 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:** ```markdown ## 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](references/forms.md) - **API completa**: Ver [REFERENCE.md](references/reference.md) - **Exemplos**: Ver [EXAMPLES.md](references/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:** ```markdown # 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 ```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 ```bash #!/bin/bash # Descrição curta do que o script faz # Uso: ./script.sh 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 ```python 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: 1. Como executar do zero? 2. 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 ```bash mkdir -p minha-skill/{scripts,references,assets} touch minha-skill/SKILL.md ``` ### Etapa 4: Implementar 1. Escreva frontmatter com name e description 2. Escreva body com workflows principais 3. Crie scripts necessários 4. Adicione referências 5. Inclua assets ### Etapa 5: Testar ```bash # 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 1. Valide a estrutura: - SKILL.md com frontmatter correto - Nome em lowercase com hífens - Description clara e completa 2. Teste localmente: ```bash openclaw skill validate ./minha-skill ``` ### Publicar ```bash # Login (primeira vez) clawdhub login # Validar clawdhub validate ./minha-skill # Publicar clawdhub publish ./minha-skill ``` ### Atualizar ```bash # 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:** ```markdown --- 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:** ```markdown --- 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 ```bash python scripts/convert_format.py input.png output.webp ``` Formatos suportados: jpg, png, webp, gif, bmp ## Comprimir Para reduzir tamanho: ```bash 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](references/finance-schema.md) - **Queries comuns**: ver [common-queries.md](references/common-queries.md) ## Conexão Use credenciais do ambiente: ```python 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)