Criando Skills

Skills ensinam ao agente como e quando usar ferramentas. Cada skill é um diretório que contém um arquivo SKILL.md com frontmatter YAML e instruções em Markdown. O OpenClaw carrega skills de várias raízes em uma ordem de precedência definida.

Crie sua primeira skill

Crie o diretório da skill

As Skills ficam na pasta skills/ do seu espaço de trabalho:

mkdir -p ~/.openclaw/workspace/skills/hello-world

Você pode agrupar skills em subpastas para organizá-las — a skill ainda é nomeada pelo frontmatter do SKILL.md, não pelo caminho da pasta:

mkdir -p ~/.openclaw/workspace/skills/personal/hello-world
# o nome da skill continua sendo "hello-world", invocada como /hello-world

Escreva o SKILL.md

O frontmatter define os metadados; o corpo fornece instruções ao agente.

---
name: hello-world
description: Uma skill simples que exibe uma saudação.
---

# Olá, mundo

Quando o usuário pedir uma saudação, use a ferramenta `exec` para executar:

```bash
echo "Olá da sua skill personalizada!"

Regras de nomenclatura:
- Use letras minúsculas, dígitos e hífens em `name`.
- Mantenha o nome do diretório e o `name` do frontmatter alinhados.
- `description` é exibido ao agente e na descoberta de comandos de barra —
  mantenha-o em uma única linha e com menos de 160 caracteres.

</Step>

<Step title="Verifique se a skill foi carregada">
```bash
openclaw skills list

Por padrão, o OpenClaw monitora arquivos SKILL.md nas raízes de skills. Se o monitor estiver desativado ou você estiver continuando uma sessão existente, inicie uma nova para que o agente receba a lista atualizada:

# Pelo chat — arquive a sessão atual e inicie uma nova
/new

# Ou reinicie o Gateway
openclaw gateway restart

Teste

openclaw agent --message "me dê uma saudação"

Ou abra um chat e peça diretamente ao agente. Use /skill hello-world para invocá-la explicitamente pelo nome.

Referência do SKILL.md

Campos obrigatórios

Campo	Descrição
`name`	Identificador exclusivo com letras minúsculas, dígitos e hífens
`description`	Descrição de uma linha exibida ao agente e na saída de descoberta

Chaves opcionais do frontmatter

Campo	Padrão	Descrição
`user-invocable`	`true`	Expõe a skill como um comando de barra do usuário
`disable-model-invocation`	`false`	Mantém a skill fora do prompt de sistema do agente (ainda é executada via `/skill`)
`command-dispatch`	—	Defina como `tool` para encaminhar o comando de barra diretamente a uma ferramenta, ignorando o modelo
`command-tool`	—	Nome da ferramenta a invocar quando `command-dispatch: tool` estiver definido
`command-arg-mode`	`raw`	Para encaminhamento à ferramenta, repassa a string bruta de argumentos à ferramenta
`homepage`	—	URL exibida como “Website” na interface de Skills do macOS

Para campos de controle de disponibilidade (requires.bins, requires.env etc.), consulte Skills — Controle de disponibilidade.

Como usar `{baseDir}`

Faça referência a arquivos dentro do diretório da skill sem fixar caminhos — o agente resolve {baseDir} em relação ao próprio diretório da skill:

Execute o script auxiliar em `{baseDir}/scripts/run.sh`.

Como adicionar ativação condicional

Restrinja sua skill para que ela seja carregada somente quando suas dependências estiverem disponíveis:

---
name: gemini-search
description: Pesquise usando a CLI do Gemini.
metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }
---

Opções de controle de disponibilidade

Chave	Descrição
`requires.bins`	Todos os binários devem existir no `PATH`
`requires.anyBins`	Pelo menos um binário deve existir no `PATH`
`requires.env`	Cada variável de ambiente deve existir no processo ou na configuração
`requires.config`	Cada caminho de `openclaw.json` deve ter um valor verdadeiro
`os`	Filtro de plataforma: `["darwin"]`, `["linux"]`, `["win32"]`
`always`	Defina como `true` para ignorar todos os controles e sempre incluir a skill

Referência completa: Skills — Controle de disponibilidade.

Ambiente e chaves de API

