skill-refiner

Original source / Raw SKILL.md

---
name: skill-refiner
description: Audit and fix all skills in the workspace for compliance with skill-creator requirements. Use when asked to "refine skills", "audit skills", "check skill quality", or "fix non-compliant skills". Exhaustively searches the entire workspace (not just skills/) to find every SKILL.md, then audits and repairs each one.
---

# Skill Refiner

Finds every skill in the workspace, audits each against skill-creator requirements, and fixes non-compliant ones.

## Workflow

### Step 1 — Discover all skills

```bash
bash scripts/find_skills.sh [workspace_dir]
```

This searches the **entire workspace** for `SKILL.md` files (not just `skills/`). Skills created without following skill-creator conventions may end up anywhere.

### Step 2 — Audit each skill

```bash
python3 scripts/audit_skill.py <skill-dir>
```

Returns JSON with:
- `issues` — blocking problems that must be fixed
- `warnings` — advisory improvements
- `compliant` — true only when issues is empty

Run this on every path returned by Step 1. Batch example:

```bash
bash scripts/find_skills.sh | while read dir; do
  python3 scripts/audit_skill.py "$dir"
done
```

### Step 3 — Report findings

Summarize results in a table:

| Skill | Location | Issues | Warnings | Status |
|-------|----------|--------|----------|--------|
| my-skill | skills/my-skill | 0 | 1 | ⚠️ |
| bad-skill | temp/bad-skill | 2 | 0 | ❌ |

### Step 4 — Fix non-compliant skills

For each skill with issues, fix in this order:

1. **Missing/malformed frontmatter** — Add or correct the `---` block with `name` and `description` only
2. **Extra frontmatter fields** — Remove any fields other than `name` and `description`
3. **Weak description** — Rewrite to include: what the skill does + trigger conditions ("Use when...")
4. **Extraneous files** — Delete README.md, INSTALLATION_GUIDE.md, CHANGELOG.md, etc.
5. **Wrong location** — If a skill is outside `skills/`, move it to `~/.openclaw/workspace/skills/<skill-name>/`
6. **Naming violations** — Rename directory to lowercase-hyphen-case

For warnings (advisory):
- Long SKILL.md (>500 lines): extract detailed content into `references/` files and link from SKILL.md
- Unlinked references: add links in SKILL.md body
- Weak description: improve trigger language

### Step 5 — Validate fixes

Re-run `audit_skill.py` on each fixed skill to confirm `"compliant": true`.

Optionally package with:
```bash
python3 /opt/homebrew/lib/node_modules/openclaw/skills/skill-creator/scripts/package_skill.py <skill-dir>
```

## Compliance Checklist

A compliant skill must have:
- [ ] `SKILL.md` at the root of a named directory
- [ ] YAML frontmatter with exactly `name` and `description` (no other fields)
- [ ] `description` includes what the skill does AND when to trigger it
- [ ] Directory name: lowercase letters, digits, hyphens only; ≤64 chars
- [ ] No extraneous files (README.md, CHANGELOG.md, etc.)
- [ ] Resources only in `scripts/`, `references/`, or `assets/`
- [ ] All `references/` files linked from SKILL.md body
- [ ] SKILL.md body ≤500 lines (split into references/ if longer)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/find_skills.sh

```bash
#!/bin/bash
# Find all skill directories in the workspace.
# Searches for SKILL.md files anywhere in the workspace tree.
# Usage: find_skills.sh [workspace_dir]
# Output: one skill directory path per line

WORKSPACE="${1:-$HOME/.openclaw/workspace}"

find "$WORKSPACE" \
  -name "SKILL.md" \
  -not -path "*/node_modules/*" \
  -not -path "*/.git/*" \
  | while read -r skill_md; do
      dirname "$skill_md"
    done \
  | sort -u

```

### scripts/audit_skill.py

