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

Skills

Creating skills

Skills teach the agent how and when to use tools. Each skill is a directory containing a SKILL.md file with YAML frontmatter and markdown instructions. OpenClaw loads skills from several roots in a defined precedence order.

Create your first skill

  • Create the skill directory

    Skills live in your workspace skills/ folder:

    bash
    mkdir -p ~/.openclaw/workspace/skills/hello-world

    You can group skills in subfolders for organization — the skill is still named by the SKILL.md frontmatter, not the folder path:

    bash
    mkdir -p ~/.openclaw/workspace/skills/personal/hello-world# skill name is still "hello-world", invoked as /hello-world

  • Write SKILL.md

    The frontmatter defines metadata; the body gives the agent instructions.

    markdown
    ---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!"```

    Naming rules:

    • Use lowercase letters, digits, and hyphens for name.
    • Keep the directory name and frontmatter name aligned.
    • description is shown to the agent and in slash-command discovery — keep it one line and under 160 characters.

  • Verify the skill loaded

    bash
    openclaw skills list

    OpenClaw watches SKILL.md files under skills roots by default. If the watcher is disabled or you are continuing an existing session, start a new one so the agent receives the refreshed list:

    bash
    # From chat — archive current session and start fresh/new # Or restart the gatewayopenclaw gateway restart

  • Test it

    bash
    openclaw agent --message "give me a greeting"

    Or open a chat and ask the agent directly. Use /skill hello-world to invoke it explicitly by name.

    • Create a personal skill on a shared Gateway

    For a skill that should follow your signed-in profile rather than belong to an agent workspace, use Plugins → Skills → My skills. Create or import the SKILL.md bundle there, then review the saved revision and activation result. You do not need host shell access or permission to edit shared Gateway settings.

    You can also ask the agent to create or improve a personal skill. Its skill_workshop tool uses the Gateway's authorized library service; it does not write managed revision directories directly. The result distinguishes a published skill from a pending proposal and explains when the session can use it. Ask explicitly to use the new revision in the current session or share it with the team.

    The single-admin default remains the workspace workflow above. Extra channel identities for the same operator do not turn a personal installation into a team setup. See personal skills and revisions for ownership, sharing, storage, and session behavior.

    SKILL.md reference

    Required fields

    Field Description
    name Unique slug using lowercase letters, digits, and hyphens
    description One-line description shown to the agent and in discovery output

    Optional frontmatter keys

    Field Default Description
    user-invocable true Expose the skill as a user slash command
    disable-model-invocation false Keep the skill out of the agent's system prompt (still runs via /skill)
    command-dispatch — Set to tool to route the slash command directly to a tool, bypassing the model
    command-tool — Tool name to invoke when command-dispatch: tool is set
    command-arg-mode raw For tool dispatch, forwards the raw args string to the tool
    homepage — URL shown as "Website" in the macOS Skills UI

    For gating fields (requires.bins, requires.env, etc.) see Skills — Gating.

    Using {baseDir}

    Reference files inside the skill directory without hardcoding paths — the agent resolves {baseDir} against the skill's own directory:

    markdown
    Run the helper script at `{baseDir}/scripts/run.sh`.

    Adding conditional activation

    Gate your skill so it only loads when its dependencies are available:

    markdown
    ---name: gemini-searchdescription: Search using Gemini CLI.metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }---
    Gating options
    Key Description
    requires.bins All binaries must exist on PATH
    requires.anyBins At least one binary must exist on PATH
    requires.env Each env var must exist in the process or config
    requires.config Each openclaw.json path must be truthy
    os Platform filter: ["darwin"], ["linux"], ["win32"]
    always Include on a compatible OS even when requires.* checks fail

    Full reference: Skills — Gating.

    Environment and API keys

    Wire an API key to a skill entry in openclaw.json:

    json5
    {  skills: {    entries: {      "gemini-search": {        enabled: true,        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },      },    },  },}

    The key is injected into the host process for that agent turn only. It does not reach the sandbox — see sandboxed env vars.

    Propose via Skill Workshop

    For agent-drafted skills or when you want operator review before a skill goes live, use Skill Workshop proposals instead of writing SKILL.md directly.

    bash
    # 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 when the proposal includes support files:

    bash
    openclaw skills workshop propose-create \  --name "hello-world" \  --description "A simple skill that prints a greeting." \  --proposal-dir ./hello-world-proposal/

    The directory must contain PROPOSAL.md at its root. Support files go under assets/, examples/, references/, scripts/, or templates/.

    After review:

    bash
    openclaw skills workshop inspect <proposal-id>openclaw skills workshop evaluate <proposal-id>openclaw skills workshop apply <proposal-id>

    See Skill Workshop for the full proposal lifecycle.

    Publishing to ClawHub

    An owner is a ClawHub publisher handle, such as @alice or @your-org. Your account has a personal owner. Organization owners can have members with owner, admin, or publisher roles; all three roles can publish. Choose your personal owner or an organization where you have publisher access.

  • Ensure your SKILL.md is complete

    Make sure name, description, and any metadata.openclaw gating fields are set. Add a homepage URL if you have a project page.

  • Install the standalone ClawHub CLI and log in

    bash
    npm i -g clawhubclawhub login

  • Publish

    bash
    clawhub skill publish ./path/to/hello-world

    Add --version <version> or --owner <owner> to override the inferred version or publish under a specific owner. See ClawHub — Publishing and ClawHub CLI for the full flow, owner scoping, and other maintenance commands (clawhub sync, clawhub skill rename, ...).

    • Best practices

    Skills reference

    Loading order, gating, allowlists, and SKILL.md format.
    Skill Workshop

    Proposal queue for agent-drafted skills.
    Skills config

    Full skills.* config schema.
    ClawHub

    Browse and publish skills on the public registry.
    Building plugins

    Plugins can ship skills alongside the tools they document.
    Slash commands

    How the command a skill registers is invoked and gated.
    Was this useful?
    On this page

    On this page