Skills

Skills são arquivos de instruções em Markdown que ensinam ao agente como e quando usar ferramentas. Cada Skill fica em um diretório que contém um arquivo SKILL.md com frontmatter YAML e um corpo em Markdown. O OpenClaw carrega as Skills incluídas e quaisquer substituições locais, filtrando-as durante o carregamento com base no ambiente, na configuração e na presença de binários.

Criar Skills

Crie e teste uma Skill personalizada do zero.

Oficina de Skills

Revise e aprove propostas de Skills elaboradas pelo agente.

Configuração de Skills

Esquema completo de configuração skills.* e listas de permissões de agentes.

ClawHub

Explore e instale Skills da comunidade.

Ordem de carregamento

O OpenClaw carrega a partir destas fontes, da maior para a menor precedência. Quando o mesmo nome de Skill aparece em vários locais, a fonte de maior precedência prevalece.

Prioridade	Fonte	Caminho
1 — maior	Skills do espaço de trabalho	`<workspace>/skills`
2	Skills do agente do projeto	`<workspace>/.agents/skills`
3	Skills pessoais do agente	`~/.agents/skills`
4	Skills gerenciadas/locais	`~/.openclaw/skills`
5	Skills incluídas	fornecidas com a instalação
6 — menor	Diretórios adicionais	`skills.load.extraDirs` + Skills de Plugins

As raízes de Skills aceitam layouts agrupados. O OpenClaw descobre uma Skill sempre que SKILL.md aparece em qualquer local dentro de uma raiz configurada (com até 6 níveis de profundidade):

<workspace>/skills/research/SKILL.md          ✓ encontrada como "research"
<workspace>/skills/personal/research/SKILL.md ✓ também encontrada como "research"

O caminho da pasta serve apenas para organização. O nome e o comando com barra da Skill vêm do campo name do frontmatter (ou do nome do diretório quando name está ausente). As listas de permissões de agentes (abaixo) também correspondem a esse name.

O diretório nativo $CODEX_HOME/skills da Codex CLI não é uma raiz de Skills do OpenClaw. Use openclaw migrate plan codex para inventariar essas Skills e, em seguida, openclaw migrate codex para copiá-las para seu espaço de trabalho do OpenClaw.

Skills hospedadas em Node

Um Node headless conectado pode publicar Skills instaladas no diretório ativo de Skills do OpenClaw (~/.openclaw/skills por padrão; substituições de ambiente do perfil se aplicam). Elas aparecem na lista normal de Skills do agente enquanto o Node está conectado e desaparecem quando ele se desconecta. Uma Skill local ou do Gateway mantém seu nome em caso de colisão; a Skill do Node recebe um nome determinístico prefixado pelo Node. A versão v1 de Skills hospedadas em Node exige que o nome do diretório corresponda ao campo name do frontmatter da Skill. A entrada da Skill inclui o localizador do Node. Seus arquivos, referências relativas e binários ficam no Node; portanto, carregue-a e execute-a com exec host=node node=<node-id>. Reinicie o host do Node após alterar os arquivos da Skill. Consulte Nodes para saber como emparelhar e desativar esse recurso.

Skills por agente e compartilhadas

Em configurações com vários agentes, cada agente tem seu próprio espaço de trabalho. Use o caminho que corresponde à visibilidade desejada:

Escopo	Caminho	Visível para
Por agente	`<workspace>/skills`	Somente esse agente
Agente do projeto	`<workspace>/.agents/skills`	Somente o agente desse espaço de trabalho
Agente pessoal	`~/.agents/skills`	Todos os agentes nesta máquina
Gerenciado compartilhado	`~/.openclaw/skills`	Todos os agentes nesta máquina
Diretórios adicionais	`skills.load.extraDirs`	Todos os agentes nesta máquina

Listas de permissões de agentes

A localização da Skill (precedência) e sua visibilidade (qual agente pode usá-la) são controles separados. Use listas de permissões para restringir quais Skills um agente vê, independentemente de onde elas são carregadas.

