---
title: "Estrutura de Skills"
url: "https://openclaw.ia.br/skills/estrutura/"
markdown_url: "https://openclaw.ia.br/skills/estrutura.MD"
description: "Como um skill do OpenClaw é organizado: SKILL.md, frontmatter, scripts, referências e assets."
date: "2026-02-01"
author: ""
---

# 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.

## Estrutura de Diretórios

```
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
```

## SKILL.md (Obrigatório)

O arquivo `SKILL.md` é o coração de todo skill. Ele contém:

### 1. Frontmatter YAML

```yaml
---
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ífens
- `description`: **Crítico!** O OpenClaw usa isso para decidir quando ativar o skill

**Campos opcionais:**
- `homepage`: Link para documentação
- `metadata.openclaw.emoji`: Emoji para identificação
- `metadata.openclaw.requires.bins`: Binários necessários
- `metadata.openclaw.install`: Instruções de instalação de dependências

### 2. Corpo Markdown

O corpo do SKILL.md contém as instruções que o OpenClaw segue quando o skill é ativado.

```markdown
# 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...
```

### Princípios do SKILL.md

1. **Seja conciso** - A janela de contexto é compartilhada. Cada token conta.
2. **Presuma inteligência** - O modelo já é capaz. Só adicione o que ele não sabe.
3. **Exemplos > explicações** - Um exemplo vale mais que três parágrafos.
4. **Máximo ~500 linhas** - Se passar disso, mova para `references/`.

---

## Diretório scripts/

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:**

```python
# 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:**
```markdown
## Rotacionar PDF

Use o script incluso:

\`\`\`bash
python scripts/rotate_pdf.py input.pdf output.pdf 90
\`\`\`
```

---

## Diretório references/

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:**
```markdown
## 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.

---

## Diretório assets/

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:**
```markdown
## 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.
```

---

## O Que NÃO Incluir

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/.

---

## Naming Conventions

- **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-data`
- **Namespace quando útil:** `gh-create-issue`, `linear-update-ticket`

---

## Graus de Liberdade

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).

---

## Próximos Passos

- [Tutorial: Criar seu primeiro skill](/skills/criar-skill/)
- [Publicar no ClawHub](/skills/clawhub/)
- [Boas práticas de segurança](/skills/seguranca/)