Skills Creator

Guide the creation, review, and optimization of OpenClaw skills that trigger reliably and instruct LLMs clearly. Based on analysis of top-performing skills across the ClawHub ecosystem.

Quick Reference

User wants...	Do this
Create a new skill	→ Mode 1: Gather requirements, pick complexity tier, write frontmatter + body
Review an existing skill

→ Mode 2: Run quality checklist, output findings as table | | Fix poor triggering | → Focus on Description Writing Formula, rewrite with trigger phrases | | Retrofit / optimize a skill | → Mode 3: Audit → rewrite description → restructure content → re-audit | | Add external API integration | → Mode 4: Create scripts/ with curl wrapper, declare dependencies | | Publish to ClawHub | → Verify quality checklist passes, then clawhub publish |

Important Rules

Rule 1: Always determine complexity tier first

Before writing anything, classify the skill into a tier. This decides file structure, SKILL.md length, and whether supporting directories are needed.

Tier	When to use	SKILL.md size	Directories
Simple	Pure instructions, no executable code	< 150 lines	None
Medium

Needs scripts or deep reference docs | 100–300 lines | scripts/ or references/ |
| Complex | Multiple workflows + hooks + cross-platform | 200–650 lines | Multiple subdirs |

Rule 2: Description is the highest-leverage field

The description in frontmatter determines whether an LLM activates the skill at all. Spend disproportionate effort here. A mediocre skill with a great description outperforms a great skill with a mediocre description.

Rule 3: Write instructions for an LLM, not documentation for a human

The SKILL.md is injected into an LLM's context. Write actionable directives ("Do X when Y"), not explanatory documentation ("This skill provides..."). The LLM needs to know what to do, not what the skill is.

Rule 4: Use tables for decision logic, not prose

Tables are the LLM's fastest lookup structure. Any conditional logic ("if X then Y") should be a table row, not a paragraph. Reserve prose for context that doesn't fit a table.

Rule 5: The skill must describe itself accurately and be internally consistent

Self-consistency is a quality signal. If the skill teaches "add a Quick Reference table", it must have one. If it references a tool, that tool must exist and its description must accurately reflect what it does. Never claim capabilities the skill doesn't have.

Rule 6: Never auto-execute generated scripts without user confirmation

This skill guides the creation of files including shell scripts. Always present generated scripts to the user for review before executing them. Never run chmod +x or execute a newly created script without explicit user approval. The skill is instructional — the user decides what to run.

---

Workflow Modes

Mode 1: Create New Skill

Step 1: Gather requirements

Ask the user:

• - What does the skill do? (one sentence)
• What triggers it? (user phrases, situations, events)
• Does it need external tools, APIs, or binaries?
• Does it need environment variables?

Step 2: Determine complexity tier

Use the tier table from Rule 1. When uncertain, start Simple — it's easier to add complexity than remove it.

Step 3: Write frontmatter

CODEBLOCK0

Field rules:

Field	Required	Format	Rules
INLINECODE5	Yes	lowercase kebab-case	Must match folder name. No spaces, no uppercase.
INLINECODE6

Yes | Single string | Follow the Description Writing Formula below. Include 5+ trigger phrases. |
| version | Yes | semver | Independent from any npm/PyPI package version. |
| homepage | No | URL | Link to source repo or documentation site. |
| metadata | No | Single-line JSON | Parser does not support multiline. Use clawdbot key (not openclaw). |

Metadata sub-fields:

Sub-field	Purpose	Example
INLINECODE12	Visual identifier on ClawHub	INLINECODE13
INLINECODE14

Executables the skill needs | ["node", "npx", "curl"] |
| requires.env | Environment variables needed | ["TAVILY_API_KEY"] |
| primaryEnv | Main env var for quick setup hint | "TAVILY_API_KEY" |

Step 4: Write SKILL.md body

Follow this section order:

1. 1. Title + one-paragraph intro — What it does, in action-oriented language
2. Quick Reference table — | User wants... | Do this | — 4–8 rows covering main use cases
3. Important Rules — Numbered constraints the LLM must follow (3–5 rules)
4. Workflow Modes — Discrete scenarios with step-by-step instructions
5. Reference sections — Field references, formulas, lookup tables
6. Gotchas — Critical pitfalls with one-line fixes
7. Further Reading — Links to references/ and assets/ files

Use the starter template at {baseDir}/assets/skill-template.md as a starting point.

Step 5: Create supporting files (Medium/Complex tiers)

Directory	When to create	What goes inside
INLINECODE24	SKILL.md exceeds 200 lines, or has deep-dive content	Detailed guides, examples, troubleshooting
INLINECODE25