{
  agents: {
    defaults: {
      skills: ["github", "weather"], // base compartilhada
    },
    list: [
      { id: "writer" }, // herda github, weather
      { id: "docs", skills: ["docs-search"] }, // substitui totalmente os padrões
      { id: "locked-down", skills: [] }, // nenhuma Skill
    ],
  },
}

Regras das listas de permissões

Omita agents.defaults.skills para deixar todas as Skills irrestritas por padrão.
Omita agents.list[].skills para herdar agents.defaults.skills.
Defina agents.list[].skills: [] para não expor nenhuma Skill a esse agente.
Uma lista agents.list[].skills não vazia é o conjunto final — ela não é combinada com os padrões.
A lista de permissões efetiva se aplica à criação de prompts, à descoberta de comandos com barra, à sincronização do sandbox e aos snapshots de Skills.
Isso não constitui um limite de autorização do shell do host. Se o mesmo agente puder usar exec, restrinja esse shell separadamente com sandboxing, isolamento de usuário do sistema operacional, listas de bloqueio/permissão do exec e credenciais por recurso.

Plugins e Skills

Plugins podem incluir suas próprias Skills listando diretórios skills em openclaw.plugin.json (caminhos relativos à raiz do Plugin). As Skills do Plugin são carregadas quando o Plugin está habilitado — por exemplo, o Plugin de navegador inclui uma Skill browser-automation para controle do navegador em várias etapas. Os diretórios de Skills de Plugins são combinados no mesmo nível de baixa precedência que skills.load.extraDirs; portanto, uma Skill incluída, gerenciada, de agente ou de espaço de trabalho com o mesmo nome os substitui. Controle a elegibilidade da própria Skill de um Plugin por meio de metadata.openclaw.requires em seu frontmatter, como em qualquer outra Skill. Consulte Plugins e Ferramentas para conhecer o sistema completo de Plugins.

Oficina de Skills

A Oficina de Skills é uma fila de propostas entre o agente e seus arquivos ativos de Skills. Quando o agente identifica um trabalho reutilizável, ele elabora uma proposta em vez de gravar diretamente em SKILL.md. Você revisa e aprova antes que qualquer alteração seja feita.

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

Consulte Oficina de Skills para conhecer o ciclo de vida completo, a referência da CLI e a configuração.

Instalação pelo ClawHub

O ClawHub é o registro público de Skills. Use os comandos openclaw skills para instalar e atualizar, ou a CLI clawhub para publicar e sincronizar.

Ação	Comando
Instalar uma Skill no espaço de trabalho	`openclaw skills install @owner/<slug>`
Instalar a partir de um repositório Git	`openclaw skills install git:owner/repo@ref`
Instalar um diretório local de Skill	`openclaw skills install ./path/to/skill --as my-tool`
Instalar para todos os agentes locais	`openclaw skills install @owner/<slug> --global`
Atualizar todas as Skills do espaço de trabalho	`openclaw skills update --all`
Atualizar uma Skill gerenciada compartilhada	`openclaw skills update @owner/<slug> --global`
Atualizar todas as Skills gerenciadas compartilhadas	`openclaw skills update --all --global`
Verificar o envelope de confiança de uma Skill	`openclaw skills verify @owner/<slug>`
Exibir o Cartão da Skill gerado	`openclaw skills verify @owner/<slug> --card`
Publicar/sincronizar pela CLI do ClawHub	`clawhub sync --all`

Detalhes da instalação

Por padrão, openclaw skills install instala no diretório skills/ do espaço de trabalho ativo. Adicione --global para instalar no diretório compartilhado ~/.openclaw/skills, visível para todos os agentes locais, a menos que as listas de permissões dos agentes restrinjam esse acesso.Instalações via Git e locais esperam encontrar SKILL.md na raiz da origem. O slug vem do campo name do frontmatter de SKILL.md quando válido e, caso contrário, usa o nome do diretório ou do repositório. Use --as <slug> para substituí-lo. openclaw skills update rastreia apenas instalações do ClawHub — reinstale origens Git ou locais para atualizá-las.

Verificação e análise de segurança

