OpenClaw

Building Custom OpenClaw Skills👨‍💻

Building a custom OpenClaw skill lets you package domain-specific knowledge and tooling into a reusable capability that any agent can use. A custom skill consists of three parts: a SKILL.md file with instructions, an optional tools.json defining custom tool interfaces, and a skill.json manifest with metadata. This guide walks through the complete lifecycle -- from scaffolding a skill directory, writing effective instructions, defining tool parameter schemas, testing locally against a real agent, to publishing on ClawHub for the community.

Key Takeaways

  • 1The SKILL.md file is the core of every custom skill. It contains structured sections: Description (what the skill does), When to Use (trigger conditions), Instructions (step-by-step workflow), Safety Rules (hard boundaries), and Common Patterns (reference commands or templates).
  • 2Custom tool definitions in tools.json extend the agent's capabilities with domain-specific actions. Each tool has a name, description, parameter schema (JSON Schema), and an executor type (bash, http, or function). The agent calls these tools like built-in ones.
  • 3The skill.json manifest declares metadata (name, version, author), required built-in tools, dependencies on other skills, and configuration options. It is the entry point OpenClaw reads when installing the skill.
  • 4Local testing with `openclaw skills test` runs the skill against a real agent in a sandboxed session. You provide test prompts and verify the agent follows the SKILL.md instructions correctly before publishing.
  • 5Parameter schemas use JSON Schema to define tool inputs. The agent generates parameters that match the schema, and OpenClaw validates them before executing the tool. This prevents malformed inputs and provides clear error messages.
  • 6Publishing to ClawHub makes your skill available to the community. Include a README, version history, and example usage. Skills are reviewed for quality and security before appearing in search results.

Master building custom openclaw skills

Take the Personalizing Your OpenClaw Agent course with hands-on lessons and challenges.

Examples

Scaffolding a new skill with the CLI

bash

The CLI scaffolds a complete skill directory with templates for each file. This gives you the correct structure and sections to fill in. Start by editing skill.json with your metadata, then write the SKILL.md instructions.

Complete SKILL.md for a deployment capability

markdown

This SKILL.md follows the recommended structure: Description, When to Use, Prerequisites, step-by-step Instructions, a Rollback section for error recovery, Safety Rules with hard boundaries, and Common Patterns for reference. Each section serves a purpose -- the agent uses 'When to Use' to decide activation and 'Safety Rules' as inviolable constraints.

Defining custom tools with parameter schemas

json

Custom tools in tools.json define the interface the agent uses. Each tool has a name, a description the model reads to understand when to use it, an executor type (bash runs a shell command), a command template with parameter placeholders, and a JSON Schema for parameters. The confirm parameter on rollback forces the agent to get user approval before destructive actions.

Testing a skill locally before publishing

bash

Local testing catches problems before publishing. The test command creates a sandboxed session where you can verify the agent follows the SKILL.md instructions for various prompts. The validate command checks the manifest structure, SKILL.md token count, and tool schema validity. Always test with edge cases like missing prerequisites or error scenarios.

Publishing a skill to ClawHub

bash

Publishing requires authentication with your ClawHub account. The publish command uploads the SKILL.md, tools.json, and manifest. Bump the version in skill.json before publishing updates. ClawHub reviews skills for quality and security -- new skills may take a short time to appear in search results.

Common Mistakes

Mistake:

Writing SKILL.md instructions that are vague or ambiguous, like 'deploy the application carefully' instead of specific step-by-step commands

Fix:

Write concrete, numbered steps with exact commands. The agent follows instructions literally. 'Run docker compose pull, then docker compose up -d --remove-orphans' is actionable. 'Deploy carefully' is not.

Mistake:

Defining custom tools without parameter validation schemas, allowing the agent to pass malformed inputs that cause runtime errors

Fix:

Always define JSON Schema for tool parameters with types, descriptions, and required fields. OpenClaw validates parameters against the schema before execution, catching errors early with clear messages.

Mistake:

Forgetting to list required built-in tools in skill.json, causing the skill to fail silently when installed on an agent that lacks those tools

Fix:

Audit your SKILL.md instructions and tools.json for every built-in tool referenced. List them all in the requiredTools array. This enables the install command to warn about missing tools upfront.

Mistake:

Skipping local testing and publishing a skill that produces incorrect or unsafe agent behavior in real conversations

Fix:

Always test with `openclaw skills test` using at least 3-5 representative prompts, including edge cases and error scenarios. Verify the agent follows safety rules and handles failures correctly.

Mistake:

Publishing a skill with a generic name like 'deploy' that conflicts with other skills on ClawHub, causing confusion

Fix:

Use descriptive, namespaced names: 'docker-compose-deploy', 'aws-ecs-deploy', 'vercel-deploy'. Specificity reduces naming conflicts and makes the skill's purpose immediately clear in search results.

Best Practices

  • Structure every SKILL.md with five sections: Description, When to Use, Instructions, Safety Rules, and Common Patterns. This consistent structure helps the agent parse and follow the instructions reliably.
  • Define parameter schemas for all custom tools. Include type, description, and required fields. Schemas act as documentation for the model and validation for the runtime.
  • Test locally with `openclaw skills test` before publishing. Include happy path prompts, edge cases, and error scenarios. Verify the agent respects safety rules in all cases.
  • Keep SKILL.md under 1,000 tokens. Every token in the skill consumes context window space on every message. If your skill is too long, split it into multiple focused skills.
  • Version your skills using semver. Bump the patch version for fixes, minor for new instructions, and major for breaking changes to tool definitions or required tools.
  • Include a Prerequisites section in SKILL.md when the skill depends on external tools or services being available. This helps the agent give clear error messages when prerequisites are missing.

Summary

Building custom OpenClaw skills involves creating a SKILL.md with structured instructions, defining tool interfaces with JSON Schema parameters in tools.json, and declaring metadata in skill.json. Test locally with `openclaw skills test` before publishing to ClawHub. Write concrete, step-by-step instructions with explicit safety rules. Keep skills focused on a single capability and under 1,000 tokens. Define parameter schemas for all custom tools. Version with semver and test updates in staging before publishing.

Practice OpenClaw with hands-on challenges

Learn building custom openclaw skills hands-on in your IDE

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

Related Concepts

Openclaw SkillsOpenclaw ToolsOpenclaw AgentsOpenclaw Soul PersonaOpenclaw Security Sandboxing

Related Cheatsheets

Openclaw Cli CheatsheetOpenclaw Skills Development Cheatsheet

Master OpenClaw with Stanza

Interactive lessons and challenges, right in your code editor.

Check the free courses. No credit card.