How to Write OpenClaw Skills in 2026: Build Custom Agent Skills

Skill Precedence: Where Skills Live

OpenClaw loads skills from multiple locations with a strict precedence order. Higher sources override lower ones when skill names conflict:

If you have a skill called github in your workspace skills and another github in ~/.agents/skills, the workspace version wins. Use this hierarchy to layer custom overrides on top of community skills without modifying them.

Writing a Skill: Step by Step

Step 1: Create the skill directory

class="language-text">mkdir -p skills/my-custom-skill
cd skills/my-custom-skill

Step 2: Write the SKILL.md file

Every SKILL.md has two sections: YAML frontmatter (metadata) and markdown body (instructions).

YAML frontmatter tells OpenClaw about the skill:

class="language-yaml">---
name: my-custom-skill
description: >
 A skill that does something useful. Activated when the user asks about
 specific topics.
tools:
 - shell
 - read
model: any
config:
 max_retries: 3
 default_timeout: 30
---

The description field is critical — it's what the agent reads to determine when to activate this skill. Be specific about triggers.

Markdown body teaches the agent how to use the skill:

class="language-markdown"># My Custom Skill
This skill helps with [specific task]. When the user asks about [topic],
follow these steps:

First, use read to check the current workspace for existing files.
Then, use shell to run the analysis command.
Format results as a table with columns: Name, Status, Priority.

Configuration
This skill reads from config.yaml in the skill directory. If the file
doesn’t exist, fall back to defaults: max_retries=3, timeout=30s.
Examples
User: “Run the analysis on my project”
Agent: [runs the skill workflow]
User: “Show me results for the frontend module”
Agent: [filters results and displays them]
Tips

Always validate input paths before running commands.
If a command fails, retry up to max_retries times.
Log all actions to ~/.openclaw/logs/skill-output.log.

Step 3: Add optional scripts

If your skill needs to run code, place scripts in a scripts/ subdirectory:

class="language-text">scripts/
 analyze.sh # Shell script for analysis
 parse.py # Python script for data processing

Reference them in the SKILL.md instructions so the agent knows they exist.

Step 4: Install via npm (optional)

For distributing your skill, publish it as an npm package or submit it to ClawHub. For local use, just place it in the right directory.

Installing Skills from ClawHub

Before writing your own, check if someone already built it:

class="language-text">npx clawhub search seo
npx clawhub install seo-keyword-research

Install multiple at once:

class="language-text">npx clawhub install github content-creator weather

Update or remove:

class="language-text">npx clawhub update seo-keyword-research
rm -rf skills/seo-keyword-research

Agent Skill Allowlists

In multi-agent setups, you can control which skills each agent can use via the config:

class="language-text">{
 agents: {
 defaults: {
 skills: ["github", "weather"],
 },
 list: [
 { id: "writer" }, // inherits github, weather
 { id: "docs", skills: ["docs-search"] }, // replaces defaults
 { id: "locked-down", skills: [] }, // no skills
 ],
 },
}

Rules:

• Omit agents.defaults.skills for unrestricted access
• Omit agents.list[].skills to inherit defaults
• Set agents.list[].skills: [] for no skills
• A non-empty list is the final set — it does not merge with defaults

For more details, see the official documentation and provider benchmarks.

Plugin Skills

Plugins can ship their own skills by listing skills directories in openclaw.plugin.json. This is how the browser plugin ships its browser-automation skill — whenever the plugin is enabled, the skill is available.

Plugin skills sit at the lowest precedence (same as extra dirs), so workspace or personal skills with the same name will override them.

Skill Workshop

OpenClaw's optional Skill Workshop plugin can create or update workspace skills from procedures observed during agent work. Enable it in config:

class="language-text">plugins:
 entries:
 skill-workshop: true

It writes only to <workspace>/skills, scans generated content, supports pending approval or automatic safe writes, and refreshes the skill snapshot after successful writes — no Gateway restart needed.

Best Practices for Writing Skills

Write clear, specific descriptions. The description field in YAML frontmatter is what the agent uses to decide when to activate your skill. "A skill for code review" is too vague. "Activated when the user asks to review pull requests or analyze code changes" is better.

Use structured instructions. Numbered steps, clear conditionals ("if X, do Y"), and explicit formatting instructions produce more consistent agent behavior.

Include examples. Show the agent what a good interaction looks like. Two or three user-agent dialogue examples are worth a page of abstract instructions.

Keep scripts simple. If a skill needs a script, keep it to a single responsibility. Complex scripts should be split into multiple files with clear naming.

Test with auto mode. OpenClaw's auto mode will choose which skills to activate. Test that your skill triggers correctly by running it in various scenarios.

Document dependencies. If your skill needs API keys, specific tools, or minimum OpenClaw versions, document them in the SKILL.md so users know what's required.

Frequently Asked Questions

What format does SKILL.md need to be in?

Standard markdown with YAML frontmatter delimited by ---. The frontmatter contains metadata (name, description, tools, config). The body contains instructions for the agent.

When does OpenClaw load skills?

Skills are loaded at session start. If you add or modify a skill, start a new session for the agent to discover the changes. The Skill Workshop plugin can refresh without a restart.

How many skills can I install?

There is no hard limit, but each skill adds tokens to the system prompt. The effective skill description text contributes to every prompt. Installing hundreds of skills with verbose descriptions will increase latency and cost. Keep descriptions concise.

Can skills have dependencies on other skills?

There is no formal dependency system. If Skill A depends on Skill B, document the requirement in A's SKILL.md and include install instructions.

Are skills sandboxed for security?

Skills run with the same permissions as the OpenClaw agent process. They can execute shell commands, read/write files, and make network requests. Review community skills before installing, especially ones that request API keys or shell access.

How do I share a skill I built?

Publish it as an npm package with the openclaw-skill keyword, submit it to clawhub.ai, or contribute to the awesome-openclaw-skills repository on GitHub.

📊 See how this tool compares to alternatives

Additional context is available from GitHub Copilot and Ollama updates.

Dig deeper: OpenClaw review · IronClaw review.