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.