OpenClaw Skills Explained: How to Install, Configure, and Build Your Own

OpenClaw skills transform a general-purpose AI agent into a specialized tool tailored to your exact workflow. Whether you need your agent to manage emails, deploy code, query databases, or control smart home devices, skills make it possible. This guide covers everything from first installation to publishing your own custom skill on the marketplace.

Understanding OpenClaw Skills

A skill is a reusable instruction module packaged as a Markdown file with structured metadata. When installed, it teaches your agent how to perform a specific task or interact with a specific service. The OpenClaw Bazaar skills directory catalogs thousands of these modules across dozens of categories.

Each skill contains a SKILL.md file with YAML frontmatter that defines its identity, requirements, and behavior. The frontmatter includes fields like:

• name (required): A unique identifier for the skill
• description (required): What the skill does
• homepage (optional): Link to documentation or the project page
• user-invocable (default: true): Whether users can trigger the skill via slash commands
• disable-model-invocation (default: false): Whether to exclude the skill from model prompts

Below the frontmatter, the Markdown body contains the actual instructions, examples, and context that guide the agent.

How Skills Load and Override Each Other

OpenClaw follows a three-tier loading hierarchy:

1. Bundled skills that ship with the OpenClaw installation
2. Managed skills stored in ~/.openclaw/skills
3. Workspace skills located in <your-project>/skills

Workspace skills override managed skills, which override bundled skills. This means you can customize any default behavior by creating a workspace-level version of an existing skill. It also means different projects can have completely different skill configurations without interference.

Installing Skills From the Marketplace

The most common installation path uses ClawHub, the official registry:

openclaw skills search "email"
openclaw skills install email-management
openclaw skills install email-management --version 2.1.0

You can also install from Skills.sh, a curated registry that runs security reviews on every listed skill:

npx skills add owner/repo-name

Or clone directly from GitHub if you prefer to review the source first.

Managing Installed Skills

openclaw skills list              # See all installed skills
openclaw skills list --eligible   # See skills available for current context
openclaw skills info calendar-sync # Get details on a specific skill
openclaw skills check             # Verify all skills are valid
openclaw skills update --all      # Update everything to latest versions

Browse and compare skills visually in the OpenClaw Bazaar directory before installing through the CLI.

Configuring Skills in openclaw.json

Skills accept customization through your project's openclaw.json configuration file. This is where you set API keys, environment variables, and skill-specific settings:

{
  "skills": {
    "entries": {
      "email-management": {
        "enabled": true,
        "apiKey": "your-api-key-here",
        "env": {
          "SMTP_HOST": "smtp.gmail.com",
          "SMTP_PORT": "587"
        }
      }
    }
  }
}

Key configuration fields include:

• enabled: Toggle a skill on or off without uninstalling it
• apiKey: Store credentials the skill needs to connect to external services
• env: Set environment variables that the skill reads at runtime
• config: Pass custom settings specific to the skill
• load.watch: Enable hot reloading so skill changes take effect immediately
• load.extraDirs: Point to additional directories containing skills

Hot reloading is particularly useful during development. When load.watch is enabled (which it is by default), editing a skill file triggers automatic reloading without restarting your agent.

Building a Custom Skill From Scratch

If the marketplace does not have what you need, building your own skill is straightforward.

Step 1: Create the Directory Structure

my-custom-skill/
  SKILL.md
  scripts/
  references/

Step 2: Write the SKILL.md File

Start with frontmatter that defines metadata — the skill name, description, any binary requirements, operating system compatibility, and activation triggers. Then write the Markdown body with clear, specific instructions for the agent.

Good skill instructions share these qualities: they are specific rather than vague, they include examples of correct behavior, they define boundaries for what the agent should and should not do, and they handle edge cases explicitly.

Step 3: Test Locally

Copy your skill directory into your workspace skills/ folder and verify it loads correctly:

openclaw skills check

Test the skill against real scenarios and iterate on the instructions until the agent behaves as expected.

Step 4: Publish to the Marketplace

Once your skill is stable and tested, publish it to ClawHub:

clawhub sync --all

You can also submit it for listing on the OpenClaw Bazaar directory to reach a wider audience, or contact us about featured placement.

Token Economics: What Skills Cost

Every active skill adds tokens to your system prompt, which affects both context window usage and API costs. Here is what to expect:

• Base overhead per skill: approximately 195 characters minimum
• Variable cost: roughly 97 characters plus the length of all metadata fields
• Typical impact: about 24 tokens per skill using standard tokenization
• 10 active skills: approximately 240 additional tokens per turn

This means running 10 skills costs you around 240 extra tokens on every single API call. For high-volume usage, that adds up. Our recommendation is to keep 5 to 15 skills active at any time and disable the rest through configuration rather than uninstalling them.

With 50 or more simultaneous skills, you may notice meaningful context window pressure and increased costs. Be deliberate about which skills you keep enabled.

Security: The Most Important Section

Security deserves serious attention. The OpenClaw ecosystem is open, which means anyone can publish a skill. Estimates suggest that roughly 80 percent of published skills are low quality, and a meaningful fraction are potentially malicious. A known vulnerability (CVE-2026-25253) demonstrated that skills can serve as an attack vector.

Essential Security Practices

1. Read the source code of every skill before installing it. Skills are Markdown files — they are human-readable by design.
2. Verify the publisher. Check their GitHub profile, contribution history, and reputation in the community.
3. Understand the permission scope. Does the skill need filesystem access? Network access? API credentials? Make sure each permission is justified.
4. Prefer vetted registries. Skills.sh conducts security reviews. ClawHub is larger but unreviewed. The OpenClaw Bazaar highlights verified publishers.
5. Sandbox untrusted skills in Docker containers with restricted permissions — limit filesystem access to read-only and restrict network reach.
6. Never hardcode secrets. Use environment variable injection through the env configuration field.
7. Test in isolation before deploying to production workflows.

Red Flags

Avoid any skill that lacks a public source repository, requests permissions far beyond its stated purpose, has no install history or reviews, contains obfuscated code, or appeared recently with no community track record.

Multi-Agent Skill Configurations

If you run multiple OpenClaw agents (for example, one for development and one for business tasks), skills can be configured independently per agent:

• Workspace skills are isolated to the specific project directory
• Managed skills are shared across all agents on the machine
• Name conflicts resolve in order: workspace takes priority over managed, which takes priority over bundled

This architecture lets you build specialized agents — a development agent loaded with coding skills and a business agent loaded with communication and CRM skills — all running on the same machine without interference.

Skills vs. Tools: Understanding the Difference

New users often confuse skills with tools. Here is the distinction: tools are built-in capabilities that come with OpenClaw (file editing, terminal access, web search). Skills teach the agent how to combine those tools into specific workflows. A skill does not add new low-level functionality — it provides context, instructions, and patterns that guide how the agent uses its existing tools.

Getting Started

The fastest path to productive skill usage:

1. Browse the OpenClaw Bazaar skills directory and identify 3 to 5 skills that match your primary workflow
2. Install them via CLI
3. Configure API keys and environment variables in openclaw.json
4. Test each skill individually before combining them
5. Iterate on configurations as you learn what works

The skill ecosystem grows weekly. Check back in the marketplace regularly for new additions, and consider building and publishing your own to contribute to the community.

Browse the Skills Directory

Find the right skill for your workflow. The OpenClaw Bazaar skills directory has over 2,300 community-rated skills — searchable, sortable, and free to install.

Browse Skills →

Built a Skill? List It on the Bazaar

If you have built a skill that others would find useful, publish it on the Bazaar. Reach thousands of developers and get feedback from the community.

Learn how to publish →