OpenClaw Skill Creator#

Create, improve, and maintain OpenClaw AgentSkills. This guide covers the full lifecycle from pattern extraction through testing.

Why This Skill Exists#

OpenClaw skills are not just simple prompt files. Skills designed for OpenClaw's architecture — 3-layer loading (description → body → references), sub-agent context injection, Phase 0 analysis — significantly improve agent quality. This skill systematizes those design principles and provides validated examples across 5 types (pipeline, single-task, tool integration, code generation, document conversion).

Language Policy#

• SKILL.md body: Always write in English — this ensures the skill works across all language environments
• references/: English by default. Localized copies may be provided as filename.ko.md, filename.ja.md, filename.zh.md
• description Keywords: Include keywords in all target languages (English, Korean, Japanese, Chinese)
• Generated skills: Follow the same policy — English body, multilingual keywords

Key Strengths#

1. OpenClaw-native patterns — Optimized for OpenClaw architecture: sub-agent context fork, references/ lazy loading, Phase 0 structural analysis
2. 5 validated types — examples/ includes actual generated skills and case analyses for each type
3. Style Guide-centric — Skills that specify "what to preserve" and "what to compress" determine agent quality
4. skill-audit integration — Validate generated skills with skill-audit to get 0-100 scores and improvement recommendations
5. Bundled skill porting — Checklist for porting existing Codex-based bundled skills to OpenClaw patterns

OpenClaw Skill Anatomy#

text

skill-name/
├── SKILL.md                          # Required. Frontmatter + instructions.
├── references/                       # Optional. Loaded on demand by the agent.
│   ├── output-format.md              #   Output specifications
│   └── subagent-prompt-templates.md  #   Sub-agent prompt templates
├── scripts/                          # Optional. Executable code (Python/Bash/etc.)
│   ├── extract_epub.py
│   └── extract_pdf.py
├── assets/                           # Optional. Files used in output, not loaded into context.
│   └── template.html
└── examples/                         # Optional. Example files for reference.

DO NOT create: README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, LICENSE, or similar auxiliary documentation.

Frontmatter (Required)#

yaml

---
name: skill-name
description: >
  What this skill does and when it should trigger.
  Include keywords in multiple languages.
  Keywords: keyword1, keyword2, 키워드1, 키워드2.
---

• name: lowercase, hyphens only. Under 64 chars. Prefer short, verb-led names.

• description: This is the primary triggering mechanism. OpenClaw reads this to decide when to load the skill. Include:

  • What the skill does
  • When to use it (triggers, contexts)
  • Keywords in all relevant languages (localized + English)
  • Do NOT put "when to use" info in the body — it's only loaded AFTER triggering.

Loading Architecture#

OpenClaw loads skills in three layers:

1. Metadata (name + description) — Always in context. ~100 words per skill.
2. SKILL.md body — Loaded when the skill triggers. Keep under 500 lines.
3. references/ — Loaded on demand when the agent decides it's needed.

Implication: Every word in description is always costing tokens. Be concise. Every word in SKILL.md costs tokens when the skill triggers. Keep it lean.

---

Skill Creation: 5-Step Process#

Step 1: Analyze "Well-Done" Results#

Before writing anything, analyze examples of the agent performing the task well without a skill.

Ask:

• What structure did the output have?
• What did the agent preserve (examples, metaphors, quotes, data)?
• What did the agent compress (repetition, verbose explanations)?
• What judgments did the agent make (grouping, prioritization, restructuring)?
• Why did it make those judgments?

This analysis becomes the Style Guide. This is the most important step. A skill that only specifies format but not style produces dry, mediocre results.

Step 2: Analyze "Failed" Results (if available)#

If sub-agents or previous skill versions produced bad results, identify exactly what went wrong:

SymptomLikely CauseOutput is dry/blandMissing style guide — no "what to preserve" rulesFlow is disconnectedChunks processed independently — missing Phase 0 context injectionLots of duplicationMissing merge/restructure instructionsInconsistent styleNo style rules in sub-agent promptsSub-agent ignores instructionsSub-agent prompt lacks context from Phase 0

Every failure maps to a specific instruction to add to the skill.

Step 3: Write Style Guide First#

Write the Style Guide before the workflow. The workflow is "what order" — the Style Guide is "how to judge."

markdown

## Style Guide

### Essence
- What is the core of this task? (e.g., "Summarization is restructuring, not compression.")
- What perspective should the agent take?

### Preservation Criteria (NEVER discard)
- Specific examples with "why"

### Compression Criteria (what to reduce)
- Specific examples with "why"

### Style Rules
- Tone, sentence length, formatting conventions
- Rules specific to this context

Step 4: Structure the Workflow#

Build the workflow around the Style Guide:

markdown

## Workflow

### Phase 0: [Analysis Step] (★ Most Important)
What to analyze before starting, and where that information gets used.

### Phase 1~N: [Execution Steps]
Each step's specific instructions.

### Phase N+1: [Validation Step]
How to verify the output meets quality standards.

Key principles:

