What Are OpenClaw Skills and How Do They Work?

OpenClaw's true power lies in its modular skill system—a framework that transforms your AI from a general-purpose assistant into a specialized expert. Skills are self-contained packages that extend your agent's capabilities by providing specialized knowledge, workflows, and tool integrations.

What Skills Provide

Skills deliver four key types of value:

1. Specialized Workflows - Step-by-step procedures for specific domains
2. Tool Integrations - Instructions for working with specific APIs and file formats
3. Domain Expertise - Company-specific knowledge and business logic
4. Bundled Resources - Scripts, references, and assets for complex tasks

Think of skills as onboarding guides that equip your agent with procedural knowledge no model can fully possess. When you need your agent to handle a specific task reliably, a well-crafted skill makes it possible.

Skill Anatomy

Every skill consists of a required SKILL.md file and optional bundled resources. The structure is simple but powerful:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata
│   └── Markdown instructions
├── scripts/ (optional)
├── references/ (optional)
└── assets/ (optional)

The SKILL.md file contains YAML frontmatter with the skill's name and description—this is how OpenClaw knows when to use the skill. The body contains implementation details that load only when the skill triggers.

Skill Loading and Precedence

Skills are loaded from three locations with a clear precedence order:

1. Workspace skills (<workspace>/skills) - Highest precedence
2. Managed skills (~/.openclaw/skills) - Shared across agents on the same machine
3. Bundled skills (shipped with OpenClaw) - Lowest precedence

When skill names conflict, workspace skills always win. This allows you to override bundled skills with custom implementations.

Progressive Disclosure Design

The skill system uses a three-tiered loading approach to manage context efficiently:

• Metadata (name + description) - Always in context
• SKILL.md body - Loaded when the skill triggers
• Bundled resources - Loaded only as needed

This design keeps your agent's context window lean while making specialized knowledge available exactly when needed. Large reference documents, scripts, and assets never clutter the context unless specifically required.

Skill Resources

Scripts Directory

The scripts/ directory contains executable code (Python, Bash, etc.) for tasks that require deterministic reliability. When the same code is repeatedly rewritten, move it to a script—this saves tokens and ensures consistency.

For example, a rotate_pdf.py script in a PDF editing skill eliminates the need to rewrite rotation logic each time.

References Directory

The references/ directory holds documentation intended to be loaded as needed. Store database schemas, API documentation, company policies, and detailed workflow guides here.

Keep your SKILL.md lean by moving detailed reference material to separate files. Only load these references when your agent determines they're needed.

Assets Directory

The assets/ folder contains files used in output but not loaded into context—templates, images, icons, and boilerplate code. When your agent needs to generate a document with specific branding, it can pull the logo from assets without consuming precious context space.

Creating Your First Skill

Skill creation follows a clear process:

1. Understand the need - Identify concrete examples of how the skill will be used
2. Plan reusable components - Determine what scripts, references, and assets to include
3. Initialize the skill - Use init_skill.py to generate the template
4. Implement resources - Add scripts, references, and assets
5. Write SKILL.md - Craft clear instructions and frontmatter
6. Package and distribute - Use package_skill.py to create a distributable .skill file

The init_skill.py and package_skill.py scripts automate much of this workflow, ensuring your skills meet all requirements.

Best Practices

• Be concise - Every token counts. Challenge each piece of information: "Does OpenClaw really need this?"
• Set appropriate freedom - Match instruction specificity to task fragility
• Use progressive disclosure - Keep SKILL.md under 500 lines
• Organize by domain - For multi-domain skills, split references by use case

By following these patterns, you create skills that extend your agent's capabilities without overwhelming its context window. The result? An AI that performs specialized tasks with human-like expertise.