Skill needs executable code (API calls, automation) | Shell/Node scripts using {baseDir} paths | | assets/ | Skill provides templates for users to copy | Starter files, config templates | | hooks/ | Skill needs event-driven triggers (rare) | Hook handlers for agent lifecycle events |

Never create _meta.json — ClawHub generates it automatically.

Step 6: Run quality review

Read {baseDir}/references/quality-checklist.md and run through all 24 checks. Fix any failures before considering the skill complete.

---

Mode 2: Review Existing Skill

1. 1. Ask the user to provide their SKILL.md content (or a file path to read)
2. Read INLINECODE31
3. Evaluate the skill against all 6 categories (24 checks total)
4. Present findings as a table:

CODEBLOCK1

1. 5. Prioritize fixes by impact: Description > Structure > Security > Style
2. Offer to apply fixes directly if the user provides a file path

---

Mode 3: Retrofit / Optimize Existing Skill

For skills that exist but don't follow best practices:

1. 1. Audit: Run the full quality checklist, list all failures
2. Rewrite description: Apply the Description Writing Formula — this has the highest impact
3. Add Quick Reference: If missing, create a situation → action table from the skill's content
4. Convert prose to tables: Find any conditional logic in paragraphs, restructure as table rows
5. Add guard clauses: Ensure "When to use" and "When NOT to use" are explicit
6. Extract deep content: Move anything beyond 300 lines into INLINECODE32
7. Add negative cases: Ensure fallback handling exists (what to do when things fail)
8. Re-audit: Run the checklist again to verify all fixes

---

Mode 4: Add External API Integration

When a skill needs to call an HTTP API (image generation, search, translation, etc.):

Pattern: scripts/ with curl wrapper

Create scripts/call-api.sh:

CODEBLOCK2

Update metadata to declare dependencies

CODEBLOCK3

Reference in SKILL.md

CODEBLOCK4

Note: Replace the placeholder URL, headers, and body with the actual API specification. Declare ALL required environment variables in metadata.clawdbot.requires.env.

---

Description Writing Formula

Formula:

CODEBLOCK5

Good example:

Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Claude ('No, that's wrong...', 'Actually...'), (3) User requests a capability that doesn't exist, (4) An external API or tool fails.

Bad example:

A helpful skill for improving agent capabilities and making things better.

Why bad: no trigger phrases, no specific scenarios, vague value proposition. The LLM has no pattern to match against user input.

Trigger phrase checklist — include at least 5 of these patterns:

Pattern	Example
Imperative verb phrase	"create a skill", "review my skill"
Question format

"how do I make a skill", "what makes a good skill" |
| Topic mention | "discusses skill development", "SKILL.md structure" |
| Tool/platform name | "OpenClaw", "ClawHub", "agent skill" |
| Problem statement | "skill not triggering", "fix my description" |

---

File Organization Guide

Path	Purpose	When to create
INLINECODE35	Core instructions — always present	Always
INLINECODE36

Deep-dive docs, examples, troubleshooting | SKILL.md > 200 lines or has detailed reference content |
| scripts/ | Executable code (shell, Node.js) | Skill wraps an API or automates a task |
| assets/ | Templates, config files for users to copy | Skill generates boilerplate |
| hooks/ | Event-driven agent lifecycle handlers | Skill needs automatic triggers (rare) |
| _meta.json | Never create — auto-generated by ClawHub | Never |

Keep SKILL.md under 300 lines. Extract to references/ beyond that threshold.

Use {baseDir} in SKILL.md to reference files within the skill package — the platform resolves this to the skill's installation path at runtime.

---

Gotchas

• - Metadata must be single-line JSON — the ClawHub parser does not support multiline. {"clawdbot":{"emoji":"🔧"}} not formatted JSON.
• Never create _meta.json — ClawHub auto-generates it on publish. Committing one causes conflicts.
• Use {baseDir} for script paths — skills can be installed anywhere. Never hardcode absolute paths.
• Avoid VirusTotal-flagged terms — words like "upload", "public URL", "CDN" trigger security scans. Use "prepare", "reference", "compress" instead.
• Pin versions in npx references — meigen@1.2.5 not meigen@latest. Floating versions are a supply chain risk.
• List ALL binaries in requires.bins — include transitive dependencies (node, npx, not just your script name).
• Use clawdbot key in metadata — not openclaw. This is the established convention (5/6 top skills use it).

Further Reading

• - {baseDir}/references/best-practices.md — comprehensive design guidelines with worked examples
• INLINECODE54 — full 24-point review checklist and retrofit process
• INLINECODE55 — copy-paste starter template for new skills