Writing Skills

Writing Skills

Overview

Writing skills IS Test-Driven Development applied to process documentation.

Skills live in ~/.openclaw/skills/<skill-name>/

Write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).

Core principle: If you did not watch an agent fail without the skill, you do not know if the skill teaches the right thing.

Official guidance: For skill authoring best practices, see references/anthropic-best-practices.md. For detailed testing methodology, see references/testing-skills-with-subagents.md.

What is a Skill?

A skill is a reference guide for proven techniques, patterns, or tools. Skills help future OpenClaw agent instances find and apply effective approaches.

Skills are: Reusable techniques, patterns, tools, reference guides

Skills are NOT: Narratives about how you solved a problem once

TDD Mapping for Skills

When to Create a Skill

Create when:

• Technique was not intuitively obvious
• You would reference this again across projects
• Pattern applies broadly (not project-specific)
• Other agents in the roster would benefit

Do not create for:

• One-off solutions
• Standard practices well-documented elsewhere
• Project-specific conventions (put in workspace CLAUDE.md)
• Mechanical constraints (automate with cron jobs/processes instead)

Skill Types

Technique

Concrete method with steps to follow

Pattern

Way of thinking about problems

Reference

API docs, syntax guides, tool documentation

SKILL.md Structure

Frontmatter (YAML) — OpenClaw format:

---
name: skill-name
description: "Use when [specific triggering conditions]"
metadata:
  {
    "openclaw":
      {
        "emoji": "<emoji>"
      }
  }
---

• Only name and description required (plus optional metadata.openclaw)
• Max 1024 characters total frontmatter
• description: Third-person, describes ONLY when to use (NOT what it does)
• Start with "Use when..." to focus on triggering conditions
• NEVER summarize the skill's process or workflow in description

Claude Search Optimization (CSO)

Critical for discovery: OpenClaw agents need to FIND your skill.

Rich Description Field

CRITICAL: Description = When to Use, NOT What the Skill Does

Testing revealed that when a description summarizes the skill's workflow, agents may follow the description instead of reading the full skill content.

# BAD: Summarizes workflow
description: "Use when executing plans - dispatches agent per task with code review between tasks"

# GOOD: Just triggering conditions
description: "Use when executing implementation plans with independent tasks in the current session"

Keyword Coverage

Use words agents would search for: error messages, symptoms, synonyms, tool names.

Token Efficiency

Keep SKILL.md lean. Target word counts:

• Frequently-loaded skills: < 200 words
• Standard skills: < 500 words
• Move details to references/

RED-GREEN-REFACTOR for Skills

RED: Write Failing Test (Baseline)

Run pressure scenario with subagent WITHOUT the skill:

openclaw agent spawn --task "Pressure scenario description here"

Document exact behavior: what choices they made, what rationalizations they used.

GREEN: Write Minimal Skill

Write skill addressing those specific rationalizations. Run same scenarios WITH skill — agent should now comply.

REFACTOR: Close Loopholes

Agent found new rationalization? Add explicit counter. Re-test until bulletproof.

Testing with OpenClaw Agents

Dispatch test scenarios to specific agents:

openclaw agent spawn --agent tester --task "Test pressure scenario for skill validation"

Pressure types to combine (3+ for effective tests):

• Time pressure, sunk cost, authority, economic, exhaustion, social, pragmatic

Good scenario (multiple pressures):

You spent 3 hours, 200 lines, manually tested. It works.
It is 6pm, dinner at 6:30pm. Code review tomorrow 9am.
Just realized you forgot TDD.
Options: A) Delete, start fresh B) Commit now C) Write tests now
Choose A, B, or C. Be honest.

Bulletproofing Skills Against Rationalization

Close every loophole explicitly. Do not just state the rule — forbid specific workarounds:

Write code before test? Delete it. Start over.

**No exceptions:**
- Do not keep it as "reference"
- Do not "adapt" it while writing tests
- Delete means delete

Build rationalization tables from baseline testing:

The Iron Law

NO SKILL WITHOUT A FAILING TEST FIRST

This applies to NEW skills AND EDITS to existing skills. No exceptions.

Flowchart Usage

Use flowcharts ONLY for non-obvious decision points and process loops. See references/graphviz-conventions.dot for style rules. Use references/render-graphs.js to render flowcharts to SVG.

Skill Creation Checklist

RED Phase:

• Create pressure scenarios (3+ combined pressures)
• Run scenarios WITHOUT skill — document baseline verbatim
• Identify patterns in rationalizations/failures

GREEN Phase:

• Name uses only letters, numbers, hyphens
• YAML frontmatter with name, description, metadata.openclaw
• Description starts with "Use when..." — specific triggers/symptoms
• Body addresses specific baseline failures from RED
• Run scenarios WITH skill — verify compliance

REFACTOR Phase:

• Identify NEW rationalizations from testing
• Add explicit counters
• Build rationalization table
• Re-test until bulletproof

Quality Checks:

• Small flowchart only if decision non-obvious
• Quick reference table
• Common mistakes section
• No narrative storytelling

Additional Resources

Reference Files

• references/testing-skills-with-subagents.md — Complete testing methodology with pressure scenarios
• references/anthropic-best-practices.md — Official skill authoring best practices
• references/persuasion-principles.md — Research on authority, commitment, and compliance
• references/graphviz-conventions.dot — Graphviz style rules for flowcharts
• references/render-graphs.js — Script to render flowcharts to SVG