skill-refiner

审核并修复工作区中的所有技能，以符合技能创建者的要求。当被要求“改进技能”、“审核技能”、“检查技能质量”或“修复不合规技能”时使用。彻底搜索整个工作区（不仅仅是技能/）以找到每一个 SKILL.md，然后审核和修复每一个。

# 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)

---

## 中文说明

# Skill Refiner

查找工作区中的每一个技能，根据 skill-creator 的要求逐一审核，并修复不合规的技能。

## 工作流程

### 第 1 步 —— 发现所有技能

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

这会在**整个工作区**中搜索 `SKILL.md` 文件（而不仅仅是 `skills/`）。未遵循 skill-creator 约定创建的技能可能出现在任何位置。

### 第 2 步 —— 审核每个技能

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

返回包含以下内容的 JSON：
- `issues` —— 必须修复的阻塞性问题
- `warnings` —— 建议性的改进项
- `compliant` —— 仅当 issues 为空时才为 true

对第 1 步返回的每个路径运行此命令。批量示例：

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

### 第 3 步 —— 汇报结果

用表格汇总结果：

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

### 第 4 步 —— 修复不合规的技能

对于每个存在问题的技能，按以下顺序修复：

1. **缺失/格式错误的 frontmatter** —— 添加或修正仅包含 `name` 和 `description` 的 `---` 块
2. **多余的 frontmatter 字段** —— 移除 `name` 和 `description` 以外的任何字段
3. **薄弱的 description** —— 重写以包含：技能的功能 + 触发条件（“Use when...”）
4. **无关的文件** —— 删除 README.md、INSTALLATION_GUIDE.md、CHANGELOG.md 等
5. **错误的位置** —— 如果技能位于 `skills/` 之外，将其移动到 `~/.openclaw/workspace/skills/<skill-name>/`
6. **命名违规** —— 将目录重命名为小写连字符格式（lowercase-hyphen-case）

对于警告（建议性）：
- 过长的 SKILL.md（>500 行）：将详细内容提取到 `references/` 文件中，并从 SKILL.md 链接过去
- 未链接的 references：在 SKILL.md 正文中添加链接
- 薄弱的 description：改进触发措辞

### 第 5 步 —— 验证修复

对每个已修复的技能重新运行 `audit_skill.py`，确认 `"compliant": true`。

可选地用以下命令打包：
```bash
python3 /opt/homebrew/lib/node_modules/openclaw/skills/skill-creator/scripts/package_skill.py <skill-dir>
```

## 合规检查清单

合规的技能必须具备：
- [ ] 位于命名目录根部的 `SKILL.md`
- [ ] YAML frontmatter 恰好包含 `name` 和 `description`（无其他字段）
- [ ] `description` 同时包含技能的功能以及触发时机
- [ ] 目录名：仅包含小写字母、数字、连字符；≤64 字符
- [ ] 无无关文件（README.md、CHANGELOG.md 等）
- [ ] 资源仅放在 `scripts/`、`references/` 或 `assets/` 中
- [ ] 所有 `references/` 文件均从 SKILL.md 正文链接
- [ ] SKILL.md 正文 ≤500 行（更长则拆分到 references/）