Vincule uma chave de API a uma entrada de skill em openclaw.json:

{
  skills: {
    entries: {
      "gemini-search": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
      },
    },
  },
}

A chave é injetada no processo hospedeiro somente durante aquele turno do agente. Ela não chega à sandbox — consulte variáveis de ambiente na sandbox.

Proponha por meio do Skill Workshop

Para skills elaboradas pelo agente ou quando você quiser a revisão do operador antes que uma skill entre em uso, utilize propostas do Skill Workshop em vez de escrever o SKILL.md diretamente.

# Proponha uma skill totalmente nova
openclaw skills workshop propose-create \
  --name "hello-world" \
  --description "Uma skill simples que exibe uma saudação." \
  --proposal ./PROPOSAL.md

# Proponha uma atualização para uma skill existente
openclaw skills workshop propose-update hello-world \
  --proposal ./PROPOSAL.md \
  --description "Skill de saudação atualizada"

Use --proposal-dir quando a proposta incluir arquivos de suporte:

openclaw skills workshop propose-create \
  --name "hello-world" \
  --description "Uma skill simples que exibe uma saudação." \
  --proposal-dir ./hello-world-proposal/

O diretório deve conter PROPOSAL.md em sua raiz. Os arquivos de suporte devem ficar em assets/, examples/, references/, scripts/ ou templates/. Após a revisão:

openclaw skills workshop inspect <proposal-id>
openclaw skills workshop apply <proposal-id>

Consulte Skill Workshop para conhecer o ciclo de vida completo das propostas.

Publicação no ClawHub

Verifique se o SKILL.md está completo

Confira se name, description e todos os campos de controle de disponibilidade em metadata.openclaw estão definidos. Adicione uma URL em homepage se você tiver uma página do projeto.

Instale a CLI independente do ClawHub e faça login

npm i -g clawhub
clawhub login

Publique

clawhub skill publish ./path/to/hello-world

Adicione --version <version> ou --owner <owner> para substituir a versão inferida ou publicar sob um proprietário específico. Consulte ClawHub — Publicação e CLI do ClawHub para conhecer o fluxo completo, o escopo de proprietários e outros comandos de manutenção (clawhub sync, clawhub skill rename, …).

Práticas recomendadas

Seja conciso — instrua o modelo sobre o que fazer, não sobre como ser uma IA.
Segurança em primeiro lugar — se sua skill usar exec, garanta que os prompts não permitam a injeção de comandos arbitrários por meio de entradas não confiáveis.
Teste localmente — use openclaw agent --message "..." antes de compartilhar.
Use o ClawHub — explore as skills da comunidade em clawhub.ai antes de criar algo do zero.

Conteúdo relacionado

Referência de Skills

Ordem de carregamento, controle de disponibilidade, listas de permissões e formato do SKILL.md.

Skill Workshop

Fila de propostas para skills elaboradas pelo agente.

Configuração de Skills

Esquema completo de configuração de skills.*.

ClawHub

Explore e publique skills no registro público.

Criação de plugins

Plugins podem incluir skills junto às ferramentas que elas documentam.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Crie sua primeira skill

Referência do SKILL.md

Campos obrigatórios

Chaves opcionais do frontmatter

Como usar `{baseDir}`

Como adicionar ativação condicional

Proponha por meio do Skill Workshop

Publicação no ClawHub

Práticas recomendadas

Conteúdo relacionado

Referência de Skills

Skill Workshop

Configuração de Skills

ClawHub

Criação de plugins

​Crie sua primeira skill

​Referência do SKILL.md

​Campos obrigatórios

​Chaves opcionais do frontmatter

​Como usar {baseDir}

​Como adicionar ativação condicional

​Proponha por meio do Skill Workshop

​Publicação no ClawHub

​Práticas recomendadas

​Conteúdo relacionado

Referência de Skills

Skill Workshop

Configuração de Skills

ClawHub

Criação de plugins

Crie sua primeira skill

Referência do SKILL.md

Campos obrigatórios

Chaves opcionais do frontmatter

Como usar `{baseDir}`

Como adicionar ativação condicional

Proponha por meio do Skill Workshop

Publicação no ClawHub

Práticas recomendadas

Conteúdo relacionado