Skill: ykaixu/openclaw-skill-reviewer (version 1.0.0)

--- name: skill-reviewer description: Comprehensive skill review and validation. Use when you need to audit an OpenClaw skill for correctness, completeness, and compliance with OpenClaw specifications. Performs three levels of review: (1) Format validation via package_skill.py, (2) Content quality assessment of SKILL.md structure and writing, (3) Functional verification that generated templates/scripts match actual OpenClaw specifications. --- # Skill Reviewer Comprehensive skill review and validation for OpenClaw skills. ## Overview This skill provides a systematic three-level review process to ensure skills are: - **Valid** - Proper structure and format - **Complete** - All required components present - **Correct** - Generated outputs match OpenClaw specifications - **High-quality** - Follows best practices ## Review Workflow ### Level 1: Format Validation Run automatic validation using `package_skill.py`: ```bash python3 /home/yupeng/.npm-global/lib/node_modules/openclaw/skills/skill-creator/scripts/package_skill.py <skill-path> ``` **Checks:** - YAML frontmatter format and required fields - Skill naming conventions and directory structure - Description completeness and quality - File organization and resource references **Outcome:** ✅ Valid or ❌ Validation errors ### Level 2: Content Quality Assessment Manually review SKILL.md for: **Frontmatter:** - `name` is concise and follows naming conventions - `description` is comprehensive and includes "when to use" information - No extraneous fields in YAML **Body Structure:** - Clear organization (workflow-based, task-based, or reference-based) - Progressive disclosure pattern (metadata → SKILL.md → references) - Concise and focused content - Imperative/infinitive form for instructions **Writing Quality:** - No filler or redundant explanations - Concrete examples and realistic scenarios - Clear guidance on when to read reference files - Avoids duplication between SKILL.md and references ### Level 3: Functional Verification **Critical Step** - Verify that generated outputs match actual OpenClaw specifications. **For skills that generate templates:** - Compare generated templates with actual OpenClaw specification files - Example: If skill generates AGENTS.md templates, compare with `/home/yupeng/.openclaw/workspace/AGENTS.md` - Check for missing required sections (session startup, memory workflow, safety rules, group chat etiquette, heartbeat mechanism) - Verify all critical requirements are present **For skills with scripts:** - Test scripts to ensure they work correctly - Verify output matches expected format - Check error handling **For skills with references:** - Verify reference files are accurate and up-to-date - Check that references are properly linked from SKILL.md ### Level 4: Best Practices Check Verify the skill follows OpenClaw skill best practices: **Progressive Disclosure:** - SKILL.md body is concise (<500 lines preferred) - Detailed information moved to references/ - References are properly linked and described **Resource Organization:** - Only necessary resource directories created - No extraneous files (README.md, INSTALLATION_GUIDE.md, etc.) - Scripts/ references/ assets/ used appropriately **Context Efficiency:** - Information lives in either SKILL.md OR references, not both - Essential procedural instructions in SKILL.md - Detailed reference material in references/ **Triggering Accuracy:** - `description` clearly states when the skill should be used - All "when to use" information is in description, not body ## Common Issues Found **Missing Functional Verification:** - Skill generates templates but they don't match actual specifications - Example: AGENTS.md template missing session startup requirements **Incomplete Descriptions:** - Description doesn't include "when to use" information - Body contains "When to Use This Skill" sections (should be in description) **Duplication:** - Same information in both SKILL.md and references - Wastes context window tokens **Extraneous Files:** - README.md, CHANGELOG.md, etc. in skill directory - Should only contain SKILL.md and necessary resources **Poor Progressive Disclosure:** - SKILL.md too verbose - References not properly linked or described ## Review Checklist For each skill, verify: - [ ] Level 1: Format validation passes - [ ] Level 2: SKILL.md structure and quality are good - [ ] Level 3: Generated templates match OpenClaw specifications - [ ] Level 4: Best practices are followed - [ ] No extraneous files - [ ] Description includes "when to use" information - [ ] References are properly linked from SKILL.md - [ ] Scripts work correctly (if present) ## Resources ### scripts/ - `review_skill.py` - Automated review script (optional enhancement) ### references/ - `openclaw-specs.md` - OpenClaw specifications for comparison - `best-practices.md` - Skill design best practices

