You’ve got an agent that’s powerful out of the box, but what happens when you need it to do something specific to your workflow? That’s where skills come in, and honestly, they’re one of the slickest parts of the OpenClaw ecosystem. We’re going to break down exactly how this system works—from the anatomy of a SKILL.md file to how precedence loading keeps your customizations clean and organized.

The Problem We’re Solving

Here’s the scenario: you’re running OpenClaw agents, and they work great with the default toolkit. But then you realize you need something custom. Maybe it’s a proprietary API call. Maybe it’s a workflow that’s unique to your team. Maybe it’s a tool that just doesn’t exist in the bundled skills yet.

Without a skills system, you’d be hacking directly into the agent configuration or rewriting core functionality. With skills? You create a directory, write one file, and boom—your agent knows how to do something new. No code rewrites. No monkeying with the core system. This is the power of proper abstraction: you extend the system without touching it.

That’s the power of skills, and understanding how they work is key to unlocking the full potential of OpenClaw. Most agents ship with a baseline of capabilities, but the real magic happens when you customize them for your exact use case. Skills are how you do that without maintaining a fork of the codebase.

What Is a Skill, Really?

A skill in OpenClaw is a self-contained unit of functionality. It’s not just a function or a single tool. A skill is a teaching system that tells your agent:

What tools are available
How to use those tools
When to use them
What the expected outcomes are

This teaching happens through a file structure. Every skill lives in a directory, and at the heart of that directory is a file called SKILL.md. Think of a skill directory as a complete package. It might contain SKILL.md, supporting files, examples, even tests. But the SKILL.md is the core—it’s the interface between the skill and the agent runtime.

The SKILL.md file is where the magic happens. It’s not a random markdown file with instructions scattered throughout. It follows a specific format: YAML frontmatter (structured metadata) followed by detailed instructions. This combination tells the OpenClaw system everything it needs to know about that skill. The structured format is intentional—it allows the system to parse and understand skills programmatically, not just display them to humans.

Think of it like a recipe card. The frontmatter is the metadata—name, difficulty, ingredients. The body is the instructions that actually teach your agent how to execute the skill properly. Just like a recipe needs both structured data (ingredient quantities) and narrative (technique), a skill needs both metadata and human-readable instructions.

The SKILL.md Anatomy: Frontmatter + Instructions

Let’s break down what a SKILL.md file actually contains, piece by piece. Understanding this structure is crucial because even small mistakes in formatting can cause the system to fail to load your skill correctly.

The YAML Frontmatter

Every SKILL.md starts with YAML frontmatter, enclosed in triple dashes. This is where you define the skill’s identity and properties:

---
name: "Database Query Runner"
version: "1.0.0"
description: "Execute SQL queries against your database safely"
author: "Your Team"
license: "MIT"
tags:
  - database
  - sql
  - queries
difficulty: "intermediate"
prerequisites:
  - "SQL knowledge"
  - "Database connection credentials"
tools:
  - "db_execute"
  - "db_test_connection"
dependencies: []
---

What’s happening here? We’re declaring:

name: The human-readable name of the skill
version: Semantic versioning so you can track updates
description: What this skill does in one sentence
author: Who created it (you, your team, the community)
license: Legal stuff—MIT, Apache, GPL, whatever
tags: Keywords for discovery and organization
difficulty: “beginner”, “intermediate”, or “advanced”
prerequisites: What knowledge or access someone needs
tools: The specific tools this skill provides
dependencies: Other skills it requires to function

This frontmatter tells OpenClaw’s loading system everything it needs to know before even reading the instructions. It’s how the system decides whether a skill is available in your environment, whether it conflicts with other skills, and how to present it to users. The system can parse this YAML once and know whether to load the skill without reading the entire markdown documentation.

Deep Dive: Frontmatter Field Meanings

Let’s spend some real time here because this is where subtle mistakes trip people up. The difference between a skill that works smoothly and one that causes friction often comes down to these details.

