Skill Design Guide

30-Second Test: If you're writing a SKILL.md or your skill "works but feels messy", load this guide.

🆚 What This Is (and Isn't)

This guide answers WHY, not HOW. See references/agent-design-research.md for full industry research background.

✅ 3 Usage Modes

Hard Rules

These cannot be violated. They override all other considerations.

1. Simplicity first. Start with a single SKILL.md. Add complexity only when simpler solutions fail.
2. Brain ≠ Hands. LLM decides what to do (SKILL.md). Deterministic code does it (scripts/). Never mix them.
3. No full preload. References are loaded on-demand. Never dump everything into context at once.
4. Every skill must have: triggers, steps tagged [Deterministic]/[LLM], Hard Rules, Failure Handling, Output Format.

Principle Zero: Simplicity First

Start simple. Add complexity only when simpler solutions fall short.

Practical checklist:

• Single SKILL.md before multiple files
• Deterministic code before LLM
• Fixed workflow before dynamic Agent
• Ship MVP, iterate from output quality

Principle One: Brain / Hands / Session

Your skills already follow this: data-ai-daily-brief (scripts fetch data), benjie-model (Session layer for other skills).

Principle Two: Design for Agent Consumption

The primary reader of a skill is an agent runtime, not a human browsing a marketplace.

Verified evidence (SkillHub TRACE evaluation, 2026-08): trigger scores describe skills being "唤醒" (awakened) by user phrases and evaluated on parameter passing — both agent-runtime behaviors. The entire evaluation pipeline (including security scans) is automated. Agent-initiated install and invocation is the dominant consumption path.

Design consequences:

Practical rules:

1. Write not_for as carefully as read_when — every excluded scenario prevents a misrouted task.
2. Don't stuff trigger keywords; one precise capability sentence (plus a bilingual summary) outperforms a keyword list under embedding retrieval.
3. Invest in the body's executable sections (Hard Rules, Failure Handling, Output Format) — that is where agent execution quality is decided.

GEO Checklist (from live publish rounds, 2026-08/09)

Field-tested generative-engine optimization rules for skill descriptions. Apply these before any publish; they complement, not replace, the table above.

1. First sentence = What + Use when. The opening sentence is the model's primary routing surface — lead with the capability and the trigger condition ("Use when any X fails…"), not with background.
2. Bilingual triggers live inside description itself. Some platform search indexes (SkillHub) index only description, not description_zh — Chinese keywords must appear in the description text, not only in the dedicated Chinese field.
3. Triggers must match the user's actual phrasing: error message text (no_token, "样式丢失"), colloquial phrasing ("修改丢失", "被截断"), and platform nouns — not just your own vocabulary.
4. Description–content consistency: every capability the description promises must exist as a section in the body. A stale promise poisons routing — the agent loads the skill, finds nothing, and trust in the description degrades. (Empirical: a description advertised a tool quick-reference the body never had.)
5. Slug discipline: a slug change is a platform identity rebuild (links, installs, stats break; old slug becomes orphaned). Never rename casually. Before publishing a NEW slug, probe availability via API and validate the probe method itself against known-existing slugs — a naive probe can silently miss or mislead.
6. Boundary declarations reduce misrouting: keep not_for in sync with the description — when the description gains a new trigger phrase, check whether any not_for exclusion now conflicts with it.

Step 1: Workflow or Agent?

One question: Are the task steps predetermined?

Most things are workflows. Don't pick Agent because it sounds advanced.

Step 2: Pick a Pattern

Five workflow patterns. Full details in references/pattern-details.md.

Step 3: Skill Structure

Required

Optional

SKILL.md Template

---
name: my-skill
description: One sentence. Trigger keywords: a, b, c.
version: 1.0.0
read_when:
  - "trigger phrase 1"
  - "trigger phrase 2"
---

# Skill Name

Overview paragraph.

## Workflow

### Step 1: [Deterministic] Confirm Input
- Validate input exists
- If missing, stop and report

### Step 2: [Deterministic] Load Materials
- Read `references/xxx.md` (only needed files)

### Step 3: [LLM] Core Execution
- Generate output following these rules:
  - Rule 1
  - Rule 2

### Step 4: [LLM] Self-Check
- Verify output meets criteria → fix → re-output

### Step 5: [Deterministic] Save Output

## Hard Rules

> These cannot be violated.

1. Rule 1
2. Rule 2

## Failure Handling

| Scenario | Action |
|----------|--------|
| Source file not found | Stop, report missing file |
| Output 50% over limit | Compress and rewrite |

## Output Format

[Define exact format and fields]

Step 4: Quality Checklist

After completing a skill, run the full governance-aware checklist. Load references/quality-checklist.md for details.

Structure ✓ | Principles ✓ | Tools ✓ | Guardrails ✓ | Behavior surface ✓ | Observability ✓

Anti-Patterns

Behavior Surface: Minimal, Opt-in, Declared

Rules for anything a skill ships beyond prose — hooks, scripts, platform adapters. Distilled from live scanner findings and a 48k-star community skill (2026-09).

Keep the surface minimal: the best helper does nothing until explicitly invoked, and nothing harmful when it fails.

After Design: Publishing

When the skill is ready to share on ClawHub/GitHub, use skill-publish to audit and publish. It handles: personal data scanning, frontmatter validation, content cleanup, bilingual enforcement, file separation (local vs published), and dual-platform push.

Failure Handling (for this guide itself)

References (on-demand)

v1.7.1 | Based on Anthropic/OpenAI/LangChain design principles | 2026-09-20

Changelog:

• v1.7.1: Added "Behavior Surface" section (opt-in gating, fail-open hooks, path self-resolution, single source of truth, declaration-behavior match, override section) + hooks/ and evals/ as optional components + undeclared-side-effects anti-pattern. Distilled from the i-have-adhd skill audit and the LP1 scanner findings. (Changelog entries for v1.5.0-v1.7.0 were not kept; the frontmatter version remained authoritative.)
• v1.4.6: Published merged content to the correct slug skill-design-guide-skill — restores 9 metadata.openclaw.tags (discoverability) + 1.4.4 governance-aware checklist / Governance & Continuity checks. (Prior 1.4.5/1.4.6 attempts landed on a stray skill-design-guide slug by mistake; that duplicate should be deleted.)
• v1.4.5: Restored metadata.openclaw.tags (9 discoverability tags) dropped in the 1.4.4 sync; no content change beyond 1.4.4 governance additions
• v1.4.4: Added governance checks for single source of truth, private-data separation, secret scanning, retry/re-run, external-action gates, and persistent task continuity
• v1.4.3: Restored display name "Skill Design Guide"
• v1.4.2: Consolidated reference/ + references/ into a single references/ dir; fixed all reference paths
• v1.4.1: Fixed display name
• v1.4.0: Refactored for progressive disclosure — split checklist/patterns/platform into references/; added Hard Rules + Failure Handling; reduced SKILL.md from 13K to ~5K chars
• v1.3.0: Added usage scenarios, Chinese version (SKILL_zh.md)
• v1.2.0: Platform-agnostic rewrite, added Credits