skillcraft

Skillcraft — OpenClaw Skill Designer

An opinionated guide for creating OpenClaw skills. Focuses on OpenClaw-specific integration — message routing, cron scheduling, memory persistence, channel formatting, frontmatter gating — not generic programming advice.

Docs: https://docs.openclaw.ai/tools/skills · https://docs.openclaw.ai/tools/creating-skills

Model Notes

This skill is written for frontier-class models (Opus, Sonnet). If you're running a cheaper model and find a stage underspecified, expand it yourself — the design sequence is a scaffold, not a script. Cheaper models should:

• Read the pattern files in {baseDir}/patterns/ more carefully before architecting
• Spend more time on Stage 2 (capability discovery) — enumerate OpenClaw features explicitly
• Be more methodical in Stage 4 (spec) — write out the full structure before implementing
• Consult https://docs.openclaw.ai when unsure about any OpenClaw feature

---

The Design Sequence

Stage 0: Inventory (Extraction Only)

Skip if building from scratch. Use when packaging existing functionality (scripts, TOOLS.md sections, conversation patterns, repeated instructions) into a skill.

Gather what exists, where it lives, what works, what's fragile. Then proceed to Stage 1.

Stage 1: Problem Understanding

Work through with the user:

1. What does this skill do? (one sentence)
2. When should it load? Example phrases, mid-task triggers, scheduled triggers
3. What does success look like? Concrete outcomes per example

Stage 2: Capability Discovery

Generalisability

Ask early: Is this for your setup, or should it work on any OpenClaw instance?

Choice	Implications
Universal	Generic paths, no local assumptions, ClawHub-ready
Particular	Can reference local skills, tools, workspace config

Skill Synergy (Particular Only)

Scan <available_skills> from the system prompt for complementary capabilities. Read promising skills to understand composition opportunities.

OpenClaw Features

Review the docs with the skill's needs in mind. Think compositionally — OpenClaw's primitives combine in powerful ways. Key docs to check:

Need	Doc
Messages	/concepts/messages
Cron/scheduling	/automation/cron-jobs
Subagents	/tools/subagents
Browser	/tools/browser
Canvas UI	/tools/ (canvas)
Node devices	/nodes/
Slash commands	/tools/slash-commands

See {baseDir}/patterns/composable-examples.md for inspiration on combining these.

Stage 3: Architecture

Based on Stages 1–2, identify which patterns apply:

If the skill...	Pattern
Wraps a CLI tool	{baseDir}/patterns/cli-wrapper.md
Wraps a web API	{baseDir}/patterns/api-wrapper.md
Monitors and notifies	{baseDir}/patterns/monitor.md

Load all that apply and synthesise. Most skills combine patterns.

Script vs. instructions split: Scripts handle deterministic mechanics (API calls, data gathering, file processing). SKILL.md instructions handle judgment (interpreting results, choosing approaches, composing output). The boundary is: could a less intelligent system do this reliably? If yes → script.

Stage 4: Design Specification

Present proposed architecture for user review:

1. Skill structure — files and directories
2. SKILL.md outline — sections and key content
3. Components — scripts, modules, wrappers
4. State — stateless, session-stateful, or persistent (and where it lives)
5. OpenClaw integration — which features, how they interact
6. Secrets — env vars, keychain, config file (document in setup section, never hardcode)

State locations:

• <workspace>/memory/ — user-facing context
• {baseDir}/state.json — skill-internal state (travels with skill)
• <workspace>/state/<skill>.json — skill state in common workspace area

If extracting: include migration notes (what moves, what workspace files need updating).

Validate: Does it handle all Stage 1 examples? Any contradictions? Edge cases?

Iterate until the user is satisfied. This is where design problems surface cheaply.

Stage 5: Implementation

Default: same-session. Work through the spec with user review at each step. Reserve subagent handoff for complex script subcomponents only — SKILL.md and integration logic stay in the main session.

1. Create skill directory + SKILL.md skeleton (frontmatter + sections)
2. Scripts (if any) — get them working and tested
3. SKILL.md body — complete instructions
4. Test against Stage 1 examples

If extracting: update workspace files, clean up old locations, verify standalone operation.

---

Crafting the Frontmatter

The frontmatter determines discoverability and gating. Format follows the AgentSkills spec with OpenClaw extensions.

---
name: my-skill
description: [description optimised for discovery — see below]
homepage: https://github.com/user/repo  # optional
metadata: {"openclaw":{"emoji":"🔧","requires":{"bins":["tool"],"env":["API_KEY"]},"primaryEnv":"API_KEY","install":[...]}}
---

Critical: metadata must be a single-line JSON object (parser limitation).

Description — Write for Discovery

The description determines whether the skill gets loaded. Include:

• Core capability — what it does
• Trigger keywords — terms users would say
• Contexts — situations where it applies

Test: would the agent select this skill for each of your Stage 1 example phrases?

Frontmatter Keys

Key	Purpose
name	Skill identifier (required)
description	Discovery text (required)
homepage	URL for docs/repo
user-invocable	true/false — expose as slash command (default: true)
disable-model-invocation	true/false — exclude from model prompt (default: false)
command-dispatch	tool — bypass model, dispatch directly to a tool
command-tool	Tool name for direct dispatch
command-arg-mode	raw — forward raw args to tool

Metadata Gating

OpenClaw filters skills at load time using metadata.openclaw:

Field	Effect
always: true	Skip all gates, always load
emoji	Display in macOS Skills UI
os	Platform filter (darwin, linux, win32)
requires.bins	All must exist on PATH
requires.anyBins	At least one must exist
requires.env	Env var must exist or be in config
requires.config	Config paths must be truthy
primaryEnv	Maps to skills.entries.<name>.apiKey
install	Installer specs for auto-setup (brew/node/go/uv/download)

Sandbox note: requires.bins checks the host at load time. If sandboxed, the binary must also exist inside the container.

Token Budget

Each eligible skill adds ~97 chars + name + description + location path to the system prompt. Keep descriptions informative but not bloated — every character costs tokens on every turn.

Install Specs

"install": [
  {"id": "brew", "kind": "brew", "formula": "tap/tool", "bins": ["tool"], "label": "Install via brew"},
  {"id": "npm", "kind": "node", "package": "tool", "bins": ["tool"]},
  {"id": "uv", "kind": "uv", "package": "tool", "bins": ["tool"]},
  {"id": "go", "kind": "go", "package": "github.com/user/tool@latest", "bins": ["tool"]},
  {"id": "dl", "kind": "download", "url": "https://...", "archive": "tar.gz"}
]

Path Conventions

Token	Meaning
{baseDir}	This skill's directory (OpenClaw resolves at runtime)
<workspace>/	Agent's workspace root

• Use {baseDir} for skill-internal references (scripts, state, patterns)
• Use <workspace>/ for workspace files (TOOLS.md, memory/, etc.)
• Never hardcode absolute paths — workspaces are portable
• For subagent scenarios, include path context in the task description (sandbox mounts differ)

References

• Pattern files: {baseDir}/patterns/ (cli-wrapper, api-wrapper, monitor, composable-examples)
• OpenClaw docs: https://docs.openclaw.ai/tools/skills
• ClawHub: https://clawhub.com