Plugins ou skills no OpenClaw 2.0: qual escolher para o seu caso?

Escrever um plugin inteiro, com manifesto, build e empacotamento, pra resolver algo que um SKILL.md mínimo já resolvia: esse é o desperdício mais comum de quem chega agora no OpenClaw

Fala aí, beleza? O OpenClaw 2.0 (apelido da v2026.8.1, publicada em 31 de agosto de 2026) é a maior atualização da história do projeto, feita por 933 contribuidores, sendo 569 de primeira viagem, com mais de 16.000 pull requests

E junto com esse tamanho todo vieram duas formas bem separadas de estender o agente: skill e plugin

As duas funcionam, as duas têm CLI própria, as duas vivem no ClawHub

O problema é que escolher a errada não dá erro na tela, só cobra o teu tempo depois

Então bora decidir isso por caso de uso, e não por hype

Plugins e skills lado a lado no OpenClaw 2.0

Antes de qualquer cenário, vale ver o desenho dos dois lado a lado

Repara que a diferença não é de "poder", é de NATUREZA: um entrega texto, o outro entrega código rodando

Se essa lógica te soa familiar, é porque ela é mesmo

Quem já quebrou a cabeça pra escolher entre MCP e skill no ecossistema do Claude vai reconhecer o padrão na hora: o eixo é sempre "isso é instrução ou é infraestrutura?"

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Quando a skill é a escolha certa

A documentação oficial do OpenClaw é direta nisso: skill é pra quando o agente já tem as ferramentas necessárias, mas precisa de um fluxo repetível, uma rubrica de revisão, uma sequência de comandos ou uma restrição de operação

Ou seja, o agente já sabe fazer, só não sabe do TEU jeito

Alguns casos que caem redondinho aqui:

• Padronizar revisão de código com uma rubrica fixa (o que sempre olhar, em que ordem, o que reprovar)
• Encadear aquela sequência de comandos que tu repete toda semana e sempre esquece um passo
• Impor restrição de operação, tipo "nunca mexa nesses diretórios sem confirmar"
• Distribuir um fluxo pro time inteiro rodar igual, sem depender de quem escreveu o prompt melhor

E por que isso sai tão barato? Porque a barreira de entrada é ridícula de baixa

Toda skill precisa, no mínimo, de name e description no frontmatter, e a description tem que caber em uma linha, com menos de 160 caracteres

O nome da skill e o slash command dela vêm do campo name do frontmatter, e quando name está ausente o fallback é o nome do diretório

O OpenClaw ainda descobre a skill sempre que um SKILL.md aparece em qualquer lugar sob um root configurado, até 6 níveis de profundidade

Tome cuidado com isso, aliás: 6 níveis é fundo, então uma pasta esquecida com um SKILL.md velho dentro continua sendo descoberta 😀

Quando você realmente precisa de um plugin

Agora a outra ponta

A documentação define plugin pra quando a capacidade envolve código, credenciais, lifecycle hooks, metadados de manifesto ou empacotamento instalável

Nenhuma dessas coisas cabe em markdown, por melhor que seja o texto

Os cenários típicos:

• Falar com uma API que exige credencial (skill não guarda segredo, ela é instrução no prompt)
• Registrar uma tool nova no runtime, que é justamente o primeiro item da lista oficial de capacidades de plugin
• Adicionar canal ou provedor de modelo
• Rodar lifecycle hooks
• Empacotar algo instalável pra outras pessoas, e não só pro teu workspace

A lista oficial do que um plugin pode registrar é bem completona: tools, skills, canais, provedores de modelo, fala, voz em tempo real, geração de mídia, busca web, fetch web, hooks e outras capacidades de runtime

Repara num detalhe massa: plugin pode registrar SKILL também

Ou seja, os dois não são rivais, um pode carregar o outro

A melhor evidência de que esse é o modelo de pacote do projeto veio no próprio 2.0: pacotes oficiais de provedor passaram a ser instaláveis separadamente durante o onboarding, casos de BytePlus, ComfyUI, Mistral, NovitaAI, OpenCode, Synthetic, Volcengine, Vydra e Xiaomi

E mais Cohere, Meta, busca DuckDuckGo, embeddings Voyage e mensageria iMessage como plugins oficiais separados

Olha o tipo de coisa que virou plugin: integração com serviço externo, provedor, canal de mensagem

É o mesmo raciocínio de quando você quer memória persistente entre sessões no agente: isso é capacidade de runtime, não é uma instrução bem escrita

O veredito: comece pela skill, suba para plugin só quando travar

O gatilho de migração é objetivo, e dá pra decorar em uma frase

Se entrou código, credencial, hook ou empacotamento, é plugin

Enquanto for texto e ordem de execução, skill basta

