OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Skills

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:

    bash
    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:

    bash
    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.

    markdown
    ---name: hello-worlddescription: Uma skill simples que exibe uma saudação.--- # Olá, mundo Quando o usuário pedir uma saudação, use a ferramenta `exec` para executar: ```bashecho "Olá da sua skill personalizada!"
    Code
     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.  OPENCLAW_DOCS_MARKER:stepClose:   OPENCLAW_DOCS_MARKER:stepOpen:IHRpdGxlPSJWZXJpZmlxdWUgc2UgYSBza2lsbCBmb2kgY2FycmVnYWRhIg ```bashopenclaw 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:

    bash
    # Pelo chat — arquive a sessão atual e inicie uma nova/new # Ou reinicie o Gatewayopenclaw gateway restart

  • Teste

    bash
    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:

    markdown
    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:

    markdown
    ---name: gemini-searchdescription: 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:

    json5
    {  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.

    bash
    # Proponha uma skill totalmente novaopenclaw 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 existenteopenclaw 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:

    bash
    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:

    bash
    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

    bash
    npm i -g clawhubclawhub login

  • Publique

    bash
    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

    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.
    Was this useful?
    On this page

    On this page