openclaw skills verify @owner/<slug> solicita ao ClawHub o envelope de confiança clawhub.skill.verify.v1 da Skill. As Skills instaladas pelo ClawHub são verificadas em relação à versão e ao registro gravados em .clawhub/origin.json. Slugs sem proprietário continuam aceitos para Skills já instaladas ou não ambíguas, mas referências qualificadas pelo proprietário evitam ambiguidades quanto ao publicador.As páginas de Skills do ClawHub exibem o estado da análise de segurança mais recente antes da instalação, com páginas de detalhes para VirusTotal, ClawScan e análise estática. O comando retorna um código diferente de zero quando o ClawHub marca a verificação como falha. Publicadores podem corrigir falsos positivos pelo painel do ClawHub ou com clawhub skill rescan @owner/<slug>.

Instalações de arquivos privados

Clientes do Gateway que precisam de distribuição fora do ClawHub podem preparar um arquivo ZIP de Skill com skills.upload.begin, skills.upload.chunk e skills.upload.commit e, em seguida, instalá-lo com skills.install({ source: "upload", ... }). Esse caminho fica desativado por padrão e exige skills.install.allowUploadedArchives: true em openclaw.json. Instalações normais pelo ClawHub nunca precisam dessa configuração.

Segurança

Trate Skills de terceiros como código não confiável. Leia-as antes de habilitá-las. Prefira execuções em sandbox para entradas não confiáveis e ferramentas de risco. Consulte Sandboxing para conhecer os controles do lado do agente.

Contenção de caminhos

A descoberta de Skills no espaço de trabalho, no agente do projeto e em diretórios adicionais aceita apenas raízes de Skills cujo caminho real resolvido permaneça dentro da raiz configurada, a menos que skills.load.allowSymlinkTargets confie explicitamente em uma raiz de destino. A Oficina de Skills grava por meio desses destinos confiáveis somente quando skills.workshop.allowSymlinkTargetWrites está habilitado. Os diretórios gerenciado ~/.openclaw/skills e pessoal ~/.agents/skills podem conter pastas de Skills vinculadas simbolicamente, mas o caminho real de cada SKILL.md ainda deve permanecer dentro do diretório resolvido da respectiva Skill.

Política de instalação do operador

Configure security.installPolicy para executar um comando de política local confiável antes que as instalações de Skills prossigam. A política recebe metadados e o caminho da origem preparada, aplica-se ao ClawHub, a uploads, ao Git, a origens locais, a atualizações e aos caminhos do instalador de dependências, e falha de forma segura quando o comando não consegue retornar uma decisão válida.

Escopo da injeção de segredos

skills.entries.*.env e skills.entries.*.apiKey injetam segredos no processo do host somente durante esse turno do agente — não no sandbox. Mantenha segredos fora de prompts e logs.

Para conhecer o modelo de ameaças mais amplo e as listas de verificação de segurança, consulte Segurança.

Formato de SKILL.md

Toda Skill precisa, no mínimo, de name e description no frontmatter:

---
name: image-lab
description: Gere ou edite imagens por meio de um fluxo de trabalho de imagens apoiado por um provedor
---

Quando o usuário solicitar a geração de uma imagem, use a ferramenta `image_generate`...

O OpenClaw segue a especificação AgentSkills. O frontmatter é analisado primeiro como YAML; se isso falhar, o sistema recorre a um analisador que aceita apenas uma única linha. Blocos metadata aninhados (incluindo mapeamentos YAML multilinha) são convertidos em uma string JSON e analisados novamente como JSON5; portanto, o formato de bloco mostrado em Controle de acesso funciona. Use {baseDir} no corpo para referenciar o caminho da pasta da skill.

Chaves opcionais do frontmatter

string

URL exibida como “Website” na interface de Skills do macOS. Também é compatível por meio de metadata.openclaw.homepage.

boolean

padrão:"true"

Quando true, a skill é disponibilizada como um comando de barra invocável pelo usuário.

boolean

padrão:"false"

Quando true, o OpenClaw mantém as instruções da skill fora do prompt normal do agente. A skill continua disponível como um comando de barra quando user-invocable também é true.

"tool"

Quando definido como tool, o comando de barra ignora o modelo e é encaminhado diretamente para uma ferramenta registrada.

