OpenClaw

OpenClaw Skills & ClawHub RegistryšŸ‘Øā€šŸ’»

Skills are the primary mechanism for giving OpenClaw agents reusable, shareable capabilities beyond their base tool set. A skill is a self-contained package consisting of a SKILL.md file (instructions the agent follows), optional tool definitions, and metadata. When installed, a skill's instructions are injected into the agent's system prompt alongside SOUL.md and other bootstrap files. ClawHub is the community registry where developers publish and discover skills. This decoupled architecture means you can add database migration support, deployment workflows, or code review capabilities to any agent without modifying its core configuration.

Key Takeaways

  • 1A skill is a directory containing a SKILL.md file (instructions), optional tool schemas (tools.json), and a manifest (skill.json) with metadata like name, version, author, and required tools. The SKILL.md is the heart of the skill -- it teaches the agent how and when to use the capability.
  • 2Skills are loaded into the agent's system prompt at startup, after SOUL.md and IDENTITY.md but before MEMORY.md. This means skill instructions have lower precedence than persona definitions but higher precedence than accumulated knowledge.
  • 3ClawHub is the community registry for publishing and discovering skills. Skills are versioned, searchable by keyword, and can declare dependencies on specific tools. Install with `openclaw skills install`, publish with `openclaw skills publish`.
  • 4Skill composition allows agents to use multiple skills simultaneously. A coding agent might have skills for testing, linting, and deployment installed together. Skills should be focused on a single capability to compose cleanly without instruction conflicts.
  • 5Skills declare their required tools in the manifest. If an agent does not have a required tool in its allow list, the skill installation warns you. This prevents installing a deployment skill on an agent that cannot run shell commands.
  • 6Skill versioning follows semver. When you update a skill on ClawHub, existing installations are not automatically updated. Use `openclaw skills update` to pull new versions. Pin versions in production to prevent unexpected behavior changes.

Master openclaw skills & clawhub registry

Take the Introduction to OpenClaw course with hands-on lessons and challenges.

Examples

Skill directory structure and manifest

bash

Every skill is a directory with at least a SKILL.md and skill.json. The manifest declares metadata and required tools. When installing the skill, OpenClaw checks that the target agent has all required tools. The tags field helps discoverability on ClawHub.

SKILL.md ā€” Teaching the agent a capability

markdown

SKILL.md is written as instructions the agent follows literally. The 'When to Use' section helps the agent decide when to activate the skill. Safety rules define hard boundaries. Common patterns give the agent reference commands. Clear, specific instructions produce reliable agent behavior.

Installing and managing skills from ClawHub

bash

ClawHub works like npm for agent capabilities. Search by keyword, install per agent, and manage versions independently. The install command checks that the agent has the required tools and warns if any are missing. Skills are versioned so you can pin to a known-good version in production.

Composing multiple skills on a single agent

json

A single agent can have multiple skills installed. Each skill's SKILL.md instructions are appended to the system prompt. The agent decides which skill to activate based on the 'When to Use' section. Keep skills focused and non-overlapping to avoid instruction conflicts when composing.

Viewing the assembled system prompt with skills

bash

The prompt preview shows exactly what the agent sees. Skills are loaded after persona files but before memory. The stats flag shows token usage per section, helping you identify bloated skills that consume too much of the context budget. Keep total skill tokens under 2,000 for most agents.

Common Mistakes

Mistake:

Writing overly broad skills that try to cover many scenarios (e.g., a single 'DevOps' skill covering deployments, migrations, monitoring, and alerting)

Fix:

Each skill should cover one focused capability. Create separate skills for deployment, migration, monitoring, and alerting. Focused skills compose better, are easier to test, and can be installed independently on different agents.

Mistake:

Installing a skill on an agent that lacks the required tools, then wondering why the agent cannot perform the skill's actions

Fix:

Check the skill's requiredTools in its manifest. Ensure the agent has all required tools in its tools.allow list before installing. The `openclaw skills install` command warns about missing tools -- do not ignore those warnings.

Mistake:

Not including a 'When to Use' section in SKILL.md, causing the agent to activate the skill at inappropriate times

Fix:

Always include a clear 'When to Use' section that describes the trigger conditions. Without it, the agent may attempt to use the skill for unrelated requests, producing confusing behavior.

Mistake:

Auto-updating skills in production without testing, causing unexpected changes in agent behavior after a skill author pushes a new version

Fix:

Pin skill versions in production configurations. Test skill updates in a staging environment first. Use `openclaw skills update` deliberately, not automatically.

Mistake:

Installing too many skills on a single agent, bloating the system prompt and consuming most of the context window before the conversation even starts

Fix:

Monitor system prompt token usage with `openclaw agent prompt --stats`. Keep total skill tokens under 2,000. If an agent needs many capabilities, consider splitting into multiple specialized agents with routing.

Best Practices

  • Write SKILL.md files with explicit 'When to Use' triggers, step-by-step instructions, and clear safety rules. The agent follows these instructions literally -- vague guidance produces unreliable behavior.
  • Keep each skill focused on a single capability. A skill for database migration should not also cover deployment. Composing multiple focused skills is more maintainable than one monolithic skill.
  • Declare all required tools in the skill manifest (skill.json). This enables the install command to verify compatibility and prevents runtime failures when the agent tries to use an unavailable tool.
  • Pin skill versions in production and test updates in staging first. A skill update changes the agent's system prompt and can alter behavior in unexpected ways.
  • Use `openclaw agent prompt --stats` to monitor the token cost of installed skills. Skills that consume too many tokens leave less room for conversation context.
  • Publish reusable skills to ClawHub with descriptive tags, a clear README, and version history. Community skills benefit everyone and reduce the effort of building agent capabilities from scratch.

Summary

OpenClaw skills are reusable agent capabilities packaged as SKILL.md files with manifests and optional tool definitions. They are installed per agent and injected into the system prompt alongside bootstrap files. ClawHub is the community registry for discovering, installing, and publishing skills. Skills should be focused on a single capability, declare their required tools, and include clear 'When to Use' triggers and safety rules. Pin versions in production, monitor token usage, and compose multiple focused skills rather than building monolithic ones.

Practice OpenClaw with hands-on challenges

Learn openclaw skills & clawhub registry hands-on in your IDE

Interactive lessons and challenges on Stanza, practice in VS Code, Cursor, or the web.

Related Concepts

Openclaw Custom SkillsOpenclaw ToolsOpenclaw AgentsOpenclaw Soul PersonaOpenclaw Gateway

Related Cheatsheets

Openclaw Cli Cheatsheet

Master OpenClaw with Stanza

Interactive lessons and challenges, right in your code editor.

Check the free courses. No credit card.