OpenClaw Skills: SKILL.md, Loading, Precedence, and Security
Learn how OpenClaw skills work, including SKILL.md files, skill folders, loading order, precedence, allowlists, gating, and security review.
OpenClaw skills are structured instruction folders that help an agent follow repeatable workflows, use available tools correctly, and apply task-specific behavior. A skill usually contains a SKILL.md file with metadata and markdown instructions. This file tells the agent what the skill does, when it should be used, and what process it should follow.
This reference explains how OpenClaw skills work, where skills are loaded from, how precedence is resolved, how per-agent skill access works, and what to check before using third-party or custom skills.
What Are OpenClaw Skills?
OpenClaw skills are reusable instruction packages for agents.
A skill does not usually provide the agent with a new action by itself. Instead, it teaches the agent how to use existing tools or follow a specific workflow.
For example:
| Item | Role |
|---|---|
| Tool | Gives the agent something it can call or perform |
| Skill | Tells the agent how and when to use a tool or workflow |
| Plugin | Can package tools, skills, channels, model providers, or other capabilities |
OpenClaw's tools documentation describes tools as callable capabilities, skills as instructions that teach the agent when and how to use those capabilities, and plugins as packages that can include multiple extension types.
Use a skill when the agent already has access to the required tools but needs a repeatable workflow, review process, operating constraint, or task-specific behavior.
What Is a SKILL.md File?
SKILL.md is the main instruction file inside a skill folder.
The OpenClaw documentation describes each skill as a directory containing a SKILL.md file with YAML frontmatter and markdown instructions.
A minimal skill folder looks like this:
hello-world/
SKILL.mdA basic SKILL.md file can look like this:
---
name: hello_world
description: Use this skill when the user asks for a simple greeting example.
---
# Hello World Skill
When the user asks for a greeting, respond with a short greeting.- The YAML frontmatter provides metadata.
- The markdown body provides the actual instructions.
What Should Be Included in SKILL.md?
A good SKILL.md file should be clear, specific, and limited to one main workflow.
Recommended sections:
| Section | Purpose |
|---|---|
name | Defines the skill name |
description | Explains when the skill should be used |
Workflow | Gives the agent step-by-step instructions |
Tool guidance | Explains which tools to use or avoid |
Output format | Defines the expected response structure |
Safety rules | Defines limits for risky actions |
Examples | Shows expected behavior |
The description is especially important because it helps the agent decide when the skill is relevant.
Weak example:
description: Helps with docs.Better example:
description: Use this skill when the user asks to summarize technical documentation into setup steps, warnings, and implementation notes.Skills vs Tools vs Plugins
OpenClaw separates tools, skills, and plugins so each part has a clear purpose.
| Concept | Purpose | Example |
|---|---|---|
| Tool | Performs an action | Browser, shell, file access, API call |
| Skill | Guides behavior | Research workflow, code review checklist, docs summary process |
| Plugin | Packages capabilities | A plugin that includes tools, skills, config, or channels |
- Use a tool when the agent needs a callable function.
- Use a skill when the agent needs instructions for how to complete a workflow.
- Use a plugin when you want to package or install a larger capability.
This separation keeps workflows easier to manage and avoids putting every instruction into one large system prompt.
Where OpenClaw Loads Skills From
OpenClaw can load skills from multiple locations.
The current skills documentation lists workspace skills, project agent skills, personal agent skills, managed or local shared skills, bundled skills, and extra configured skill directories.
Common skill locations include:
| Location | Purpose |
|---|---|
<workspace>/skills | Workspace-specific skills |
<workspace>/.agents/skills | Project agent skills |
~/.agents/skills | Personal agent skills |
~/.openclaw/skills | Managed or local shared skills |
Bundled skills | Skills shipped with OpenClaw |
skills.load.extraDirs | Extra configured skill directories |
- Use workspace skills for project-specific behavior.
- Use shared locations only when the skill should apply across multiple projects or agents.
Skill Precedence Order
If two skills have the same name, OpenClaw uses precedence rules to decide which version wins.
The current documented precedence order is:
<workspace>/skills
ā <workspace>/.agents/skills
ā ~/.agents/skills
ā ~/.openclaw/skills
ā bundled skills
ā skills.load.extraDirsThis means a skill in <workspace>/skills has higher priority than a same-named skill in ~/.openclaw/skills, bundled skills, or skills.load.extraDirs.
Example:
~/.openclaw/skills/research-summary/SKILL.md
<workspace>/skills/research-summary/SKILL.mdIn this case, the workspace version should take priority for that workspace.
Choosing the Right Skill Location
Use this table when deciding where a skill should live.
| Need | Recommended location |
|---|---|
| One project needs custom instructions | <workspace>/skills |
| A workspace needs agent-specific behavior | <workspace>/.agents/skills |
| A personal workflow should work across projects | ~/.agents/skills |
| A shared local skill should be available across agents | ~/.openclaw/skills |
| A built-in OpenClaw skill is enough | Bundled skills |
| A shared external skill directory is needed | skills.load.extraDirs |
A safe starting point is to place new custom skills in the workspace. After the skill is tested and stable, move it to a shared location only if it is useful across more than one project.
Per-Agent Skill Allowlists
Skill loading and skill access are separate.
A skill may exist on disk, but an agent may still be restricted from using it. OpenClaw supports per-agent skill allowlists, which control which skills an agent can use.
Example configuration pattern:
{
"agents": {
"defaults": {
"skills": ["github", "weather"]
},
"list": [
{ "id": "writer" },
{ "id": "docs", "skills": ["docs-search"] },
{ "id": "locked-down", "skills": [] }
]
}
}Example behavior:
| Agent | Skill behavior |
|---|---|
writer | Inherits the default skill list |
docs | Uses only docs-search |
locked-down | Uses no skills |
Use allowlists when different agents need different levels of access.
For example, a documentation agent may need a docs-search skill, while a restricted support agent may need no file or shell-related skills.
Load-Time Filters and Gating
OpenClaw can filter skills based on requirements such as environment, configuration, or binary availability. The official skills documentation mentions gating and skill eligibility behavior.
A skill may depend on:
- an environment variable
- an API key
- a local binary
- a configured service
- a specific operating system
- a required tool
If the requirement is missing, the skill may not be available.
This prevents the agent from trying to use a workflow that cannot run in the current environment.
Environment and API Key Handling
Skills may require access to credentials, API keys, or environment variables.
OpenClaw documentation references skills.entries.* environment and API key injection behavior.
Do not place secrets directly inside SKILL.md.
Bad example:
Use this API key: sk-example-secret-keyBetter example:
Use the configured environment variable for the required API key.Warning: Never store API keys, passwords, private tokens, or credentials inside SKILL.md. Use supported configuration, environment variables, or secret-management methods instead.
Skill Snapshots and Refresh Behavior
OpenClaw can snapshot eligible skills when a session starts. The documentation also mentions that OpenClaw watches skill folders and can update the skills snapshot when SKILL.md files change.
In practice:
- A skill added after a session starts may not affect the current session immediately.
- A changed SKILL.md may require a new session or refresh behavior.
- If a skill does not appear, start a new session and check the skill location.
When testing a new skill, use a clean session so the latest skill set is loaded.
Installing Skills With ClawHub
OpenClaw supports installing skills from ClawHub. The official skills documentation mentions this command pattern:
openclaw skills install <slug>This downloads a ClawHub skill folder into the workspace.
After installation:
- Check the installed folder.
- Open and read SKILL.md.
- Review any helper scripts or reference files.
- Confirm required tools and environment variables.
- Test the skill in a safe workspace before using it with important data.
Warning: Do not install public skills blindly. Review SKILL.md and any helper scripts before enabling a skill in your environment.
Creating a Basic OpenClaw Skill
Create a skill folder:
skills/hello-world/
SKILL.mdAdd a SKILL.md file:
---
name: hello_world
description: Use this skill when the user asks for a simple hello-world example.
---
# Hello World Skill
When the user asks for a greeting, respond with:
"Hello from your custom skill."Start a new session after creating the skill.
If your environment supports the OpenClaw skills command, you can check available skills with:
openclaw skills listNote: If the command behavior differs in your installed version, check the current OpenClaw CLI documentation before using it in production.
Recommended SKILL.md Structure
Use this structure for production-ready skills:
---
name: skill_name
description: Use this skill when...
---
# Skill Name
## When to Use
Use this skill when...
## Workflow
1. First step.
2. Second step.
3. Third step.
## Tool Guidance
Use:
- Tool A for...
- Tool B for...
Avoid:
- Tool C unless...
## Output Format
Return:
- Summary
- Steps
- Warnings
- Final result
## Safety Rules
Do not...
Ask for confirmation before...This structure keeps the skill easy to review and predictable for the agent.
Example: Documentation Summary Skill
---
name: docs_summary
description: Use this skill when the user asks to summarize technical documentation into setup steps, warnings, and implementation notes.
---
# Documentation Summary Skill
## When to Use
Use this skill when the user provides documentation, a docs URL, a README, or a technical guide and asks for a summary or implementation plan.
## Workflow
1. Identify the product, feature, or API being documented.
2. Extract the main purpose.
3. List required setup steps in order.
4. Identify configuration values, environment variables, ports, paths, or permissions.
5. Include warnings, limits, or version-specific details.
6. Avoid unsupported claims.
7. State uncertainty when the source is unclear.
## Output Format
Return:
- What it does
- When to use it
- Setup steps
- Required configuration
- Common mistakes
- Final notes
## Safety Rules
Do not invent commands.
Do not claim support for a feature unless the source confirms it.
Do not expose secrets, tokens, or private configuration values.Example: Code Review Skill
---
name: code_review
description: Use this skill when the user asks for a code review focused on bugs, security, maintainability, or production readiness.
---
# Code Review Skill
## When to Use
Use this skill when the user provides code and asks for review, debugging, cleanup, security feedback, or production-readiness checks.
## Review Checklist
Check for:
1. Incorrect logic
2. Missing error handling
3. Security risks
4. Hardcoded secrets
5. Unsafe file operations
6. Repeated code
7. Performance issues
8. Missing validation
9. Missing tests
10. Unclear naming
## Output Format
Return:
- Summary
- Critical issues
- Suggested fixes
- Optional improvements
- Final recommendation
## Safety Rules
Do not rewrite large sections unless requested.
Do not remove business logic without explaining why.
Flag risky changes clearly.Example: Safe File Operation Skill
---
name: safe_file_operations
description: Use this skill when the user asks to organize, rename, move, or edit files in a workspace.
---
# Safe File Operations Skill
## When to Use
Use this skill when the user asks for file cleanup, file organization, renaming, movement, or batch edits.
## Workflow
1. Inspect the target files.
2. Explain the planned changes.
3. Create a dry-run list before changing anything.
4. Ask for confirmation before destructive actions.
5. Avoid hidden, system, credential, dependency, and production config files unless explicitly approved.
6. Report what changed.
## Safety Rules
Never delete files without confirmation.
Never overwrite files without confirmation.
Never modify credential files, environment files, or production configuration without explicit approval.
Prefer copy or backup before destructive changes.Security Review Checklist
Skills can affect how an agent behaves. Review every skill before installing, enabling, or sharing it.
This is especially important for skills that use shell commands, browser sessions, files, APIs, credentials, scheduled jobs, or external services.
| Check | Why it matters |
|---|---|
| Read SKILL.md fully | Instructions can change agent behavior |
| Check helper scripts | Scripts may perform actions not obvious from the skill description |
| Review required tools | Powerful tools increase risk |
| Check environment requirements | Missing keys or binaries can break the workflow |
| Look for external network calls | Data may be sent outside the workspace |
| Look for destructive actions | File deletion, overwrite, or production changes need approval |
| Check for hidden instructions | Malicious or unsafe instructions may be embedded in natural language |
| Use allowlists | Limit which agents can use sensitive skills |
| Test in a safe workspace | Avoid damaging production data |
Security note: Recent research on agent skill ecosystems has highlighted risks around malicious or vulnerable skills, hidden behavior in SKILL.md, prompt injection, and semantic supply-chain issues. These risks do not mean skills should be avoided, but they do mean skills should be reviewed carefully before use.
Common Mistakes
Missing SKILL.md
Wrong:
skills/my-skill/instructions.mdCorrect:
skills/my-skill/SKILL.mdInvalid YAML Frontmatter
Wrong:
---
name my_skill
description My skill
---Correct:
---
name: my_skill
description: Use this skill when...
---Too Broad Description
Wrong:
description: Use this skill for everything.Correct:
description: Use this skill when the user asks to convert technical documentation into setup steps, warnings, and implementation notes.Duplicate Skill Names
If two skills have the same name, precedence decides which one wins.
Check higher-priority locations first if the wrong skill version is being used.
Hardcoded Secrets
Do not store API keys, passwords, access tokens, or private credentials inside SKILL.md.
No Safety Rules
Any skill that can affect files, accounts, APIs, messages, production systems, customer data, or billing should include approval rules.
Old Session Still Running
If a new or updated skill does not appear, start a new session or check refresh behavior.
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| Skill does not appear | Wrong folder or missing SKILL.md | Check path and filename |
| Skill appears but is not used | Weak description | Rewrite the description with clear trigger conditions |
| Wrong skill version is used | Precedence conflict | Check higher-priority locations |
| Skill is blocked | Agent allowlist | Update allowed skills for that agent |
| Skill fails during task | Missing tool, binary, config, or API key | Check requirements and gating |
| Skill changes do not apply | Session snapshot or refresh behavior | Start a new session |
| Skill behaves unsafely | Bad instructions | Add safety rules and review scripts |
Recommended Rules for Production Skills
Use these rules when writing or reviewing production-ready skills:
- Give each skill one clear purpose.
- Use a specific description.
- Keep the workflow short and testable.
- Put long references in separate files.
- Avoid hardcoded secrets.
- Add safety rules for risky actions.
- Use allowlists for sensitive workflows.
- Test in a safe workspace first.
- Document the expected output format.
- Review public or third-party skills before installing.
Summary
OpenClaw skills are reusable instruction folders that help an agent follow specific workflows. Each skill usually contains a SKILL.md file with YAML frontmatter and markdown instructions.
The key points are:
- SKILL.md defines the skill's purpose and workflow.
- Skills are different from tools and plugins.
- OpenClaw can load skills from workspace, project, personal, shared, bundled, and extra configured locations.
- Skill precedence decides which version wins when duplicate skill names exist.
- Per-agent allowlists control which agents can use which skills.
- Load-time filters can prevent unavailable skills from loading.
- Skill changes may require a new session or refresh behavior.
- Third-party skills should be reviewed before use.
A good skill should be focused, readable, safe, and easy to test. It should clearly explain when to use the workflow, what steps to follow, what output to produce, and which actions require confirmation.