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:
| Level | Content | When Loaded | Size Limit |
|---|
| 1st | name + description | Always in context | ~100 words |
| 2nd | SKILL.md body | After skill triggers | <500 lines |
| 3rd | references/ / scripts/ | As needed | Unlimited |
Key rule: If SKILL.md exceeds 500 lines, split content into references/ files.
Principle 3: Match Freedom to Task Fragility
| Freedom | Form | Best For |
|---|
| High | Free-text instructions | Multiple valid approaches, context-dependent decisions |
| Medium | Pseudocode / parameterized scripts | Preferred pattern exists, some variation OK |
| Low | Fixed scripts, few params | Brittle operations, consistency critical |
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
< 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:
| Resource | When to Use | Example |
|---|
scripts/ | Deterministic execution, repeated code patterns | PDF rotation, API call wrappers |
references/ | Detailed docs loaded on demand | API docs, DB schemas, company policies |
assets/ | Files copied into output | Templates, logos, fonts |
Step 3: Initialize Skill Folder
cd <workspace>/skills
python3 <skill-creator>/scripts/init_skill.py <skill-name> \
--path . --resources scripts,references
Or manually:
mkdir -p skills/<skill-name>/{scripts,references}
touch skills/<skill-name>/SKILL.md
Step 4: Write SKILL.md
Frontmatter rules (two hard rules):
name: lowercase + hyphens, ≤64 charsdescription: "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 <skill-creator>/scripts/quick_validate.py <skill-path>
Validation checks:
- Frontmatter has
name + description
name is lowercase hyphen-casedescription has no < > 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:
| Platform | When to Consider | How |
|---|
| ClawHub | For sharing skills publicly with the OpenClaw community | clawhub publish <path> --slug <slug> --version 1.0.0 |
| GitHub | For version control, collaboration, or personal backup | git init && git add . && git commit then push to a repo |
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:
| Real Value | Placeholder Format | Example |
|---|
| API Base URL | {{SERVICE_BASE_URL}} | {{ERP_BASE_URL}} |
| API Token | {{ERP_API_TOKEN}} | (never expose real value) |
| Host address | {{SYNOLOGY_HOST_LAN}} | {{SYNOLOGY_HOST_LAN}}:5006 |
| File path | {{DSM_WEBDAV_ROOT}} | {{DSM_WEBDAV_ROOT}}/opencode/ |
| Database | {{POSTGRES_HOST}} | {{POSTGRES_HOST}}:5432 |
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
| Dimension | Bad Skill | Good Skill |
|---|
| description | "An Excel skill" | "Create/edit Excel with formulas/formatting. Triggered: user provides .xlsx, asks to generate report or format data." |
| body | Walls of commands mixed together | Clear: When to Use → Steps → Constraints → Examples |
| examples | None | Good/bad comparisons — knows what the Agent actually needs |
| length | 1000+ lines all in SKILL.md | ≤500 lines in SKILL.md, references/ for details |
| constraints | None | Real failure experience turned into rules |
7. Quick Checklist
For every skill you create or audit, confirm:
