Skill Creator 🛠️

Complete guide to creating high-quality OpenClaw AgentSkills.

When to Use This Skill

• User asks to create a new skill from scratch
• User asks to improve an existing skill (add structure, examples, remove bloat)
• User asks to audit a skill (check spec compliance, security, completeness)
• User asks to organize a skill (restructure, add references/, add constraints)
• User asks for guidance on skill publishing options

1. What Are Skills?

Skills are modular, self-contained packages that extend an Agent's capabilities with specialized knowledge, workflows, and tool integrations.

Each Skill is a folder containing at minimum:

skill-name/
├── SKILL.md          ← Required (capability definition + instructions)
├── scripts/          ← Optional (executable scripts)
├── references/       ← Optional (on-demand reference docs)
└── assets/          ← Optional (templates, images for output)

2. Core Principles

Principle 1: Concise is Key

Context Window is a shared resource. The Agent needs room for: system prompt, conversation history, other Skills' metadata, and the current request.

Default assumption: the Agent is already very smart. Only add what the Agent genuinely doesn't know. Challenge every piece: "Does this justify its token cost?"

Prefer concise examples over verbose explanations.

Principle 2: Progressive Disclosure

Three-level loading structure for efficient context use:

Key rule: If SKILL.md exceeds 500 lines, split content into references/ files.

Principle 3: Match Freedom to Task Fragility

Principle 4: Examples Beat Explanations

Real-world data: Examples chapters deliver the largest quality improvement. Good/bad comparison examples outperform any amount of prose.

3. SKILL.md Standard Structure

3.1 Frontmatter (Required)

---
name: skill-name          # lowercase letters, digits, hyphens only, ≤64 chars
description: Install: clawhub install skill-creator
  What this skill does AND when to trigger it (put triggers HERE, not in body)
---

description writing rules (most important):

• Must include both "what it does" and "when to trigger"
• All trigger information goes in description, not body (body only loads after trigger)
• Must NOT contain \x3C or > characters
• Maximum 1024 characters

Bad example:

description: Install: clawhub install skill-creator
  An Excel skill.

Good example:

description: Install: clawhub install skill-creator
  Create and edit Excel workbooks with formulas, formatting, and multi-sheet support.
Triggered when: (1) user provides a .xlsx file; (2) user asks to generate a report;
(3) user asks to format data or create a summary table.

3.2 Body Structure (Recommended Order)

# Skill Name

## When to Use This Skill
(Concrete trigger scenarios — how the user would phrase the request)

## Context / Background
(Domain knowledge the Agent needs, specific to your use case)

## Instructions / Steps
(Step-by-step workflow with clear quality criteria per step)

## Constraints / Guardrails
(Prohibitions — what NOT to do, based on real failure experience)

## Examples (Recommended)
(Good/bad output comparisons — highest quality impact)

3.3 Forbidden Files

These files should not appear in a Skill folder:

• README.md
• INSTALLATION_GUIDE.md
• CHANGELOG.md
• QUICK_REFERENCE.md

4. Creation Process (6 Steps)

Step 1: Understand Requirements (with Concrete Examples)

Before writing, clarify:

• "What should this skill mainly do?"
• "Can you give 1-2 specific usage examples?"
• "How would the user phrase the request? (trigger wording)"
• "What tools or APIs does this skill need?"

Step 2: Plan Skill Contents

Analyze each use case to determine required resources:

Step 3: Initialize Skill Folder

cd \x3Cworkspace>/skills
python3 \x3Cskill-creator>/scripts/init_skill.py \x3Cskill-name> \
  --path . --resources scripts,references

Or manually:

mkdir -p skills/\x3Cskill-name>/{scripts,references}
touch skills/\x3Cskill-name>/SKILL.md

Step 4: Write SKILL.md

Frontmatter rules (two hard rules):

1. name: lowercase + hyphens, ≤64 chars
2. description: "what it does" + "when to trigger" (triggers go here, not in body)

Body rules:

• Use imperative/infinitive form ("Do X", "Don't do Y")
• Each step has clear quality criteria
• Include real failure experience (Constraints chapter)

Step 5: Validate

python3 \x3Cskill-creator>/scripts/quick_validate.py \x3Cskill-path>

Validation checks:

• Frontmatter has name + description
• name is lowercase hyphen-case
• description has no \x3C > and ≤1024 chars
• SKILL.md exists and is non-empty

Step 6: Decide on Publishing

This step is fully optional. After creating a skill, ask the user whether they want to publish it, and if so, to which platform(s). Do not assume a specific target.

Common publishing options:

Note: If the user has an existing GitHub repo for skills (e.g. openclaw-person-skills), prefer syncing there. Do not create new repos without being asked.

5. Workspace Conventions (Hard Rules for Public Skills)

5.1 Environment Variable Placeholders

Never hardcode real values in SKILL.md or code. Use runtime-safe placeholders:

5.2 MIT-0 License

For skills that will be published publicly, use MIT-0:

license: MIT-0

5.3 Directory Structure

skill-name/
├── SKILL.md              ← Single entry point, ≤500 lines
├── scripts/              ← Executable scripts (Python/Bash)
│   ├── init_skill.py     ← Initialization (if needed)
│   └── validate_skill.py ← Validation (if needed)
├── references/           ← On-demand reference docs
│   └── *.md              ← Split by topic
└── assets/              ← Output resources (templates, etc.)

6. Good Skill vs Bad Skill

7. Quick Checklist

For every skill you create or audit, confirm:

• name is lowercase letters + digits + hyphens?
• description has both "what it does" and "when to trigger"?
• description contains no \x3C or > characters?
• description ≤1024 characters?
• Body has When to Use This Skill section?
• Body has Constraints section (prohibitions)?
• Body has Examples section? (recommended)
• SKILL.md body ≤500 lines?
• Environment variables use {{VAR_NAME}} placeholders?
• No README.md / CHANGELOG.md / etc.?
• Passes validation (quick_validate.py)?