string

Nome da ferramenta a ser invocada quando command-dispatch: tool estiver definido.

"raw"

padrão:"raw"

Para o encaminhamento à ferramenta, repassa a string de argumentos bruta à ferramenta sem análise pelo núcleo. A ferramenta recebe { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }.

Controle de acesso

O OpenClaw filtra as skills no momento do carregamento usando metadata.openclaw (objeto JSON5 incorporado ao frontmatter; consulte a observação sobre análise acima). Uma skill sem um bloco metadata.openclaw sempre é elegível, a menos que seja explicitamente desativada.

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
        "primaryEnv": "GEMINI_API_KEY",
      },
  }
---

boolean

Quando true, sempre inclui a skill e ignora todos os outros controles.

string

Emoji opcional exibido na interface de Skills do macOS.

string

URL opcional exibida como “Website” na interface de Skills do macOS.

("darwin" | "linux" | "win32")[]

Filtro de plataforma. Quando definido, a skill só é elegível em um sistema operacional listado.

string[]

Cada binário deve existir no PATH.

string[]

Pelo menos um binário deve existir no PATH.

string[]

Cada variável de ambiente deve existir no processo ou ser fornecida pela configuração.

string[]

Cada caminho de openclaw.json deve ter um valor verdadeiro.

string

Nome da variável de ambiente associada a skills.entries.<name>.apiKey.

object[]

Especificações opcionais de instalação usadas pela interface de Skills do macOS (brew / node / go / uv / download).

Blocos legados metadata.clawdbot ainda são aceitos quando metadata.openclaw está ausente, para que skills instaladas mais antigas mantenham seus controles de dependência e suas dicas de instalação. Novas skills devem usar metadata.openclaw.

Especificações de instalação

As especificações de instalação informam à interface de Skills do macOS como instalar uma dependência:

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install":
          [
            {
              "id": "brew",
              "kind": "brew",
              "formula": "gemini-cli",
              "bins": ["gemini"],
              "label": "Install Gemini CLI (brew)",
            },
          ],
      },
  }
---

Regras de seleção do instalador

Quando vários instaladores são listados, o Gateway escolhe uma opção preferencial (brew quando disponível; caso contrário, node).
Se todos os instaladores forem download, o OpenClaw lista cada entrada para que você possa ver todos os artefatos disponíveis.
As especificações podem incluir os: ["darwin"|"linux"|"win32"] para filtrar por plataforma.
Instalações com Node respeitam skills.install.nodeManager em openclaw.json (padrão: npm; opções: npm / pnpm / yarn / bun). Isso afeta apenas instalações de skills; o ambiente de execução do Gateway ainda deve ser Node.
Preferência de instalador do Gateway: Homebrew → uv → gerenciador de node configurado → go → download.

Detalhes por instalador

Homebrew: o OpenClaw não instala o Homebrew automaticamente nem converte fórmulas do brew em comandos do gerenciador de pacotes do sistema. Em contêineres Linux sem brew, instaladores exclusivos do brew ficam ocultos; use uma imagem personalizada ou instale a dependência manualmente.
Go: o OpenClaw exige Go 1.21 ou mais recente para instalações automáticas de skills. Se go estiver ausente e o Homebrew estiver disponível, o OpenClaw primeiro instalará o Go por meio do Homebrew; no Linux sem Homebrew, ele poderá usar apt-get como root ou por meio de sudo sem senha quando o candidato atualizado golang-go atender à versão mínima. O go install efetivo da dependência sempre usa como destino um diretório de binários dedicado e gerenciado pelo OpenClaw (o bin do Homebrew em uma instalação nova; caso contrário, ~/.local/bin), em vez do GOBIN configurado — suas próprias variáveis de ambiente GOBIN, GOPATH e GOTOOLCHAIN são lidas, mas nunca sobrescritas.
Download: url (obrigatório), archive (tar.gz | tar.bz2 | zip), extract (padrão: automático quando um arquivo compactado é detectado), stripComponents, targetDir (padrão: ~/.openclaw/tools/<skillKey>).

Observações sobre isolamento

