Skill Build Helper

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:

   {
     "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