path: references/best-practices.md
content: # Skill Design Best Practices

Based on skill-creator SKILL.md and OpenClaw conventions.

## Core Principles

### Concise is Key
The context window is a public good. Skills share the context window with everything else.

**Default assumption:** Codex is already very smart. Only add context Codex doesn't already have.

Challenge each piece of information:
- "Does Codex really need this explanation?"
- "Does this paragraph justify its token cost?"

Prefer concise examples over verbose explanations.

### Set Appropriate Degrees of Freedom

Match the level of specificity to the task's fragility and variability:

**High freedom (text-based instructions):**
- Multiple approaches are valid
- Decisions depend on context
- Heuristics guide the approach

**Medium freedom (pseudocode or scripts with parameters):**
- Preferred pattern exists
- Some variation is acceptable
- Configuration affects behavior

**Low freedom (specific scripts, few parameters):**
- Operations are fragile and error-prone
- Consistency is critical
- Specific sequence must be followed

## Progressive Disclosure Design

Skills use a three-level loading system:

1. **Metadata (name + description)** - Always in context (~100 words)
2. **SKILL.md body** - When skill triggers (<5k words)
3. **Bundled resources** - As needed by Codex (Unlimited)

### Progressive Disclosure Patterns

**Pattern 1: High-level guide with references**
Keep SKILL.md body to essentials, link to detailed references:

```markdown
# PDF Processing

## Quick start
Extract text with pdfplumber: [code example]

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md)
- **API reference**: See [REFERENCE.md](REFERENCE.md)
```

**Pattern 2: Domain-specific organization**
Organize by domain to avoid loading irrelevant context:

```
bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md
    ├── sales.md
    ├── product.md
    └── marketing.md
```

**Pattern 3: Conditional details**
Show basic content, link to advanced:

```markdown
# DOCX Processing

## Creating documents
Use docx-js. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents
For simple edits, modify XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
```

### Guidelines

- **Avoid deeply nested references** - Keep references one level deep from SKILL.md
- **Structure longer reference files** - Include table of contents for files >100 lines
- **Keep SKILL.md under 500 lines** - Split content when approaching this limit

## SKILL.md Structure

### Frontmatter (YAML)

Required fields:
- `name`: The skill name
- `description`: Primary triggering mechanism
  - Include both what the skill does AND when to use it
  - Include all "when to use" information here (NOT in body)
  - Example: "Comprehensive document creation, editing, and analysis. Use when Codex needs to work with .docx files for: (1) Creating new documents, (2) Modifying content, (3) Working with tracked changes"

**Do NOT include any other fields in YAML frontmatter.**

### Body

**Writing Guidelines:**
- Always use imperative/infinitive form
- Be concise and focused
- Include concrete examples
- Reference bundled resources clearly

## Resource Organization

### scripts/
Executable code (Python/Bash/etc.) for tasks requiring deterministic reliability.

**When to include:**
- Same code is being rewritten repeatedly
- Deterministic reliability is needed

**Benefits:**
- Token efficient
- Deterministic execution
- May execute without loading into context

### references/
Documentation intended to be loaded as needed into context.

**When to include:**
- Documentation Codex should reference while working
- Database schemas, API documentation, domain knowledge, company policies

**Best practice:**
- If files are large (>10k words), include grep search patterns in SKILL.md
- **Avoid duplication**: Information should live in either SKILL.md OR references, not both

### assets/
Files used in output, not loaded into context.

**When to include:**
- Templates, images, icons, boilerplate code, fonts, sample documents

**Benefits:**
- Separates output resources from documentation
- Enables Codex to use files without loading into context

## What NOT to Include