```python
#!/usr/bin/env python3
"""
Audit a skill directory for compliance with skill-creator requirements.
Usage: audit_skill.py <skill-dir>
Output: JSON with issues (blocking) and warnings (advisory)
"""

import sys
import re
import json
from pathlib import Path


EXTRANEOUS_FILES = {
    'README.md', 'INSTALLATION_GUIDE.md', 'QUICK_REFERENCE.md',
    'CHANGELOG.md', 'INSTALL.md', 'SETUP.md', 'CONTRIBUTING.md',
}
ALLOWED_SUBDIRS = {'scripts', 'references', 'assets', 'locales', 'docs'}
TRIGGER_KEYWORDS = ['use when', 'trigger', 'when to use', 'activate when', 'use for', 'when user', 'when asked']


def audit_skill(skill_dir: str) -> dict:
    path = Path(skill_dir)

    if not path.is_dir():
        return {"skill_dir": skill_dir, "error": "Not a directory", "issues": [], "warnings": [], "compliant": False}

    issues = []
    warnings = []
    skill_md = path / "SKILL.md"

    # 1. SKILL.md must exist
    if not skill_md.exists():
        return {"skill_dir": skill_dir, "skill_name": path.name, "issues": ["SKILL.md not found"], "warnings": [], "compliant": False}

    content = skill_md.read_text(encoding='utf-8')
    lines = content.splitlines()

    # 2. YAML frontmatter
    if not content.startswith('---'):
        issues.append("Missing YAML frontmatter (must start with ---)")
    else:
        end = content.find('\n---', 3)
        if end == -1:
            issues.append("Malformed YAML frontmatter (no closing ---)")
        else:
            fm = content[3:end].strip()

            has_name = bool(re.search(r'^name:\s*\S', fm, re.MULTILINE))
            has_desc = bool(re.search(r'^description:\s*\S', fm, re.MULTILINE))

            if not has_name:
                issues.append("Frontmatter missing required field: 'name'")
            if not has_desc:
                issues.append("Frontmatter missing required field: 'description'")

            # No extra fields allowed
            field_names = re.findall(r'^([a-zA-Z_]+)\s*:', fm, re.MULTILINE)
            extra = set(field_names) - {'name', 'description'}
            if extra:
                issues.append(f"Frontmatter has extra fields (only name+description allowed): {', '.join(sorted(extra))}")

            # Description quality: should mention when to use
            if has_desc:
                desc_block = re.search(r'^description:\s*(?:\|[-]?\s*\n)?([\s\S]+?)(?=\n[a-zA-Z_]+\s*:|$)', fm, re.MULTILINE)
                if desc_block:
                    desc_text = desc_block.group(1).strip().lower()
                    # Strip YAML block scalar indent
                    desc_text = re.sub(r'\n\s+', ' ', desc_text)
                    if not any(kw in desc_text for kw in TRIGGER_KEYWORDS):
                        warnings.append("Description doesn't clearly state trigger conditions (add 'Use when...' or similar)")
                    if len(desc_text) < 60:
                        warnings.append(f"Description is very short ({len(desc_text)} chars) — should be comprehensive for reliable triggering")

    # 3. Naming convention
    name = path.name
    if not re.match(r'^[a-z0-9][a-z0-9-]*$', name):
        issues.append(f"Directory name '{name}' violates convention (lowercase letters, digits, hyphens only; no leading hyphen)")
    if len(name) > 64:
        issues.append(f"Directory name too long ({len(name)} chars, max 64)")

    # 4. Extraneous files
    for fname in EXTRANEOUS_FILES:
        if (path / fname).exists():
            issues.append(f"Extraneous file: {fname} (remove — skills should not contain auxiliary docs)")

    # 5. Unexpected subdirectories
    for item in path.iterdir():
        if item.is_dir() and not item.name.startswith('.') and item.name not in ALLOWED_SUBDIRS:
            warnings.append(f"Unexpected subdirectory: {item.name}/ (allowed: scripts/, references/, assets/)")

    # 6. SKILL.md length
    if len(lines) > 500:
        warnings.append(f"SKILL.md is {len(lines)} lines — consider splitting into references/ files (recommended max: 500)")

    # 7. References linked from SKILL.md
    refs_dir = path / 'references'
    if refs_dir.exists():
        for ref in refs_dir.iterdir():
            if ref.is_file() and ref.name not in content:
                warnings.append(f"references/{ref.name} is not linked from SKILL.md")

    return {
        "skill_dir": str(path.resolve()),
        "skill_name": name,
        "issues": issues,
        "warnings": warnings,
        "compliant": len(issues) == 0,
    }


if __name__ == '__main__':
    if len(sys.argv) < 2:
        print("Usage: audit_skill.py <skill-dir>", file=sys.stderr)
        sys.exit(1)
    print(json.dumps(audit_skill(sys.argv[1]), indent=2))

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# skill-refiner

Audit and fix [OpenClaw](https://github.com/openclaw/openclaw) agent skills for [skill-creator](https://github.com/openclaw/openclaw/tree/main/skills/skill-creator) compliance.

[中文文档](./README.zh.md)

## Why?

OpenClaw skills need to follow specific conventions to be properly discovered and triggered. Common issues include:

- Missing or malformed YAML frontmatter
- Extra frontmatter fields (only `name` and `description` allowed)
- Extraneous files (README.md, CHANGELOG.md in skill directories)
- Weak descriptions that don't specify trigger conditions

This tool finds all skills in your workspace and reports compliance issues.

## Quick Start

```bash
# Scan your OpenClaw workspace
npx skill-refiner

