skill-design-guide

Complete methodology for designing, testing, and quality-checking OpenClaw Skills.

OpenClaw Skill — works with OpenClaw AI agents

What It Does

A meta-skill that guides AI agents through the full lifecycle of Skill development: from initial design and trigger scenario definition, through implementation and testing, to quality inspection and publishing. Distilled from hands-on experience building 16+ production Skills. Includes an automated linter (skill_lint.py) for structural validation.

Quick Start

# Install via ClawHub (recommended)
openclaw skill install skill-design-guide

# Or clone this repo
git clone https://github.com/rrrrrredy/skill-design-guide.git ~/.openclaw/skills/skill-design-guide

Key Concepts

• Skill = runtime context container, not documentation
• 4 lifecycle stages: static scan (description only) → dynamic injection (full SKILL.md) → execution (ReAct loop) → fold & forget
• SKILL.md rules decay as conversation progresses — hard constraints belong in system prompt

Features

• Design principles: Trigger-first design, token budget management, description as routing
• Quality checklist: 12-point inspection covering structure, content, safety, and compliance
• Automated linter: skill_lint.py validates SKILL.md structure, version consistency, line count
• Common gotchas catalog: Collected pitfalls from 16+ Skill development cycles
• Testing methodology: Trigger word testing, execution path verification, fallback validation

Usage

Trigger phrases:

• "新建 skill"、"设计 skill"、"skill 质检"
• "评审 skill"、"skill 设计原则"、"创建 skill"
• "skill 最佳实践"、"skill review"、"skill lint"

Project Structure

skill-design-guide/
├── SKILL.md                          # Main skill definition & workflow
├── scripts/
│   └── skill_lint.py                 # Automated SKILL.md linter
├── references/
│   ├── design-principles.md          # Core design principles (detailed)
│   ├── quality-checklist.md          # 12-point QA checklist
│   ├── common-gotchas.md             # Known pitfalls & solutions
│   └── testing-guide.md              # Testing methodology
└── .gitignore

Requirements

• OpenClaw agent runtime
• Python 3 (for skill_lint.py)

License

MIT