A skill should only contain essential files. Do NOT create:

- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- etc.

The skill should only contain information needed for an AI agent to do the job at hand.

## Skill Naming

- Use lowercase letters, digits, and hyphens only
- Normalize titles to hyphen-case (e.g., "Plan Mode" -> `plan-mode`)
- Generate names under 64 characters
- Prefer short, verb-led phrases
- Namespace by tool when it improves clarity (e.g., `gh-address-comments`)
- Name skill folder exactly after the skill name

## Common Anti-Patterns

### "When to Use This Skill" in Body
❌ Wrong: Body contains "When to Use This Skill" section
✅ Right: All "when to use" information in description field

### Duplication
❌ Wrong: Same information in both SKILL.md and references
✅ Right: Information lives in one place only

### Verbose SKILL.md
❌ Wrong: SKILL.md body is long and detailed
✅ Right: SKILL.md is concise, details in references

### Extraneous Files
❌ Wrong: README.md, CHANGELOG.md, etc. in skill directory
✅ Right: Only SKILL.md and necessary resources

### Missing Links
❌ Wrong: References exist but not linked from SKILL.md
✅ Right: SKILL.md clearly describes when to read each reference

path: references/openclaw-specs.md
content: # OpenClaw Specifications

This file contains key OpenClaw specifications that skills should reference when generating templates or configurations.

## AGENTS.md Required Sections

### Session Startup
Every AGENTS.md must include session startup requirements:
- Read SOUL.md
- Read USER.md
- Read memory/YYYY-MM-DD.md (today + yesterday)
- Read MEMORY.md (main session only)

### Memory Workflow
- Daily notes: memory/YYYY-MM-DD.md
- Long-term: MEMORY.md (main session only)
- MEMORY.md security: only load in main sessions

### Safety Rules
- Don't exfiltrate private data
- Don't run destructive commands without asking
- Prefer `trash` over `rm`
- Ask before external actions (emails, posts, etc.)

### Group Chat Behavior
- You are a participant, not the user's voice
- Respond when: mentioned, can add value, correcting misinformation
- Stay silent when: casual banter, already answered, would interrupt
- Use emoji reactions naturally
- Avoid triple-tap (multiple responses to same message)

### Heartbeat Mechanism
- Default heartbeat prompt behavior
- Heartbeat vs cron: when to use each
- What to check during heartbeats
- When to reach out vs stay quiet
- Memory maintenance during heartbeats

### Tools
- Skills provide tools
- Voice storytelling capabilities
- Platform formatting rules (Discord/WhatsApp)

## SOUL.md Required Sections

### Core Truths
- Be genuinely helpful, not performatively helpful
- Have opinions
- Be resourceful before asking
- Earn trust through competence
- Remember you're a guest

### Boundaries
- Private things stay private
- Ask before external actions
- Never send half-baked replies
- Not the user's voice in groups

### Vibe
- How to come across
- Concise when needed, thorough when matters

## IDENTITY.md Required Fields

- Name
- Creature (type of being)
- Vibe (how you come across)
- Emoji (signature)
- Avatar (optional)

## USER.md Required Fields

- Name
- What to call them
- Pronouns (optional)
- Timezone
- Notes (context, preferences)

## HEARTBEAT.md Guidelines

- Keep extremely short
- If effectively empty, can skip heartbeat runs
- Add 1-5 short checklist items when needed
- Heartbeats burn tokens; enable only when trusted

## BOOTSTRAP.md

- One-time first-run ritual
- Follow it, figure out who you are, then delete it
- Contains birth certificate for new agents

## Memory Files

### memory/YYYY-MM-DD.md
- Raw logs of what happened
- Create memory/ directory if needed
- Capture decisions, context, things to remember

### MEMORY.md
- Curated long-term memory
- Only load in main sessions
- DO NOT load in shared contexts
- Contains personal context that shouldn't leak
- Write significant events, thoughts, decisions, opinions, lessons learned

Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)