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:

| Mode | Trigger | |------|---------| | Create | User wants a new skill | | Optimize | User wants to improve or review an existing skill |

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:

```yaml --- 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:
5. ```json
6. {
7. "tool": "exec",
8. "command": "<shell command here>"
9. }
10. ```
11. `## Examples`: Table with realistic input/output pairs (minimum 3 rows)
12. 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:

```markdown # <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

| User says | Mode | Action | |-----------|------|--------| | "I want to create a skill that tracks my reading list" | Create | Scaffold `reading-track/`, gather examples, write SKILL.md + README.md | | "Can you review my sm-saver skill?" | Optimize | Read `sm-saver/SKILL.md`, run checklist, report issues | | "Build a skill for checking server status" | Create | Scaffold `server-check/`, gather examples, write SKILL.md + README.md | | "Improve the reminder skill for ClawHub" | Optimize | Read `reminder/SKILL.md`, run checklist, add README.md if missing |