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)

| Tool | Purpose | |------|---------| | skill-creator | HOW to structure a SKILL.md file | | THIS GUIDE | WHY behind design decisions — Workflow vs Agent, which pattern |

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

✅ 3 Usage Modes

| Mode | Trigger | Output | |------|---------|--------| | New Design | "I want to build a X] skill" | Architecture blueprint (pattern + structure) | | Skill Review | "Review this skill" / "Check quality" | Report via checklist | | Pattern Selection | "Should I use X or Y?" | Pattern recommendation with rationale |

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

| Layer | Role | File | |-------|------|------| | Brain | Decision logic, workflow definition | SKILL.md | | Hands | Deterministic execution | scripts/ | | Session | Knowledge base, config, templates | references/, assets/ |

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

Step 1: Workflow or Agent?

One question: Are the task steps predetermined?

| Type | When | |------|------| | Workflow | Steps are clear and predictable → choose this (faster, cheaper, debuggable) | | Agent | Steps uncertain, need dynamic planning → choose this (flexible but costly) |

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.

| Pattern | Best For | |---------|----------| | Prompt Chaining | Sequential steps with checkpoints | | Routing | Clear input types → different paths | | Parallelization | Independent subtasks | | Orchestrator-Workers | Unpredictable subtasks (sparingly!) | | Evaluator-Optimizer | Generate→Evaluate→Repeat until pass |

Step 3: Skill Structure

Required

| Component | Content | |-----------|---------| | SKILL.md | YAML frontmatter (name, description, read_when) + workflow + Hard Rules + Failure Handling + Output Format |

Optional

| Component | When | |-----------|------| | references/ | Domain knowledge (loaded on demand) | | scripts/ | Deterministic steps | | assets/ | Templates, configs |

SKILL.md Template

yaml
---
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 ✓ | Observability ✓

Anti-Patterns

| Anti-Pattern | Fix | |-------------|------| | Over-engineering | Start with single SKILL.md | | Full preload | Load references on-demand only | | God Skill | Split duties — one skill, one thing | | All-LLM | Scripts for deterministic steps | | No guardrails | Add Hard Rules + Failure Handling | | Vague output | Define exact format and fields | | Publishing dirty | Before publishing, run skill-publish to audit and clean |

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)

| Scenario | Action | |----------|--------| | User asks for code, not design | Redirect to skill-creator | | Pattern comparison ambiguous | Load references/pattern-details.md | | Review request without skill details | Ask: "Show me your SKILL.md or describe what the skill does" | | User wants to publish a completed skill | Redirect to skill-publish |

References (on-demand)

| Need | Load | |------|------| | 25-point checklist | references/quality-checklist.md | | Pattern deep dive | references/pattern-details.md | | Platform-specific config | references/platform-compatibility.md | | Industry research background | references/agent-design-research.md | | Anthropic tool design | references/anthropic-tool-design.md | | Publishing to ClawHub/GitHub | Use skill-publish (separate skill) |

v1.4.6 | Based on Anthropic/OpenAI/LangChain design principles | 2026-08-02

Changelog:

• 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