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

CODEBLOCK0

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:

CODEBLOCK1

• - 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. 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>"
   }
   

1. 5. ## Examples: Table with realistic input/output pairs (minimum 3 rows)
2. 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 INLINECODE13
• 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 INLINECODE18
• 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:

CODEBLOCK3

5. Quality check

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

• - [ ] Frontmatter has name + INLINECODE21
• [ ] 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. 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 |