Skill Creator

Other

创建、编辑、改进或审核 OpenClaw AgentSkill。触发场景：用户要求"创建一个 skill"、"写一个技能"、"帮我新建技能"、"改进这个 skill"、"审核 skill"、"整理 skill"、"完善技能说明"。同时用于：skill 目录结构调整、文件迁移（移动到 references/ 或 s...

Install

openclaw skills install ashan-skill-creator

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 chars
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 <skill-creator>/scripts/quick_validate.py <skill-path>

Validation checks:

Frontmatter has name + description
name is lowercase hyphen-case
description 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: