Visão geral
Em uma arquitetura multiagente, as Skills são o meio central pelo qual um agente percebe e utiliza ferramentas. O OpenClaw, como um framework de runtime de agentes maduro, implementa um mecanismo de invocação em camadas: descoberta de skills, resolução de prioridade, filtragem no carregamento e controle de visibilidade por agente — cada etapa com regras explícitas. Este artigo disseca a arquitetura em camadas para que desenvolvedores e operadores entendam exatamente como as skills são carregadas, filtradas e invocadas.
O que é uma Skill?
No OpenClaw, toda Skill é um diretório contendo um arquivo SKILL.md. Esse arquivo combina frontmatter YAML com instruções em Markdown que dizem ao agente quando e como usar uma ferramenta específica. Um layout típico:
skills/
github/
SKILL.md
weather/
SKILL.md
wp-post-from-outline/
SKILL.md
scripts/Quando um agente é iniciado, o OpenClaw varre todos os diretórios de skills registrados, injeta as skills qualificadas no prompt do sistema e o agente pode invocá-las na conversa.
As seis camadas de prioridade de carregamento
O OpenClaw carrega skills de múltiplas fontes. Quando skills com o mesmo nome aparecem em locais diferentes, a fonte de maior prioridade vence. A ordem, da maior para a menor:
Camada 1: Skills do workspace — <workspace>/skills/. Cada agente tem seu próprio workspace; skills aqui são visíveis apenas para aquele agente e sobrepõem qualquer skill de mesmo nome em outros locais.
Camada 2: Skills de agente do projeto — <workspace>/.agents/skills/. Skills compartilhadas no nível do workspace, visíveis para os agentes daquele workspace.
Camada 3: Skills pessoais de agente — ~/.agents/skills/. Skills pessoais no nível da máquina, visíveis para todos os agentes.
Camada 4: Skills gerenciadas/locais — ~/.openclaw/skills/. Para sobrescritas e patches locais, compartilhadas por todos os agentes.
Camada 5: Skills embutidas — distribuídas junto com a instalação do OpenClaw; menor prioridade padrão.
Camada 6: Pastas extras de skills — configuradas via skills.load.extraDirs; também com a menor prioridade.
A disposição em camadas garante uma invariante: personalização no nível do agente sempre se sobrepõe aos padrões globais, ao mesmo tempo em que preserva o compartilhamento flexível por baixo.
Isolamento de skills no modo multiagente
No modo de agente único, todas as skills são visíveis para o único agente. No modo multiagente, cada agente possui um workspace independente (contendo AGENTS.md, SOUL.md, USER.md e skills/), sua própria configuração de autenticação com perfis de auth separados e seu próprio armazenamento de sessões. Ao carregar, o OpenClaw primeiro mescla todas as fontes (deduplicando skills de mesmo nome por prioridade) e depois aplica a filtragem de visibilidade por agente. Ou seja: a localização/prioridade decide qual cópia vence; a allowlist do agente decide quais skills são visíveis; e os dois são dimensões de controle independentes.
A allowlist de skills do agente
A visibilidade granular é feita por meio de agents.defaults.skills e agents.list[].skills:
{
"agents": {
"defaults": {
"skills": ["github", "weather"]
},
"list": [
{ "id": "writer" },
{ "id": "docs", "skills": ["docs-search"] },
{ "id": "locked-down", "skills": [] }
]
}
}As regras: omitir agents.defaults.skills deixa todas as skills disponíveis por padrão; omitir agents.list[].skills faz o agente herdar os padrões; definir agents.list[].skills: [] deixa o agente sem nenhuma skill; e uma lista não vazia é o conjunto final — ela não é mesclada com os padrões. Esse design permite que equipes atribuam conjuntos de skills diferentes a agentes com papéis distintos: um agente de atendimento limitado a weather e search, enquanto um agente de operações recebe github e healthcheck.
O mecanismo de gating
Mesmo as skills na allowlist passam por filtragem em tempo de execução no carregamento. O campo metadata.openclaw no SKILL.md declara pré-condições:
---
name: image-lab
description: Generate images via provider
metadata: {"openclaw": {"requires": {"bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"]}}}
---Tipos de gate suportados: requires.bins (binários que devem existir no PATH), requires.anyBins (pelo menos um de vários), requires.env (variáveis de ambiente obrigatórias), requires.config (entradas obrigatórias na configuração do OpenClaw) e os (darwin/linux/win32). Apenas skills cujas todas as condições são satisfeitas são injetadas no contexto do agente — evitando que ele veja skills que não consegue usar de fato e falhe com erros.
Skills embutidas em plugins
O sistema de plugins do OpenClaw pode carregar suas próprias skills. Um plugin declara um diretório skills no openclaw.plugin.json, e habilitar o plugin carrega as skills automaticamente. O plugin browser, por exemplo, inclui a skill browser-automation, que ensina o agente a controlar o navegador em múltiplas etapas. Skills de plugins ficam no mesmo nível de skills.load.extraDirs e podem ser sobrescritas por skills do workspace ou embutidas. O design alcança autocontenção de capacidades: instale o plugin e seu manual de operação fica imediatamente disponível, sem configuração extra.
Injeção de ambiente e limites de segurança
Quando um agente executa, o OpenClaw processa em ordem: lê os metadados das skills; aplica os valores de skills.entries.<key>.env e apiKey no process.env; constrói o prompt do sistema contendo apenas as skills qualificadas; e restaura o ambiente original após a execução. A injeção de ambiente é isolada por escopo — vale apenas enquanto aquele agente executa, sem jamais tocar o shell global. Em ambientes com sandbox, os processos das skills rodam dentro do contêiner sem herdar o process.env do host, então as variáveis do sandbox devem ser configuradas separadamente via agents.defaults.sandbox.docker.env.
Snapshots e hot reload
O OpenClaw cria um snapshot das skills qualificadas no início da sessão, e os turnos seguintes da mesma sessão reutilizam esse snapshot; mudanças nas skills só valem na próxima sessão nova. Dois casos suportam hot reload durante a sessão: quando o watcher de skills está habilitado (skills.load.watch: true, ativado por padrão) e quando um novo nó macOS remoto aparece. O watcher atualiza o snapshot em eventos de alteração do arquivo SKILL.md, com debounce de 250ms.
O custo em tokens, quantificado
As skills qualificadas são injetadas no prompt do sistema como uma lista XML compacta, e o custo em tokens é determinístico: um custo-base de 195 caracteres assim que houver pelo menos uma skill, mais 97 caracteres por skill mais os tamanhos escapados em XML de seu nome, descrição e localização. A fórmula: total = 195 + Σ(97 + len(name) + len(description) + len(location)). Pela estimativa aproximada da OpenAI de quatro caracteres por token, cada skill custa cerca de 24 tokens de custo-base mais o conteúdo de seus campos — ou seja, manter a quantidade de skills sob controle reduz diretamente o custo de contexto.
Uma configuração multiagente prática
Suponha que uma equipe precise de três agentes: main, um assistente do dia a dia com skills gerais; coding, um assistente de código com skills de GitHub e programação; e family, um assistente doméstico com acesso restrito:
{
"agents": {
"defaults": {
"skills": ["weather", "search", "summarizer"]
},
"list": [
{
"id": "main",
"workspace": "~/.openclaw/workspace-main"
},
{
"id": "coding",
"workspace": "~/.openclaw/workspace-coding",
"skills": ["github", "coding-agent", "summarizer"]
},
{
"id": "family",
"workspace": "~/.openclaw/workspace-family",
"skills": ["weather"],
"sandbox": { "mode": "all" }
}
]
}
}Os três agentes compartilham uma mesma máquina e um mesmo processo de gateway, mas a visibilidade das skills é totalmente isolada — e o agente family ainda roda dentro de um sandbox.
Conclusão
O mecanismo de skills em camadas do OpenClaw se resume a três estratos: uma camada de descoberta de seis níveis de prioridade, em que a skill de mesmo nome com maior prioridade vence; uma camada de filtragem cujo gating de bins/env/config/os garante que as skills realmente possam executar; e uma camada de visibilidade de allowlists por agente para permissões granulares. O design é flexível — cada camada é configurada de forma independente — e seguro, com isolamento por sandbox e controle por allowlist. Para qualquer implantação multiagente, entender esse mecanismo é a chave para construir uma infraestrutura de agentes confiável.
Tags: OpenClaw, agente, skills, multiagente, sistema de skills
