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: ·

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 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?

Skill Synergy (Particular Only)

Scan 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:

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

Stage 3: Architecture

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

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:

• /memory/ — user-facing context
• {baseDir}/state.json — skill-internal state (travels with skill)
• /state/.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

Metadata Gating

OpenClaw filters skills at load time using metadata.openclaw:

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

• Use {baseDir} for skill-internal references (scripts, state, patterns)
• Use / 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:
• ClawHub: