Skill Builder

A meta-skill for creating and optimizing OpenClaw skills following official best practices. Guides you through a structured workflow from intent to publish-ready skill.

Workflow

1. Understand intent

Determine the mode:

If creating: Ask the user for 2-3 concrete usage examples (what would they say to trigger this skill, what should happen). These examples drive the description and workflow design.

If optimizing: Read the existing SKILL.md and note its current structure before proceeding.

2. Scaffold the directory

Create the skill directory under ~/workspace/skills/:

<skill-name>/
├── SKILL.md          (required — agent instructions)
├── README.md         (recommended for published skills)
├── scripts/          (if deterministic code is needed)
└── references/       (if large docs needed on-demand)

Naming rules: - Lowercase, hyphens only (no underscores, no spaces) - Max 64 characters - Verb-led when possible (e.g., workout-track, skill-builder) - Folder name must match the name field in frontmatter

3. Write the SKILL.md

The SKILL.md is the core file — it contains the agent's instructions for executing the skill.

Frontmatter (YAML)

Three fields:

---
name: <skill-name>
description: <what it does>. Use when <trigger context>.
metadata: {"openclaw":{"requires":{"bins":["list","of","binaries"]}}}
---

• name: Must match folder name exactly
• description: Primary trigger mechanism. Include "Use when..." to help the agent decide when to activate. Be specific to avoid overlap with other skills
• metadata: Declare runtime dependencies. Load {baseDir}/references/frontmatter-spec.md for the full reference if needed

Body structure

Write the body following these rules:

1. Opening line: One sentence explaining what the skill does
2. ## Workflow: Numbered H3 steps (### 1. Step name) — imperative form
3. Tables for structured data (fields to extract, flags, mappings)
4. Code blocks with exact commands — use exec tool JSON format: json { "tool": "exec", "command": "<shell command here>" }
5. ## Examples: Table with realistic input/output pairs (minimum 3 rows)
6. Error handling section: What to do when things fail — always present, never retry silently

Key rules

• Keep SKILL.md under 500 lines — move detailed docs to references/
• Use {baseDir} for paths within the skill directory (e.g., {baseDir}/scripts/run.sh)
• No hardcoded secrets — read from env vars, .env, or openclaw.json via jq
• Imperative form throughout ("Extract the URL", not "The URL is extracted")
• Confirmation before state changes — show a summary and ask before writing to DB, sending messages, etc.

4. Write the README.md

User-facing documentation with these sections:

# <Skill Name>

<What it does — 1-2 lines>

## Requirements

- <binary or service 1>
- <binary or service 2>

## Setup

<Step-by-step setup instructions>

## Usage

<2-3 natural language examples showing what the user would say>

## Install

```bash
clawhub install <author>/<skill-name>
```

5. Quality check

Load {baseDir}/references/checklist.md and validate every item:

• [ ] Frontmatter has name + description
• [ ] name matches folder name
• [ ] Description includes "Use when..." trigger phrases
• [ ] No hardcoded secrets or API keys
• [ ] {baseDir} used for all internal paths
• [ ] Metadata declares runtime dependencies (requires.bins, requires.env)
• [ ] Error handling section is present
• [ ] Examples section with at least 3 rows
• [ ] SKILL.md is under 500 lines
• [ ] README.md present for published skills
• [ ] Confirmation step before any state-changing operation

Report the results as a checklist to the user, noting any failures.

6. Optimize (existing skills only)

When reviewing an existing skill:

1. Read the current SKILL.md
2. Run the quality check from Step 5
3. List each issue found with a concrete fix
4. Ask the user which fixes to apply
5. Apply approved fixes

Do not rewrite an entire SKILL.md — make targeted, minimal edits.

Examples