Name and Version: The combination of name and version creates a unique identifier for your skill. OpenClaw tracks these separately, which means you can have version 1.0.0 and 1.1.0 of the same skill coexisting in your system (though usually you’ll only use the latest). The name should be human-readable but also match your directory name—consistency matters. If your directory is named database-query-runner but your name field says “db-runner”, you’ll confuse tools that try to match them up. Following a consistent naming convention—using hyphens in directory names and matching in the frontmatter—saves headaches later.

Description: This is what shows up in UI listings and search results. Keep it punchy. “Execute SQL queries against your database safely” is good. “A tool for executing queries” is vague. The description is your elevator pitch. Think about someone browsing a list of fifty skills trying to find the one they need. Your description should be clear enough that they know immediately whether this is the skill they’re looking for.

Tags: These are searchable keywords. If someone searches for “database”, your skill shows up because you tagged it with “database”. Use three to five tags per skill. Too many and they become noise. Too few and discoverability suffers. Tags should be specific enough to be useful but common enough that someone would actually search for them. “database” is good. “my-team-database” is too specific. “data” is too vague.

Difficulty: This is more about communication than technical gating. Setting difficulty to “advanced” signals to users that they should understand threading or async patterns before using it. “Beginner” means straightforward. This helps the right people find the right skills. However, this is informational only—it doesn’t prevent anyone from using an advanced skill. It’s like a difficulty rating on a hiking trail. The trail doesn’t prevent novices from hiking it, but the rating sets expectations.

Prerequisites: Here’s where you list hard requirements. “SQL knowledge” means the agent needs to understand SQL syntax (conceptual). “Database connection credentials” means actual credentials must be available. Prerequisites are warnings, not gates—the skill will still load, but users know what they need. This is useful documentation for anyone who finds the skill and wants to use it. If credentials are missing, the skill might load but fail at runtime, which is fine as long as users are warned upfront.

Tools: This is critical. List every single tool your skill exposes. If you forget one, it won’t be available to agents. This is also where conflicts happen: if two skills define the same tool name, the loading system needs to know which one wins. That’s why the precedence system exists. A tool name is how agents discover and invoke the capability, so listing them accurately is essential.

Dependencies: If your skill requires another skill to be present, list it here. For example, a “Database Query Optimizer” skill might depend on “Database Query Runner”—it assumes the base queries work first. If a dependency is missing, OpenClaw can warn you during load time before you try to use the skill. This prevents confusing runtime failures.

The Instructions Section

After the frontmatter comes the actual content—detailed instructions on how to use the tools in this skill. This is where you teach your agent through examples, explanations, and patterns. The instructions are not just documentation—they’re part of how your agent learns to use the tools. Many AI systems use the instructions as context when deciding how to invoke tools.

A well-written instructions section typically follows this structure:

Overview: What does this skill do and why would you use it? Set context and expectations.

Tool Definitions: What are the specific tools available? What parameters do they accept? What do they return?

Usage Examples: Real-world scenarios showing how to apply the tools. Concrete examples are more useful than abstract descriptions.

Common Patterns: Typical workflows and best practices. What’s the “happy path” for using this skill?

Troubleshooting: What can go wrong and how to fix it. Help users self-diagnose problems.

Safety Notes: Warnings about destructive operations or security considerations. Destructive operations need extra attention.

Here’s a real example of what the instructions might look like:

## Database Query Runner Skill

This skill allows your agent to execute SQL queries safely against your
connected database. It includes tools for testing connections, running
queries, and handling results.

### Available Tools

#### db_execute

Executes a SQL query and returns results.

**Parameters:**

- query (string): The SQL statement to execute
- timeout (integer, optional): Query timeout in seconds (default: 30)
- explain (boolean, optional): If true, returns EXPLAIN plan instead of results

**Returns:**

- rows: Array of result rows
- columns: Array of column names
- execution_time: Time taken in milliseconds
- row_count: Number of rows affected/returned

#### db_test_connection

Tests the database connection.

**Parameters:**

- connection_name (string): Name of the connection to test

**Returns:**

- connected (boolean)
- server_version (string)
- response_time (integer): Milliseconds

### Usage Example: Basic Query

When you need to retrieve data, construct your query and call db_execute:

\`\`\`
I need to find all users who signed up in the last 30 days.
The agent should:

1. Call db_execute with query: "SELECT \* FROM users WHERE signup_date >= NOW() - INTERVAL '30 days'"
2. Process the returned rows
3. Summarize findings
   \`\`\`

### Common Patterns

**Pattern 1: Validate Before Execute**
Always test connection first with db_test_connection before running complex queries.

**Pattern 2: Use EXPLAIN for Optimization**
For slow queries, call db_execute with explain=true to see the execution plan.

**Pattern 3: Batch Operations**
For multiple operations, chain them together rather than making separate calls.

### Safety Notes

⚠️ **Destructive Operations**: DELETE and UPDATE statements should only be executed
with explicit confirmation. Log all modifications.

⚠️ **Performance**: Complex joins on large tables may timeout. Use LIMIT for testing.

See what we did there? The instructions aren’t just dry documentation. They’re teaching material. They show your agent not just what tools exist, but how to think about using them. The agent learns patterns, safety considerations, and best practices. When the agent encounters a similar situation later, it has this instruction set as context for decision-making.

The Loading Precedence: Where Skills Come From

Here’s where things get really interesting. OpenClaw doesn’t just load all skills equally. It uses a precise precedence system to determine which version of a skill wins when there are conflicts or duplicates. This is what makes the skill system so powerful—you can customize without maintaining a fork.

The precedence order, from highest to lowest priority, is:

Workspace Skills (./skills/ in your project directory)
User Skills (~/.openclaw/skills/ in your home directory)
Bundled Skills (Shipped with OpenClaw)

This matters. Let’s say OpenClaw ships with a “Git Manager” skill. You find it doesn’t quite fit your team’s workflow. You can create your own Git Manager skill in your workspace directory, and your version will be loaded instead of the bundled one. No conflicts. No weird workarounds. Just clean override. This is a fundamental design principle: local customizations always win.

Here’s how that plays out in practice:

OpenClaw looks for "git-manager" skill:

1. Checks ./skills/git-manager/SKILL.md (FOUND) ✓ USES THIS
2. Never checks ~/.openclaw/skills/git-manager/SKILL.md
3. Never checks bundled version

---

OpenClaw looks for "database-query" skill:

1. Checks ./skills/database-query/SKILL.md (NOT FOUND)
2. Checks ~/.openclaw/skills/database-query/SKILL.md (FOUND) ✓ USES THIS
3. Never checks bundled version

---

OpenClaw looks for "slack-messenger" skill:

1. Checks ./skills/slack-messenger/SKILL.md (NOT FOUND)
2. Checks ~/.openclaw/skills/slack-messenger/SKILL.md (NOT FOUND)
3. Checks bundled skills (FOUND) ✓ USES THIS

This precedence system is why you can customize without fear. Your workspace skills take absolute priority. Your personal skills come second. The bundled defaults are your safety net. You can experiment in your workspace without affecting other projects or your personal setup, and both of those can coexist with the standard bundled skills.

Understanding Conflict Resolution

When two skills try to define the same tool, what happens? OpenClaw resolves it using the precedence order. The skill that loads first wins. So if you have a custom “send_message” tool in your workspace skill and the bundled Slack skill also has “send_message”, your version wins every time.

But here’s the thing: this can be confusing. That’s why you should always check what tools you’re overriding. Look at the bundled skill, understand what it does, and make sure your override is actually better. We’ve all seen someone override a core tool and then spend hours debugging because they forgot what the original did. The solution is documentation. When you override a tool, document why you’re doing it. What’s different about your version? What problem does it solve?

The skills.load.extraDirs Configuration

But wait, there’s more. What if you want to load skills from somewhere else entirely? Maybe you’ve got a shared team repository of skills. Maybe you’re testing skills before moving them to the standard locations. Maybe you’re building a platform where users can drop custom skills into a plugins directory.

That’s where skills.load.extraDirs comes in. This is a configuration option in your openclaw.json file that lets you specify additional directories to search for skills. It’s a powerful escape hatch when the three standard locations aren’t enough.

Here’s what it looks like in your config:

{
  "skills": {
    "load": {
      "extraDirs": [
        "/team/shared-skills",
        "/projects/special-workflow-skills",
        "~/my-experimental-skills"
      ]
    }
  }
}

With this configuration, OpenClaw will search these directories in order after checking the standard locations. So your full precedence chain becomes:

Workspace skills (./skills/)
User skills (~/.openclaw/skills/)
Extra directories (in the order listed in config)
Bundled skills

The order of extra directories matters. If the same skill name appears in multiple extra directories, the first one wins. So if you have /team/shared-skills and /projects/special-workflow-skills both containing a “database-query” skill, the one in /team/shared-skills loads because it comes first.

This is useful in several scenarios:

Scenario 1: Team Shared Skills
Your team has a Git repository with standard skills everyone should use. Add it to extraDirs, and every agent in the team loads those skills automatically. Someone updates the repo, everyone gets the new version. No manual syncing. This is great for large teams where consistency matters. Imagine your team has twenty developers, each running OpenClaw on their machine. Without shared skills, they maintain twenty separate copies of custom skills, leading to version drift and incompatibility. With extraDirs pointing to a shared repository, everyone runs the same versions, stays in sync automatically, and benefits from improvements immediately. This is especially powerful for enforcing organizational standards—you maintain the canonical versions of critical skills in the shared repository, and all agents use those by default.

Scenario 2: Experimental Skills
You’re building a new skill and want to test it before making it official. Put it in an experiment directory, configure extraDirs to point there, and test it out. When it’s ready, move it to the real location and remove it from extraDirs. This lets you keep experimental work separate from production. The beauty of this approach is you can iterate rapidly on experimental skills without affecting your production skills. You can test new ideas, gather feedback, refine the interface, and only move to production when you’re confident. This is a best practice for managing change—separate development from production, test thoroughly, then promote.

Scenario 3: Plugin System
You’re building an application that uses OpenClaw, and you want users to be able to add custom skills. Have them drop skills in a plugins directory, and configure extraDirs to load from there. Now users can extend functionality without touching core code. This is how many extensible systems work—users get a standard directory where they can drop their own code. You might distribute your application with a plugins/ directory and documentation showing users how to structure skills. Users who need custom integrations create skills, drop them in that directory, and they load automatically. Your core application code never changes, but it gains new capabilities through user-provided skills.

The power here is flexibility. You’re not locked into a single location. You can organize skills however makes sense for your use case. And because of the precedence system, you don’t have to worry about conflicts—the loading order is deterministic and predictable.

Enabling, Disabling, and Overriding Skills

Understanding how to control which skills are available is crucial. You might have reasons to disable certain skills. Maybe you’re in a regulated environment and only want approved skills. Maybe you’re sharing an OpenClaw instance between teams and need to isolate capabilities. Maybe a skill has a bug and you need to disable it temporarily.

You might have reasons to disable certain skills:

Security: You don’t want agents in production using experimental skills
Performance: Some skills might be expensive to load
Conflicts: Multiple skills might provide the same functionality, and you want to pick one
Regulatory: You operate in an environment where only approved tools can be used

Disabling a Bundled Skill

Let’s say OpenClaw ships with a “Web Scraper” skill, but you don’t want your agents using it. Maybe it violates your terms of service. Maybe it causes performance problems. Maybe you have a better version. You have two options:

Option 1: Create an empty override

Create ./skills/web-scraper/SKILL.md with minimal frontmatter and no tools:

---
name: "Web Scraper"
disabled: true
reason: "Not approved for use in this workspace"
---
This skill is disabled.

When OpenClaw loads this, it sees the skill exists but is disabled, and it won’t make the tools available. This approach has the advantage of being explicit and local to your workspace. It’s also reversible—you can delete the file and get back the bundled version.

Option 2: Configure in openclaw.json

Add a skills.disabled section:

{
  "skills": {
    "disabled": ["web-scraper", "external-api-caller"]
  }
}

The configuration approach is cleaner for multiple disables. The override approach is useful when you want to document why a skill is disabled directly in the skill file. Both work, and you can use them together. Configuration-based disabling is good for operations (disable five skills in a deployment), while override files are good for documentation (this explains why we don’t use web scraping).

Overriding a Bundled Skill

We touched on this earlier, but it’s worth emphasizing. If you want to modify how a bundled skill works, create your own version in your workspace:

./skills/
  ├── custom-database/
  │   └── SKILL.md
  └── git-manager/           ← Overrides bundled version
      └── SKILL.md

Your git-manager/SKILL.md will be loaded instead of the bundled one. This is how you customize OpenClaw to fit your exact workflow without touching the core system. You can tweak tool parameters, add new tools, change documentation, all without modifying OpenClaw itself. When OpenClaw updates, the bundled skill gets better, but you keep your customizations.

Skill Categories: Organizing Your Growing Library

As you accumulate skills, organization becomes important. Skills serve different purposes, and categorizing them helps you and your team think about them coherently. There are several common categories:

Integration Skills: Connect to external services (Slack, GitHub, Jira, Salesforce, etc.). These are typically conversions between your domain and external APIs. When you use an integration skill, the agent learns how to talk to a third-party service.

Data Skills: Query, transform, and analyze data (SQL, spreadsheets, data pipelines). These skills manipulate information internal to your system. These are typically read-heavy, though they can include writes when necessary.

Automation Skills: Repetitive workflows (deployment, scheduling, backup). These are about doing complex multi-step things consistently. They often orchestrate other skills.

Content Skills: Generate, edit, or process text and media (writing, image processing, code generation). These leverage LLM or ML capabilities to create or modify content.

System Skills: Low-level operations (file management, process control, networking). These are infrastructure-level tools that might not fit neatly into other categories.

When you’re building a skill, think about which category it fits. This helps with discoverability and prevents tool naming conflicts. A “send_message” tool in the Slack integration skill is different from a “send_message” tool in the Email skill. Use namespacing if you’re building multiple related tools. Prefix your tools with the skill name: slack_send_message, email_send_message. This prevents the precedence system from getting confused.

Performance Impact Analysis

Here’s something people don’t talk about much: how many skills you load affects performance. Each skill’s SKILL.md is parsed and validated when the system starts. Too many skills and startup gets slow. This matters especially in production where startup time directly affects your service availability.

OpenClaw’s loading system is designed to handle hundreds of skills, but there’s a practical limit around 1,000 before you’ll start seeing measurable slowdown. At that scale, the parsing overhead becomes noticeable. If you’re hitting that limit, consider:

Move unused skills to a separate directory not in the load path
Create skill bundles (a single skill that wraps multiple tools)
Use skills.disabled to explicitly prevent loading unnecessary skills

Also, keep your SKILL.md files lean. Huge documentation is great, but if you’re documenting thousands of lines per skill, consider moving detailed docs to a separate location and just linking to them in SKILL.md. A SKILL.md that’s too large slows down parsing and makes it harder to maintain. The frontmatter is usually small, but the instructions can grow large if you’re not disciplined about documentation.

When you’re deploying OpenClaw with many skills, consider lazy-loading patterns. Load skills on demand rather than at startup. This speeds up initialization at the cost of slight latency when you first use a skill.

The ClawHub Marketplace Connection

Here’s something worth knowing: the OpenClaw ecosystem includes ClawHub, a marketplace where you can share and discover skills. There are currently 5,400+ community skills available. This is a significant resource that many people don’t take advantage of.

This is significant because:

Discovery: Before you build something custom, check ClawHub. Someone might have already solved your problem. Why maintain code if someone else already maintains it?
Sharing: When you build a skill that’s useful, you can publish it to ClawHub and help others. You might discover that your internal tool is actually valuable to other people.
Ecosystem: The precedence loading system means community skills can be used alongside your custom ones without conflicts. You get the best of both worlds.

When you’re thinking about whether to build a skill internally or use a community one, consider maintenance. Community skills are maintained by volunteers. Internal skills are your responsibility. Sometimes it’s worth maintaining your own for critical functionality. Sometimes it’s smarter to use well-maintained community skills and contribute back if you find bugs. The test: would you rather spend time building this, or spend time vetting and monitoring a community version?

Putting It All Together: A Real-World Example

Let’s walk through a real scenario from start to finish. This will tie together everything we’ve discussed.

Your Situation: Your team uses a proprietary internal API for customer data. OpenClaw’s bundled skills don’t know how to talk to it. You need agents to be able to fetch customer data, search by name or email, and retrieve order history. This is genuinely useful, so you might eventually contribute it to ClawHub.

Step 1: Create the Skill Structure

./skills/
  └── customer-data-api/
      └── SKILL.md

Step 2: Write the SKILL.md

---
name: "Customer Data API"
version: "1.0.0"
description: "Fetch customer data from internal API"
author: "Your Team"
tags:
  - customer
  - internal-api
  - data
difficulty: "intermediate"
tools:
  - "get_customer_by_id"
  - "search_customers"
  - "get_customer_orders"
---

## Customer Data API Skill

This skill provides access to your internal customer database API.

### Available Tools

#### get_customer_by_id
Fetches a single customer record by ID.

**Parameters:**
- customer_id (string): The customer's unique ID
- include_orders (boolean, optional): Include order history

**Returns:**
- customer object with name, email, account_status, created_date

#### search_customers
Search for customers by name, email, or account status.

**Parameters:**
- query (string): Search term
- status (string, optional): "active", "inactive", or "suspended"
- limit (integer, optional): Max results (default: 10)

**Returns:**
- Array of matching customer objects

#### get_customer_orders
Fetch all orders for a customer.

**Parameters:**
- customer_id (string): Customer ID
- status (string, optional): "pending", "shipped", "delivered"

**Returns:**
- Array of order objects with order_id, total, date, status

### Usage Example: Customer Lookup

When an agent needs customer information:

1. Use search_customers with the customer name if you don't have an ID
2. Use get_customer_by_id with include_orders=true to get full details
3. Process the returned data and summarize for the user

### Error Handling

If a customer isn't found, the tools return an empty result set.
If the API is unreachable, tools return an error status.

Step 3: Deploy and Test

Copy the skill directory into your workspace. OpenClaw automatically discovers it and makes it available. Test with a simple query to make sure the tools are accessible.

Step 4: Use It

Your agents can now:

Search for customers
Fetch detailed records
Access order history
All without you modifying core OpenClaw code

And if you later decide to share this skill, you can publish it to ClawHub, and other teams can use it too. Or if it’s proprietary, you can share it internally through your team’s extraDirs configuration. ClawHub has mechanisms for private skills if needed.

Key Takeaways

Here’s what you should walk away understanding:

SKILL.md is the teaching file: Frontmatter + instructions is all you need to teach OpenClaw something new. The file structure is deliberately simple so you can focus on content, not formatting.
Precedence protects your customizations: Workspace > User > Bundled means your changes always win without conflicts. This hierarchy lets you override anything without fear, knowing your customizations will take priority.
extraDirs gives you flexibility: Load skills from anywhere you want, in any order that makes sense. Whether it’s team repositories, experimental directories, or user plugins, the loading system adapts to your structure.
Disabling is straightforward: Override, disable, or configure out of the box. Multiple approaches let you handle different scenarios—sometimes an override makes sense, sometimes configuration is cleaner.
The ecosystem is vast: 5,400+ community skills exist. Before building, check what’s available. Standing on the shoulders of others is smart engineering.
Categories and namespacing matter: Organize your skills intentionally to avoid confusion and conflicts. Good naming and organization prevent problems before they start.
Performance scales: Up to thousands of skills is fine, but be thoughtful about what you load. Start simple and add complexity only when needed.
Testing and versioning are important: Use semantic versioning on your skills and test thoroughly before deploying. Treat skills like you would treat any production code.

The OpenClaw skills system is elegant precisely because it’s simple. You create directories, write SKILL.md files, and your agent learns new tricks. No complex configuration. No core rewrites. Just organized, layered extensibility that adapts to your needs.

The real power of this system isn’t any single feature—it’s that everything works together coherently. Your workspace skills override bundled ones. You can share skills across your team. You can extend without modifying core code. You can test experimental features safely. All of this happens naturally because of thoughtful system design.

That’s the power of skills—and now you know how they work.

OpenClaw Skills System Explained: How SKILL.md Files Teach Your Agent New Tricks