skill-refiner

# 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 s...

# 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
  ⚠️  Descripti...