Estrutura de Skills
Como um skill do OpenClaw é organizado: SKILL.md, frontmatter, scripts, referências e assets.
Estrutura de um Skill
Todo skill do OpenClaw segue uma estrutura padronizada que facilita a criação, manutenção e distribuição.
meu-skill/
├── SKILL.md ← Obrigatório: instruções e metadados
├── scripts/ ← Opcional: código executável
│ ├── processar.py
│ └── validar.sh
├── references/ ← Opcional: documentação de referência
│ ├── api-docs.md
│ └── schemas.md
└── assets/ ← Opcional: arquivos para output
├── template.html
└── logo.png
O arquivo SKILL.md é o coração de todo skill. Ele contém:
---
name: meu-skill
description: Descrição clara do que o skill faz e quando usar.
homepage: https://exemplo.com/docs
metadata:
openclaw:
emoji: "🔧"
requires:
bins: ["curl", "jq"]
install:
- id: brew
kind: brew
formula: jq
bins: ["jq"]
label: "Instalar jq (brew)"
---
Campos obrigatórios:
name: Nome do skill em lowercase com hífensdescription: Crítico! O OpenClaw usa isso para decidir quando ativar o skill
Campos opcionais:
homepage: Link para documentaçãometadata.openclaw.emoji: Emoji para identificaçãometadata.openclaw.requires.bins: Binários necessáriosmetadata.openclaw.install: Instruções de instalação de dependências
O corpo do SKILL.md contém as instruções que o OpenClaw segue quando o skill é ativado.
# Nome do Skill
Breve descrição do propósito.
## Quando usar
- Gatilho 1
- Gatilho 2
## Quick Start
\`\`\`bash
comando exemplo
\`\`\`
## Opções Avançadas
Detalhes adicionais...
- Seja conciso - A janela de contexto é compartilhada. Cada token conta.
- Presuma inteligência - O modelo já é capaz. Só adicione o que ele não sabe.
- Exemplos > explicações - Um exemplo vale mais que três parágrafos.
- Máximo ~500 linhas - Se passar disso, mova para
references/.
Scripts executáveis para tarefas determinísticas ou repetitivas.
Quando usar:
- Código que seria reescrito toda vez
- Operações que precisam de confiabilidade determinística
- Tarefas complexas com múltiplas etapas
Exemplo:
# scripts/rotate_pdf.py
#!/usr/bin/env python3
import sys
from pypdf import PdfReader, PdfWriter
def rotate_pdf(input_path, output_path, degrees=90):
reader = PdfReader(input_path)
writer = PdfWriter()
for page in reader.pages:
page.rotate(degrees)
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]))
No SKILL.md:
## Rotacionar PDF
Use o script incluso:
\`\`\`bash
python scripts/rotate_pdf.py input.pdf output.pdf 90
\`\`\`
Documentação de referência carregada sob demanda.
Quando usar:
- Schemas de banco de dados
- Documentação de API
- Guias detalhados de workflow
- Políticas e regras de negócio
Estrutura recomendada:
references/
├── api-docs.md ← Documentação da API
├── schemas.md ← Schemas de dados
├── workflows.md ← Processos detalhados
└── examples.md ← Exemplos extensivos
No SKILL.md:
## API Reference
Para detalhes completos da API, veja [references/api-docs.md](references/api-docs.md).
## Schemas
Schemas do banco de dados em [references/schemas.md](references/schemas.md).
Dica: Para arquivos grandes (>100 linhas), inclua um sumário no topo.
Arquivos usados no output, não carregados em contexto.
Quando usar:
- Templates (HTML, DOCX, PPTX)
- Imagens e logos
- Boilerplate de código
- Fontes e recursos visuais
Exemplos:
assets/
├── template.html ← Template de relatório
├── logo.png ← Logo para documentos
├── slides.pptx ← Base para apresentações
└── frontend/ ← Boilerplate de projeto
├── index.html
└── style.css
No SKILL.md:
## Criar Relatório
Copie o template:
\`\`\`bash
cp assets/template.html output/relatorio.html
\`\`\`
Edite conforme necessário e adicione o logo de assets/logo.png.
Um skill deve conter apenas o essencial. NÃO crie:
- ❌ README.md
- ❌ INSTALLATION_GUIDE.md
- ❌ CHANGELOG.md
- ❌ CONTRIBUTING.md
- ❌ Documentação para humanos
O skill é para o agente de IA, não para leitura humana. Toda informação necessária deve estar no SKILL.md ou em references/.
Nome do skill: lowercase, hífens, sem espaços
- ✅
pdf-editor - ✅
github-pr-review - ❌
PDF Editor - ❌
githubPRReview
- ✅
Máximo 64 caracteres
Prefira verbos:
rotate-pdf,send-email,analyze-dataNamespace quando útil:
gh-create-issue,linear-update-ticket
Calibre a especificidade das instruções:
| Liberdade | Quando usar | Exemplo |
|---|---|---|
| Alta | Múltiplas abordagens válidas | “Organize os arquivos de forma lógica” |
| Média | Padrão preferido com variações | Pseudocódigo com parâmetros |
| Baixa | Operações frágeis/críticas | Script específico com poucos parâmetros |
Metáfora: Pense no agente explorando um caminho. Uma ponte estreita sobre precipício precisa de corrimãos específicos (baixa liberdade). Um campo aberto permite muitas rotas (alta liberdade).