Só que nenhum dos dois é de graça, e é honesto falar do custo escondido dos dois lados

O custo escondido do plugin é o ciclo de vida dele: manifesto pra manter, build pra rodar, e a administração do enable e disable

Aqui tem uma pegadinha: mudanças de habilitação de plugin podem ser aplicadas sem reiniciar quando o plugin instalado E o runtime do Gateway suportam

Quando não suportam, a interface avisa que o restart é necessário

Dá pra viver com isso (o Gateway do OpenClaw 2.0 inicia em cerca de 575 ms, contra aproximadamente 1,6 segundo antes), mas é fricção que a skill simplesmente não tem

O custo escondido da skill é mais sutil e pega muita gente

As instruções da skill não entram no prompt por padrão: o system prompt inclui uma lista compacta com nome, descrição e localização, e o modelo lê o SKILL.md completo somente quando precisa

Esse progressive disclosure é ótimo pro consumo de contexto, mas significa que a tua description é a vitrine INTEIRA da skill

Descrição vaga, skill nunca lida

E aí você jura que a skill não funciona, quando na real ela nunca foi aberta 🙂

Os comandos que você vai usar em cada caminho

Cada caminho tem o seu conjunto de CLI, e misturar os dois é fonte clássica de confusão

Do lado das skills, o openclaw skills tem search, install, update, verify, list, info, check e o workshop (com list, inspect, propose-create, propose-update, revise, apply, reject e quarantine)

Do lado dos plugins, o openclaw plugins tem list, search, inspect, install, uninstall, update, enable, disable, doctor, build, validate, init e o registry marketplace (com list, entries e refresh)

Agora os detalhes que evitam dor de cabeça:

1. openclaw skills install <skill-slug> instala a skill no diretório skills/ do workspace ATIVO. O erro comum aqui é rodar de outro workspace e depois procurar a skill no lugar errado
2. A CLI separada clawhub instala skills em ./skills sob o diretório de trabalho atual, e registra as versões instaladas em .clawhub/lock.json. O erro comum é ignorar esse lock na hora de versionar o projeto
3. openclaw plugins install clawhub:<package> resolve pelo ClawHub, e o mesmo comando também aceita diretório local (./my-bundle), arquivo (./my-bundle.tgz) e --marketplace <source>. O erro comum é esquecer o prefixo clawhub: e não entender por que não resolveu
4. openclaw plugins list faz um inventário a frio do que o OpenClaw consegue descobrir a partir da config, dos manifestos e do registro persistido de plugins
5. openclaw plugins search consulta o ClawHub apenas por pacotes de code plugin e bundle plugin, NÃO por skills. O erro comum é procurar skill por aqui e achar que ela não existe: o comando certo é openclaw skills search
6. Esse plugins search lê só o catálogo remoto, sem inspecionar estado local, com limite padrão de 20 resultados e teto de 100. O erro comum é tomar a primeira página como "tudo o que existe"

O ClawHub, vale dizer, é o registro público de skills do OpenClaw e também expõe um catálogo nativo de pacotes pra code plugins e bundle plugins

Os dois mundos moram lá, só que com portas de entrada diferentes

O que muda se você já tinha extensões antes do OpenClaw 2.0

Se tu chega de uma versão anterior, tem três coisas pra conferir antes de sair criando extensão nova

O plugin OpenProse deixou de vir embutido no 2.0

As rotas de modelo codex/ foram renomeadas para openai/

E o openclaw doctor --fix resolve a maior parte dessa limpeza, então rode ele antes de sair caçando o problema na mão

Tem outra mudança que mexe direto com skill e plugin: o OpenClaw 2.0 introduziu modos explícitos de permissão de sessão e restrições de workspace, com acesso a arquivos ancorado no workspace ou worktree registrado

Traduzindo: onde as tuas extensões conseguem LER mudou de figura

Se você tinha uma skill contando com arquivo fora do workspace, é aí que ela vai te surpreender

Qual caminho seguir a partir de agora

A régua cabe numa linha: se é texto e ordem de execução, skill; se é código, credencial, hook ou empacotamento, plugin

O próximo passo concreto é o mais chato de aceitar e o mais barato de fazer: escreve um SKILL.md mínimo, só com name e description, e testa o slash command

Se resolveu, acabou, você economizou um manifesto, um build e um ciclo de enable e disable

Se travou em alguma das quatro palavras mágicas (código, credencial, hook, empacotamento), aí sim vale montar o pacote com dist/, openclaw.plugin.json e package.json

Na prática, a maioria absoluta dos casos do dia a dia morre na skill mesmo

E tá tudo bem, o objetivo nunca foi construir a extensão mais elaborada, foi resolver o problema…

até o próximo post!