• Phase 0 first — analyze the full input before dividing into chunks or delegating
• Context injection for sub-agents — sub-agents have NO context from the main session. Phase 0 results must be explicitly injected into sub-agent prompts.
• Validation step — check output length, structure, and quality

Step 5: Split into References (if needed)#

If SKILL.md approaches 500 lines, split:

Content typeWhere to put itOutput structure/specificationsreferences/output-format.mdSub-agent prompt templatesreferences/subagent-prompt-templates.mdDomain knowledge (APIs, schemas)references/domain.mdExamplesreferences/examples.md

Always link references from SKILL.md with a description of when to read them.

---

Sub-Agent Design Patterns#

Sub-agents are the #1 source of skill quality degradation. The root cause is always the same: the sub-agent lacks context that the main agent has.

Pattern A: Context Injection#

Always include in sub-agent prompts:

1. Full context — "This chunk is part of [overall structure]. It covers [topic]."
2. Specific preservation list — "In this chunk, preserve: [metaphor, quote, example]"
3. Judgment criteria — 3-4 lines from Style Guide
4. Output format — How to format the result

Pattern B: Template with Fill-in-the-Blanks#

Don't copy templates verbatim. Use [ ] placeholders filled from Phase 0:

markdown

Sub-agent prompt template (fill `[ ]` from Phase 0 results):

## Context
[Overall structure from Phase 0]
[This chunk's position in the whole]

## Preserve (this chunk only)
[Specific items from Phase 0]

## Instructions
[Depth/format/style rules]

---
[Chunk text]
---

If Phase 0 didn't produce [ ] values, the template can't be filled. The sub-agent becomes a context-free "text compressor." This is why Phase 0 is mandatory.

Pattern C: Sequential Pipeline#

When multiple depth levels exist (e.g., 1x and 5x), use sequential dependency:

text

depth=1x:  Analyze → Chunk → Summarize → Merge → summary.md
depth=5x:  Analyze → Chunk → Summarize → Merge → summary.md
           → Use summary.md as skeleton → Expand → summary_5x.md

Why sequential? The simpler output provides structure for the complex one. Starting with the complex version means each chunk is independently summarized, losing overall flow.

Pattern D: Merge ≠ Concatenate#

When merging multiple chunk results:

1. Never just concatenate
2. Restructure according to Phase 0's topic flow
3. Remove duplicates (keep the most detailed version)
4. Derive overall takeaways (not just chunk summaries)

---

Skill File Organization Rules#

Keep SKILL.md Lean#

• Under 500 lines — split into references/ if longer
• Only in SKILL.md: Workflow phases, Style Guide summary, parameter tables, reference links
• In references/: Detailed specs, prompt templates, domain knowledge, examples

Reference File Best Practices#

• One level deep — all reference files link directly from SKILL.md, not from other references
• Table of contents — for reference files over 100 lines
• Never duplicate — information lives in either SKILL.md OR a reference file, never both

Workspace Skills vs Bundled Skills#

Workspace ( ~/.openclaw/workspace/skills/)Bundled ( /app/skills/)PersistenceSurvives container restartsReset on container restartScopeUser-specific, project-specificShared, system-wideWhen to useCustom workflows, domain knowledgeUniversal tools (weather, discord, etc.)Source of truthThis directory for new custom skillsReference only, don't modify

Always create custom skills in workspace. Never modify bundled skills.

---

Skill Improvement & Auditing#

Audit Checklist#

For any skill, check:

Triggering

• description clearly explains when to trigger?
• Keywords in relevant languages?
• No "when to use" sections in body (should be in description)?

Style Guide

• "What to preserve" with specific examples?
• "What to compress" with specific examples?
• Style rules explicit?

Workflow

• Phase 0 (analysis) comes first?
• Sub-agent context injection specified?
• Validation/quality check step exists?

Sub-agent Integration

• Prompt templates have [ ] placeholders filled from Phase 0?
• Clear warning about what happens without context injection?

File Organization

• SKILL.md under 500 lines?
• Long content split to references/?
• Each reference file describes when to read it?

Common Anti-Patterns#

Anti-PatternProblemFixFormat-only, no styleDry, mediocre outputAdd Style GuideSub-agent without contextDisconnected chunksAdd Phase 0 + context injectionSimple concatenationDuplication, no flowAdd restructure instructionsArbitrary chunk boundariesContent cut mid-section"Cut only at section/chapter boundaries"Parallel depth generationInconsistent structuresSequential pipeline (simple → complex)Template used verbatimContext-free instructionsFill [ ] from Phase 0 results"When to use" in bodyNever read (body loads after trigger)Move to description

---

References#

• references/openclaw-vs-codex.md — Differences from the bundled Codex skill-creator and porting checklist
• examples/summarize.md — Validation example: summarize skill (sub-agent pipeline type)
• examples/changelog.md — Validation example: changelog skill (doc conversion type)
• examples/scaffold.md — Validation example: scaffold skill (code generation type)
• examples/screenshot-capture.md — Validation example: screenshot-capture skill (tool integration type)
• examples/unit-converter.md — Validation example: unit-converter skill (single-task type)
• examples/skill-audit.md — Validation example: skill-audit (meta validation tool)