🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Skill Build Helper
πŸ¦€ ClawHub

Skill Build Helper

by @spideystreet

Create or optimize an OpenClaw skill. Use when the user wants to build a new skill, improve an existing one, review a SKILL.md, or prepare a skill for ClawHu...

Versionv1.0.1
Downloads665
Installs4
#legal
TERMINAL
clawhub install skill-build-helper

πŸ“– About This Skill

name: skill-build-helper description: Create or optimize an OpenClaw skill. Use when the user wants to build a new skill, improve an existing one, review a SKILL.md, or prepare a skill for ClawHub publishing. metadata: {"openclaw":{"requires":{"bins":["jq"]}}}

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.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: 
description: . Use when .
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": ""
   }
    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:

    # 
    Requirements
    • 

    • Setup
    Usage
    <2-3 natural language examples showing what the user would say>
    Install
    \\\bash
clawhub install /
\\\

    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 |

    πŸ’‘ 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 |

    βš™οΈ Configuration