Skills
Criando Skills
Skills ensinam ao agente como e quando usar ferramentas. Cada habilidade é um diretório
contendo 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 habilidade
Crie o diretório da habilidade
Skills ficam na pasta skills/ do seu workspace. Crie um diretório para sua
nova habilidade:
mkdir -p ~/.openclaw/workspace/skills/hello-worldVocê pode agrupar Skills em subpastas para organização — a habilidade ainda é
nomeada pelo frontmatter do SKILL.md, não pelo caminho da pasta:
mkdir -p ~/.openclaw/workspace/skills/personal/hello-world# skill name is still "hello-world", invoked as /hello-worldEscreva o SKILL.md
Crie SKILL.md dentro do diretório. O frontmatter define metadados;
o corpo fornece instruções ao agente.
---name: hello-worlddescription: A simple skill that prints a greeting.--- # Hello World When the user asks for a greeting, use the `exec` tool to run: ```bashecho "Hello from your custom skill!" Regras de nomenclatura:- Use letras minúsculas, dígitos e hífens para `name`.- Mantenha o nome do diretório e o `name` do frontmatter alinhados.- `description` é exibido para o agente e na descoberta de comandos de barra — mantenha em uma linha e com menos de 160 caracteres. OPENCLAW_DOCS_MARKER:stepClose: OPENCLAW_DOCS_MARKER:stepOpen:IHRpdGxlPSJWZXJpZmlxdWUgc2UgYSBoYWJpbGlkYWRlIGZvaSBjYXJyZWdhZGEi ```bashopenclaw skills listPor 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:
# From chat — archive current session and start fresh/new # Or restart the gatewayopenclaw gateway restartTeste
Envie uma mensagem que deve acionar a habilidade:
openclaw agent --message "give me a greeting"Ou abra um chat e pergunte 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 |
Slug único usando letras minúsculas, dígitos e hífens |
description |
Descrição em 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 habilidade como um comando de barra do usuário |
disable-model-invocation |
false |
Mantém a habilidade fora do prompt de sistema do agente (ainda executa via /skill) |
command-dispatch |
— | Defina como tool para rotear o comando de barra diretamente para uma ferramenta, ignorando o modelo |
command-tool |
— | Nome da ferramenta a invocar quando command-dispatch: tool estiver definido |
command-arg-mode |
raw |
Para despacho de ferramenta, encaminha a string de argumentos bruta para a ferramenta |
homepage |
— | URL exibida como "Site" na UI de Skills do macOS |
Para campos de controle de acesso (requires.bins, requires.env etc.), veja
Skills — Controle de acesso.
Usando {baseDir}
Use {baseDir} no corpo da habilidade para referenciar arquivos dentro do diretório
da habilidade sem codificar caminhos fixos:
Run the helper script at `{baseDir}/scripts/run.sh`.Adicionando ativação condicional
Restrinja sua habilidade para que ela só carregue quando suas dependências estiverem disponíveis:
---name: gemini-searchdescription: Search using Gemini CLI.metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }---Opções de controle de acesso
| 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 ser verdadeiro |
os |
Filtro de plataforma: ["darwin"], ["linux"], ["win32"] |
always |
Defina como true para ignorar todos os controles e sempre incluir a habilidade |
Referência completa: Skills — Controle de acesso.
Ambiente e chaves de API
Vincule uma chave de API a uma entrada de habilidade em openclaw.json:
{ skills: { entries: { "gemini-search": { enabled: true, apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, }, }, },}A chave é injetada no processo host apenas para aquela rodada do agente. Ela não chega ao sandbox — veja variáveis de ambiente em sandbox.
Proponha via Workshop de Habilidades
Para Skills redigidas pelo agente ou quando você quiser revisão do operador antes de uma habilidade entrar
em produção, use propostas do Workshop de Habilidades em vez de escrever
SKILL.md diretamente.
# Propose a brand-new skillopenclaw skills workshop propose-create \ --name "hello-world" \ --description "A simple skill that prints a greeting." \ --proposal ./PROPOSAL.md # Propose an update to an existing skillopenclaw skills workshop propose-update hello-world \ --proposal ./PROPOSAL.md \ --description "Updated greeting skill"Use --proposal-dir quando a proposta incluir arquivos de suporte:
openclaw skills workshop propose-create \ --name "hello-world" \ --description "A simple skill that prints a greeting." \ --proposal-dir ./hello-world-proposal/O diretório deve conter PROPOSAL.md. Arquivos de suporte podem 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>Veja Workshop de Habilidades para o ciclo de vida completo da proposta.
Publicando no ClawHub
Garanta que seu SKILL.md esteja completo
Certifique-se de que name, description e quaisquer campos de controle
metadata.openclaw estejam definidos. Adicione uma URL homepage se você tiver uma página do projeto.
Instale a habilidade do ClawHub
A habilidade do ClawHub documenta o formato atual do comando de publicação e os metadados obrigatórios:
openclaw skills install @openclaw/clawhub-publishPublique
clawhub publishVeja ClawHub — Publicação para o fluxo completo.
Boas práticas
Relacionados
Ordem de carregamento, controle de acesso, allowlists e formato do SKILL.md.
Fila de propostas para Skills redigidas pelo agente.
Esquema completo de configuração skills.*.
Navegue e publique Skills no registro público.
Plugins podem distribuir Skills junto com as ferramentas que documentam.
