Everything you need to build, test, and publish OpenClaw skills in one place. Skills are reusable agent capabilities packaged as a SKILL.md (instructions), skill.json (manifest), and optional tools.json (custom tool definitions). This cheatsheet covers the full lifecycle: project scaffolding, parameter schemas, input validation, skill composition, local testing, debugging, and ClawHub publishing. Keep this open while you build.
| Name | Syntax | Description |
|---|---|---|
| Skill anatomy | SKILL.md + skill.json + tools.json | Every skill is a directory with SKILL.md (agent instructions), skill.json (manifest with name, version, requiredTools), and optional tools.json (custom tool definitions). |
| Create a skill | openclaw skills create <name> | Scaffold a new skill directory with template SKILL.md, skill.json, tools.json, and README.md. |
| Skill parameters | parameters: { type: "object", properties: {...} } | Define tool input schemas using JSON Schema in tools.json. OpenClaw validates parameters before execution. |
| Input validation | "required": ["field1", "field2"] | Mark required fields in the JSON Schema. OpenClaw rejects calls with missing required parameters and returns clear error messages. |
| Skill composition | skills: ["@org/skill-a", "@org/skill-b"] | Install multiple focused skills on a single agent. Each skill's SKILL.md is injected into the system prompt independently. |
| Test skills locally | openclaw skills test ./<skill-dir> --agent <id> | Run the skill against a real agent in a sandboxed session with test prompts. |
| Publish to ClawHub | openclaw skills publish ./<skill-dir> | Upload skill to ClawHub after authentication. Requires valid manifest and passing validation. |
| Skill versioning | "version": "1.2.0" (semver) | Follow semver in skill.json. Patch for fixes, minor for new instructions, major for breaking tool changes. |
| Error handling | "onError": { "retry": false, "fallback": "message" } | Define error behavior in tool definitions. Control retry logic and fallback messages for failed tool executions. |
| Skill hooks | "hooks": { "onInstall": "...", "onActivate": "..." } | Lifecycle hooks in skill.json that run on install, activation, and deactivation. Use for setup validation and cleanup. |
openclaw skills create <name>The CLI scaffolds a complete skill directory with template files. Start by editing skill.json with your metadata, then write the SKILL.md instructions.
Tips
{ name, version, description, author, requiredTools, tags, config, hooks }The manifest declares metadata, required tools, tags for ClawHub discovery, optional config defaults, and lifecycle hooks. OpenClaw reads this when installing.
Tips
Description → When to Use → Instructions → Safety Rules → Common PatternsSKILL.md is the heart of the skill. The agent reads and follows these instructions literally. Every section serves a specific purpose for the agent's decision-making.
Tips
{ tools: [{ name, description, executor, command, parameters }] }Each tool definition includes a name, description (the model reads this), executor type, command template with {{placeholders}}, and a JSON Schema for parameters.
Tips
properties.{field}.{type, enum, pattern, minimum, maximum}Use JSON Schema features for strict parameter validation: enums for fixed choices, min/max for ranges, arrays for lists, and nested objects for structured config.
Tips
executor: "function", handler: "./handlers/deploy.ts"Function executors let you write TypeScript handlers with full type safety. The handler receives validated parameters and a context object with skill config and agent metadata.
Tips
return { success, message, data }Return a structured response with success flag, human-readable message, and optional data object. The agent uses 'message' for its reply and 'data' for follow-up reasoning.
Tips
return { stream: true, generator: async function* () {...} }For long-running operations like log tailing, return a streaming response. The agent receives chunks incrementally and can relay them to the user in real time.
Tips
skills: ["@org/skill-a", "@org/skill-b"]Install multiple focused skills on a single agent. Each skill's SKILL.md is injected independently. The agent decides which skill to activate based on the 'When to Use' section.
Tips
context.invokeSkill(skillName, params)Skills can invoke tools from other installed skills via context.invokeSkill(). This enables orchestration patterns where a higher-level skill coordinates multiple capabilities.
Tips
context.{agent, session, config, workspace}The context object provides access to agent metadata, session info, skill config values, and the workspace path. Use it to make skills context-aware.
Tips
context.state.get(key) / context.state.set(key, value)Use context.state to persist data across tool invocations within a session. State is scoped to the agent and session, and survives across multiple messages.
Tips
fetch() in function executor handlersFunction executor handlers can call external APIs using fetch(). Read API tokens from environment variables — never hardcode secrets.
Tips
import { handler } from './handlers/my-tool'Unit test skill handlers by importing them directly and providing a mock context. Mock fetch() for external API calls and context.state for state management.
Tips
openclaw skills test ./<dir> --agent <id> [--prompts ...]The CLI provides sandboxed testing, validation, and prompt preview. Always validate and test locally before publishing to ClawHub.
Tips
context.log.debug() / context.log.info() / context.log.error()Use context.log for structured logging in skill handlers. Debug logs require OPENCLAW_LOG_LEVEL=debug. Error logs are always visible in `openclaw logs`.
Tips
createMockContext() from @openclaw/sdk/testingThe @openclaw/sdk/testing module provides createMockContext() for integration tests. It includes working state management, log capture, and configurable skill config.
Tips
openclaw auth login → validate → publishThe full publishing workflow: authenticate, validate, publish, verify. ClawHub reviews new skills for quality and security before they appear in search.
Tips
"version": "MAJOR.MINOR.PATCH" in skill.jsonFollow semver strictly. Existing installations are NOT auto-updated — users must explicitly update. Pin versions in production.
Tips
README.md in skill directoryA good README helps users understand what your skill does, how to install it, what tools it requires, and how to use it. This is what appears on your ClawHub skill page.
Tips
tags, description, and README in skill.jsonGood metadata makes your skill discoverable on ClawHub. Use specific names, clear descriptions, and relevant tags.
Tips
A complete skill with validated parameters. The JSON Schema enforces URL format with a regex pattern, restricts custom aliases to alphanumeric characters, and marks 'url' as required. OpenClaw validates all parameters before the handler runs.
A skill handler that calls an external API with proper error handling. Checks for the API key upfront, handles specific HTTP errors (404 for city not found), catches network errors, uses structured logging, and returns both a human-readable message and structured data.
A pipeline skill that orchestrates other skills via context.invokeSkill(). It deploys using the docker-deploy skill, verifies health using the health-check skill, and automatically rolls back if the health check fails. Dependencies are declared in skill.json so OpenClaw ensures all required skills are installed.
Missing 'When to Use' section in SKILL.md causes the agent to activate the skill at inappropriate times or ignore it entirely
Always include a 'When to Use' section with explicit trigger conditions. List specific phrases or scenarios: 'Use this skill when the user asks to deploy, check deployment status, or rollback.' Without it, the agent cannot decide when to activate your skill.
Forgetting to list required tools in skill.json leads to silent failures when the skill is installed on an agent without those tools
Audit every tool reference in your SKILL.md instructions and tools.json. Add them all to the 'requiredTools' array in skill.json. The install command warns about missing tools — but only if you declare them.
SKILL.md exceeding 1,000 tokens consumes too much context window, leaving less room for conversation and causing degraded agent performance
Check token usage with `openclaw skills validate`. If over 1,000 tokens, split into multiple focused skills. Remove redundant instructions and keep Common Patterns concise. Monitor with `openclaw agent prompt --stats`.
Publishing a skill without bumping the version in skill.json causes the publish to fail or silently overwrite the existing version
Always update the 'version' field in skill.json before running `openclaw skills publish`. Follow semver: patch for fixes, minor for new features, major for breaking changes. ClawHub rejects duplicate version numbers.
Hardcoding API keys or secrets in handler files or SKILL.md instead of reading from environment variables exposes credentials on ClawHub
Always read secrets from process.env in handler code. Document required environment variables in your README.md. Never include real tokens in SKILL.md, tools.json, or handler files. ClawHub scans for leaked secrets and blocks the publish.