create-skill

Create Skill

A meta-skill for onboarding new skills into openclaw-superpowers. Follow this process whenever you or a contributor wants to add a new skill.

Step 1: Define the Skill

Answer these questions before writing anything:

1. What does this skill do? (one sentence)
2. When should the agent use it? (the trigger)
3. Is it core or OpenClaw-native?
   • Core: General agent methodology (brainstorming, debugging, planning). Works in any agent runtime.
   • OpenClaw-native: Requires persistence, long-running sessions, or memory. Specific to OpenClaw's always-on model.
4. Does an existing skill already cover this? If yes, extend it instead of creating a new one.
5. Does this skill need to persist state between sessions or wakeups? If yes → stateful: true + STATE_SCHEMA.yaml.

Step 2: Choose a Name

• Use kebab-case: my-new-skill
• Name describes the action, not the category: retry-with-backoff not error-handling-utils
• Keep it short — 2-4 words max

Step 3: Scaffold the Skill

Create the directory and files:

skills/<core|openclaw-native>/<skill-name>/
  ├── SKILL.md
  └── STATE_SCHEMA.yaml   # only if stateful: true

Use the frontmatter template for SKILL.md (optional fields shown as comments):

---
name: <skill-name>
description: <One sentence — what it does and when to use it.>
# cron: "<5-field cron expression>"   # optional: if skill runs on a schedule
# stateful: true                       # optional: if skill persists state
---

See TEMPLATE.md for the full content structure.

Step 4: Write the Content

Follow these conventions (learned from existing skills):

• Be direct. Open with the core principle, not a preamble. ("Plans prevent wasted work." not "This skill helps you write plans.")
• Be prescriptive. Tell the agent exactly what to do, step by step. Avoid vague guidance.
• Be brief. The best skills in this repo are under 50 lines. If it's longer, split into smaller skills.
• Include decision criteria. Tell the agent when to use it and when not to.
• Use checklists for verification steps (see verification-before-completion).
• Add checkpoint guidance if the skill applies to work spanning multiple sessions.
• State in prose is a mistake. If your skill describes saving progress to markdown or memory files, use stateful: true + STATE_SCHEMA.yaml instead.

Step 5: Validate

Before committing, check:

• Frontmatter is correct — name matches directory name, description is one clear sentence
• File is at the right path — skills/<core|openclaw-native>/<name>/SKILL.md
• No overlap with existing skills — if there's overlap, merge or differentiate clearly
• Follows the template — has When to Use, The Process, and Key Principles sections
• Under 80 lines — if longer, consider splitting
• Actionable — every step tells the agent what to do, not what to think about
• Testable — you can tell whether the agent followed the skill correctly by looking at its output
• If stateful: true — STATE_SCHEMA.yaml exists with version: and fields: keys
• If cron: is set — expression is valid 5-field cron syntax

Step 6: Register

No manual registration needed. OpenClaw auto-discovers skills from the extensions directory. Ensure:

1. The directory is under skills/core/ or skills/openclaw-native/
2. The file is named exactly SKILL.md
3. The install symlink is in place (install.sh handles this)
4. For stateful skills, install.sh creates ~/.openclaw/skill-state/<skill-name>/ automatically
5. For skills with cron:, install.sh registers them with OpenClaw's cron on next run

Common Mistakes

• Too abstract. "Think carefully about edge cases" is not a skill step. "List 3 edge cases and write a test for each" is.
• Too broad. If a skill covers more than one distinct workflow, split it.
• Missing triggers. Without clear "when to use" criteria, the agent won't know to invoke it.
• Duplicating existing skills. Check brainstorming, writing-plans, systematic-debugging, and verification-before-completion before creating something similar.
• State in prose. If your skill describes saving progress to markdown or memory files, use stateful: true with a STATE_SCHEMA.yaml instead — it's structured, machine-readable, and resumable.