English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

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.

For how skills are loaded and prioritized, see Skills.

Create your first skill

  • Create the skill directory

    Skills live in your workspace. Create a new folder:

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

  • Write SKILL.md

    Create SKILL.md inside that directory. The frontmatter defines metadata, and the markdown body contains instructions for the agent.

    ---
name: hello-world
description: A simple skill that says hello.
---

# Hello World Skill

When the user asks for a greeting, use the `echo` tool to say
"Hello from your custom skill!".

    Use hyphen-case with lowercase letters, digits, and hyphens for the skill name. Keep the folder name and frontmatter name aligned.

  • Add tools (optional)

    You can define custom tool schemas in the frontmatter or instruct the agent to use existing system tools (like exec or browser). Skills can also ship inside plugins alongside the tools they document.

  • Load the skill

    Start a new session so OpenClaw picks up the skill:

    # From chat
/new

# Or restart the gateway
openclaw gateway restart

    Verify the skill loaded:

    openclaw skills list

  • Test it

    Send a message that should trigger the skill:

    openclaw agent --message "give me a greeting"

    Or just chat with the agent and ask for a greeting.

    • Skill metadata reference

    The YAML frontmatter supports these fields:

    Field Required Description
    name Yes Unique identifier using lowercase letters, digits, and hyphens
    description Yes One-line description shown to the agent
    metadata.openclaw.os No OS filter (["darwin"], ["linux"], etc.)
    metadata.openclaw.requires.bins No Required binaries on PATH
    metadata.openclaw.requires.config No Required config keys

    Best practices

    • Be concise — instruct the model on what to do, not how to be an AI
    • Safety first — if your skill uses exec, ensure prompts don't allow arbitrary command injection from untrusted input
    • Test locally — use openclaw agent --message "..." to test before sharing
    • Use ClawHub — browse and contribute skills at ClawHub

    Where skills live

    Location Precedence Scope
    \<workspace\>/skills/ Highest Per-agent
    \<workspace\>/.agents/skills/ High Per-workspace agent
    ~/.agents/skills/ Medium Shared agent profile
    ~/.openclaw/skills/ Medium Shared (all agents)
    Bundled (shipped with OpenClaw) Low Global
    skills.load.extraDirs Lowest Custom shared folders