requires.bins é verificado no host no momento do carregamento da skill. Se um agente for executado em um ambiente isolado, o binário também deverá existir dentro do contêiner. Instale-o por meio de agents.defaults.sandbox.docker.setupCommand ou de uma imagem personalizada. setupCommand é executado uma vez após a criação do contêiner e exige acesso de saída à rede, um sistema de arquivos raiz gravável e um usuário root no ambiente isolado.

Substituições de configuração

Ative e configure skills incluídas ou gerenciadas em skills.entries no arquivo ~/.openclaw/openclaw.json:

{
  skills: {
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
        config: {
          endpoint: "https://example.invalid",
          model: "nano-pro",
        },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

boolean

false desativa a skill mesmo quando ela está incluída ou instalada. A skill incluída coding-agent exige ativação — defina skills.entries.coding-agent.enabled: true e garanta que claude, codex, opencode ou outra CLI compatível esteja instalada e autenticada.

string | { source, provider, id }

Campo de conveniência para skills que declaram metadata.openclaw.primaryEnv. Aceita uma string de texto simples ou um objeto SecretRef.

Record<string, string>

Variáveis de ambiente injetadas na execução do agente. A injeção ocorre apenas quando a variável ainda não está definida no processo.

object

Conjunto opcional de campos de configuração personalizados por skill.

string[]

Lista de permissões opcional apenas para skills incluídas. Quando definida, somente as skills incluídas na lista são elegíveis. Skills gerenciadas e do espaço de trabalho não são afetadas.

Por padrão, as chaves de configuração correspondem ao nome da skill. Se uma skill definir metadata.openclaw.skillKey, use essa chave em skills.entries. Coloque nomes com hífen entre aspas: o JSON5 permite chaves entre aspas.

Injeção de ambiente

Quando uma execução de agente é iniciada, o OpenClaw:

Lê os metadados das skills

O OpenClaw resolve a lista efetiva de skills do agente, aplicando regras de controle, listas de permissões e substituições de configuração.

Injeta variáveis de ambiente e chaves de API

skills.entries.<key>.env e skills.entries.<key>.apiKey são aplicados a process.env durante a execução.

Cria o prompt do sistema

As skills elegíveis são compiladas em um bloco XML compacto e injetadas no prompt do sistema.

Restaura o ambiente

Após o término da execução, o ambiente original é restaurado.

A injeção de variáveis de ambiente é limitada à execução do agente no host, não ao ambiente isolado. Dentro de um ambiente isolado, env e apiKey não têm efeito. Consulte Configuração de Skills para saber como passar segredos a execuções em ambientes isolados.

Para o backend incluído claude-cli, o OpenClaw também materializa o mesmo snapshot de skills elegíveis como um Plugin temporário do Claude Code e o transmite por meio de --plugin-dir. Outros backends de CLI usam apenas o catálogo do prompt.

Snapshots e atualização

O OpenClaw cria um snapshot das skills elegíveis quando uma sessão é iniciada e reutiliza essa lista em todos os turnos seguintes da sessão. Alterações nas skills ou na configuração entram em vigor na próxima sessão nova. As Skills são atualizadas durante a sessão em dois casos:

O monitor de skills detecta uma alteração em SKILL.md.
Um novo node remoto elegível se conecta.

A lista atualizada é utilizada no próximo turno do agente. Se a lista de permissões efetiva do agente mudar, o OpenClaw atualizará o snapshot para manter as skills visíveis alinhadas.

Monitor de Skills

Por padrão, o OpenClaw monitora as pastas de skills e atualiza o snapshot quando arquivos SKILL.md são alterados. Configure em skills.load:

{
  skills: {
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
      watch: true, // default
      watchDebounceMs: 250, // default
    },
  },
}

Use allowSymlinkTargets para estruturas intencionais com links simbólicos em que o link simbólico da raiz de uma skill aponta para fora da raiz configurada, por exemplo, <workspace>/skills/manager -> ~/Projects/manager/skills. Ative skills.workshop.allowSymlinkTargetWrites somente quando o Skill Workshop também precisar aplicar propostas por meio desses caminhos confiáveis com links simbólicos.

Nodes macOS remotos (Gateway Linux)

Se o Gateway for executado no Linux, mas um node macOS estiver conectado com system.run permitido, o OpenClaw poderá considerar elegíveis as skills exclusivas do macOS quando os binários necessários estiverem presentes nesse node. O agente deve executar essas skills por meio da ferramenta exec com host=node.Nodes offline não tornam visíveis skills exclusivamente remotas. Se um node parar de responder às sondagens de binários, o OpenClaw removerá as correspondências de binários armazenadas em cache.

Impacto em tokens

Quando as skills são elegíveis, o OpenClaw injeta um bloco XML compacto no prompt do sistema. O custo é determinístico e cresce linearmente por skill:

Sobrecarga básica (somente quando uma ou mais skills são elegíveis): um bloco fixo de texto introdutório mais o invólucro <available_skills>.
Por skill: aproximadamente 97 caracteres mais os comprimentos dos campos name, description e location.
O escape de XML expande & < > " ' em entidades, adicionando alguns caracteres por ocorrência.
Com aproximadamente 4 caracteres por token, 97 caracteres ≈ 24 tokens por skill antes dos comprimentos dos campos.

Se o bloco renderizado exceder o orçamento de prompt configurado (skills.limits.maxSkillsPromptChars), o OpenClaw primeiro preservará o máximo possível de identidades de Skills (nome, localização e versão) que couberem no formato compacto sem descrições. Em seguida, usará o orçamento restante para descrições abreviadas. Se não restar orçamento para descrições, elas serão omitidas. O prompt incluirá uma observação indicando openclaw skills check sempre que for necessário usar a formatação compacta ou truncar a lista. Mantenha as descrições curtas e informativas para minimizar a sobrecarga do prompt.

Conteúdo relacionado

Criação de Skills

Guia passo a passo para criar uma Skill personalizada.

Oficina de Skills

Fila de propostas de Skills elaboradas por agentes.

Configuração de Skills

Esquema completo de configuração de skills.* e listas de permissões de agentes.

Comandos de barra

Como os comandos de barra de Skills são registrados e roteados.

ClawHub

Explore e publique Skills no registro público.

Plugins

Plugins podem incluir Skills junto com as ferramentas que documentam.

Overview

Plugins

Plugin guides

Building plugins

Automation

Tools

Agent coordination

Skills

Criar Skills

Oficina de Skills

Configuração de Skills

ClawHub

Ordem de carregamento

Skills hospedadas em Node

Skills por agente e compartilhadas

Listas de permissões de agentes

Plugins e Skills

Oficina de Skills

Instalação pelo ClawHub

Segurança

Formato de SKILL.md

Chaves opcionais do frontmatter

Controle de acesso

Especificações de instalação

Substituições de configuração

Injeção de ambiente

Snapshots e atualização

Impacto em tokens

Conteúdo relacionado

Criação de Skills

Oficina de Skills

Configuração de Skills

Comandos de barra

ClawHub

Plugins

Criar Skills

Oficina de Skills

Configuração de Skills

ClawHub

​Ordem de carregamento

​Skills hospedadas em Node

​Skills por agente e compartilhadas

​Listas de permissões de agentes

​Plugins e Skills

​Oficina de Skills

​Instalação pelo ClawHub

​Segurança

​Formato de SKILL.md

​Chaves opcionais do frontmatter

​Controle de acesso

​Especificações de instalação

​Substituições de configuração

​Injeção de ambiente

​Snapshots e atualização

​Impacto em tokens

​Conteúdo relacionado

Criação de Skills

Oficina de Skills

Configuração de Skills

Comandos de barra

ClawHub

Plugins

Ordem de carregamento

Skills hospedadas em Node

Skills por agente e compartilhadas

Listas de permissões de agentes

Plugins e Skills

Oficina de Skills

Instalação pelo ClawHub

Segurança

Formato de SKILL.md

Chaves opcionais do frontmatter

Controle de acesso

Especificações de instalação

Substituições de configuração

Injeção de ambiente

Snapshots e atualização

Impacto em tokens

Conteúdo relacionado