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

You installed OpenClaw. Your agent can search the web, write files, and chat across Telegram, Discord, and Signal. That's already powerful — but you're using maybe 10% of what OpenClaw can do.

The real leverage lives in OpenClaw's skills system. Skills are self-contained tool packages that teach your agent new capabilities. Install one with a single command, and your agent instantly knows how to use it — no code changes, no restarts.

There are 5,400+ skills on ClawHub covering everything from SEO research to GitHub automation to browser control. But the most powerful skill is the one you write yourself. Here's exactly how to build custom OpenClaw skills in 2026.

What Is an OpenClaw Skill?

An OpenClaw skill is a directory containing a SKILL.md file with YAML frontmatter and instructions. Your agent reads this file at session start and learns what tools it has available and how to use them.

Every skill can contain:

Component	Required	Purpose
SKILL.md	Yes	YAML frontmatter + markdown instructions that teach the agent
scripts/	No	Python, Bash, or Node.js scripts the agent can execute
templates/	No	Default settings, prompt templates, API key placeholders

When the agent starts a new session, it scans all skill directories, reads every SKILL.md, and builds its internal tool registry. Skills that mention specific triggers (like "when the user asks about weather") teach the agent when to activate automatically.

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:

Priority	Source	Path	Visible To
1 (highest)	Workspace skills	<workspace>/skills	Only that agent
2	Project agent skills	<workspace>/.agents/skills	Only that workspace's agent
3	Personal agent skills	~/.agents/skills	All agents on that machine
4	Managed/local skills	~/.openclaw/skills	All agents on that machine
5	Bundled skills	Shipped with install	All agents
6	Extra skill folders	skills.load.extraDirs (config)	All agents on that machine

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

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.

← Back to all posts