# Scan a specific directory
npx skill-refiner /path/to/workspace
```

## Installation

### As an OpenClaw Skill

```bash
clawhub install skill-refiner
```

Then ask your agent: "audit my skills" or "check skill compliance"

### Global CLI

```bash
npm install -g skill-refiner
skill-refiner ~/.openclaw/workspace
```

## What It Checks

| Check | Severity | Description |
|-------|----------|-------------|
| SKILL.md exists | 🔴 Issue | Every skill needs a SKILL.md |
| YAML frontmatter | 🔴 Issue | Must start with `---` block |
| Required fields | 🔴 Issue | `name` and `description` required |
| Extra fields | 🔴 Issue | Only `name` + `description` allowed |
| Extraneous files | 🔴 Issue | No README.md, CHANGELOG.md, etc. |
| Naming convention | 🔴 Issue | lowercase-hyphen-case, ≤64 chars |
| Trigger conditions | 🟡 Warning | Description should include "Use when..." |
| SKILL.md length | 🟡 Warning | Recommended max 500 lines |
| Unlinked references | 🟡 Warning | Files in references/ should be linked |

## Output Example

```
🔍 skill-refiner — scanning: /Users/me/.openclaw/workspace

✅ markdown-converter
✅ weather
❌ my-broken-skill
  ✗  Frontmatter has extra fields: metadata, author
  ✗  Extraneous file: README.md
⚠️ another-skill
  ⚠️  Description doesn't clearly state trigger conditions

─────────────────────────────────
Total: 4  ✅ 2  ❌ 1  ⚠️ 1
```

## Programmatic Usage

```bash
# Find all skills
bash scripts/find_skills.sh /path/to/workspace

# Audit a single skill (returns JSON)
python3 scripts/audit_skill.py /path/to/skill-dir
```

## License

MIT

```

### _meta.json

```json
{
  "owner": "1va7",
  "slug": "skill-refiner",
  "displayName": "skill-refiner",
  "latest": {
    "version": "1.0.0",
    "publishedAt": 1771558869156,
    "commit": "https://github.com/openclaw/skills/commit/fbdab895e2fddd46c1581a67f54c2fa0dc82f2ed"
  },
  "history": []
}

```