skill-maintenance维护技能库整洁，系统性整理、归类、查重、清理废弃技能（含项目源码误入 skills/ 目录的情况），**以及在 install 前对 skill 做安全审计（调用 skillspector）**。**新能力（v2.2）**：对指定 skill 进行合规/规范检查（YAML frontmatter / description 规范 / 多余文件 / 目录结构），并与 viceroy-skills 云端同名 skill 比对，**自动三向 merge**，保证本地和云端都是最新文件。**新能力（v2.7）**：分析技能使用情况——直接查询 SQLite 数据库 session 历史，区分「mtime 活跃」和「实际被调用过」。触发词：「检查 skill 规范」「合规检查」「跟云端比对」「merge skill」「…
Independent GitHub snapshot · Automated classification · Original documentation governs
按 viceroy-skills 仓库的 6 分类标准维护本地技能库，识别重复/低频/废弃技能，保持 6 大分类整洁有序。配套 skill-github-sync 形成"本地整理 → 推到 GitHub"闭环。
v2.1（2026-06-21 升级）：新增第 7 节「安装前安全审计」—— 在 install 新 skill 之前，自动调用 skillspector 做 64 pattern / 16 分类的静态扫描 + 风险分评估，避免装入含 prompt injection / data exfiltration / supply chain attack 的恶意 skill。
v2.2（2026-06-28 升级）：新增第 8 节「合规检查 + 云端 merge」—— 对指定 skill 进行规范审计（YAML / description / 文件结构），与 viceroy-skills 云端同名 skill 三向 merge，保证本地和 GitHub 两端文件同步最新。
| 英文分类 | 中文 | 用途 | 路径前缀 |
|---|---|---|---|
ai | AI模型 | LLM/agent runtime | ~/.openclaw/skills/ai/ |
assistant | 助理 | 通用工具/笔记/存储/陪伴 | ~/.openclaw/skills/assistant/ |
creative | 创意 | 写作/排版/设计/视频 | ~/.openclaw/skills/creative/ |
developer | 开发 | 工程化/调试/部署/skill 自身工具 | ~/.openclaw/skills/developer/ |
operations | 运营 | 数据采集/SEO/GitHub 项目雷达 | ~/.openclaw/skills/operations/ |
product | 产品 | 调研/分析/竞品/标签打分 | ~/.openclaw/skills/product/ |
铁律：
OpenClaw 加载 skill 时按以下顺序，高优先级覆盖低优先级同名 skill：
| # | 来源 | 路径 | 可见性 |
|---|---|---|---|
| 1 | Workspace skills | <workspace>/skills | 仅该 agent |
| 2 | Project agent skills | <workspace>/.agents/skills | 仅该工作区 agent |
| 3 | Personal agent skills | ~/.agents/skills | 全机器所有 agent |
| 4 | Managed/local skills | ~/.openclaw/skills | 全机器所有 agent |
| 5 | Bundled skills | 安装自带 | 全机器所有 agent |
| 6 | Extra dirs | skills.load.extraDirs | 全机器所有 agent |
维护原则：
~/.openclaw/skills/<cat>/），让所有 agent 共享按顺序执行：
盘点所有 skill：
# 系统级（含嵌套分类目录）
find ~/.openclaw/skills -name "SKILL.md" -type f
# 工作区（试装区）
find ~/.openclaw/workspace/skills -name "SKILL.md" -type f 2>/dev/null
# 内置
find ~/.hermes/skills -name "SKILL.md" -type f 2>/dev/null
识别非 skill 项（关键！实战中最常踩坑）：
~/.openclaw/workspace/projects/<name>/skills/developer/ 是 skill，但 5-27 误建时把 skill-maintenance 嵌进去形成空顶层）→ 整目录审计识别重复 / 旧版：
~/.openclaw/skills/developer/skill-maintenance/ 和 ~/.openclaw/skills/skill-maintenance/）→ 留新删旧，对比 mtime 或仓库引用jacardl/skillshub → jacardl/viceroy-skills）→ 必删归类新 skill：对照 6 分类表，关键词匹配：
operations/assistant/product/creative/developer/ai/检查空目录 stub：
find ~/.openclaw/skills -maxdepth 2 -name "DESCRIPTION.md" | while read f; do
dir=$(dirname "$f")
[ ! -f "$dir/SKILL.md" ] && echo "STUB: $dir"
done
验证关键引用：例如 zhiligithub 引用 zhili-publish/scripts/publish_zhili.py，分类嵌套后路径变成 skills/creative/zhili-publish/scripts/ —— 跑一次 publish_zhili.py --help 验证
满足以下任一条件建议清理（删除前必须向用户确认）：
| 条件 | 处理方式 |
|---|---|
| 与现有 skill 功能完全重复（描述重叠 >70%） | 删旧留新（或合并） |
| 长期未使用（边缘领域如音乐/游戏/家居控制） | 删 |
| 依赖的外部服务已失效 | 删 |
| 描述过时且无法修复 | 删 |
| 旧版（指向已废弃仓库） | 删 |
| 嵌套在错误位置的空顶层目录 | 删整目录 |
| 项目源码误入 skills/ | 移到 ~/.openclaw/workspace/projects/ 或 ~/.openclaw/workspace/<name>/ |
zhili-publish → creative/（内容生产）zhiligithub → operations/（GitHub 项目雷达，类比 github-daily-trending）zhilicomments → creative/（短评）assistant/developer/执行前必须：
/tmp/skill-mv-backup/ 或 ~/.openclaw/workspace/.backup-pre-skill-cleanup/mv（不要用 rm —— mv 至少可逆；SOUL.md 红线："trash > rm"）--help 或最简单命令维护完成后输出：
问题：同一 skill 在 3 个位置同时存在（内容完全相同）—— openclaw/skills/{name}/、openclaw/workspace/skills/{name}/、openclaw/skills/{cat}/{name}/。常见于法律类 skill 批量安装后。
检测脚本：
#!/usr/bin/env python3
"""检测 triplicate skills（三处重复的 skill）"""
import os
from pathlib import Path
def scan_all(base):
results = {}
for root, dirs, files in os.walk(base):
if 'SKILL.md' not in files: continue
rel = Path(root).relative_to(base)
results[str(rel)] = str(root)
return results
oc_sys = scan_all(Path.home() / ".openclaw/skills")
oc_ws = scan_all(Path.home() / ".openclaw/workspace/skills")
cats_map = {}
top_level = []
for k, v in oc_sys.items():
parts = k.split('/')
if len(parts) == 1:
top_level.append(k)
else:
cat = parts[0]
name = '/'.join(parts[1:])
cats_map.setdefault(cat, {})[name] = k
ws_names = {}
for k, v in oc_ws.items():
parts = k.split('/')
name = parts[0]
ws_names[name] = k
# 检测 triplicate
for cat, skills in cats_map.items():
if cat == 'legal-skills-chinese':
for name, cat_path in skills.items():
top_path = Path.home() / ".openclaw/skills" / name
ws_path = Path.home() / ".openclaw/workspace/skills" / cat / name
locations = []
if top_path.exists(): locations.append("top-level")
if ws_path.exists(): locations.append("workspace/" + cat)
if len(locations) >= 2:
print(f"TRIPLICATE: {name} in {locations}")
清理原则：
openclaw/skills/legal-skills-chinese/{name}/ — 保留（已归类）openclaw/skills/{name}/ — 删除（顶层重复）openclaw/workspace/skills/legal-skills-chinese/{name}/ — 删除（试装区过期）实战案例（2026-07-03）：35 个法律技能 triplicate，同时存在于顶层 + legal-skills-chinese 分类 + workspace 三处。清理后系统级从 87 → 51 个。
skill-maintenance 不止是本地整理，最终目的是跟 viceroy-skills 仓库同步：
本地整理（skill-maintenance）→ 跟 GitHub 对照 → 推差异（skill-github-sync）
↑ |
└──────────────── 验证一致性 ←─────────────────────┘
联动步骤：
skill-maintenance 整理完本地结构skill-github-sync 拉取 GitHub 端最新 skill 列表skill-github-sync 推本地独有 + 有价值的 skill核心原则：装新 skill 之前必须先用 skillspector 扫一遍。skill 装到系统级后就默认 agent 全部信任它 —— 一旦含 prompt injection / data exfiltration / 提权代码，影响范围是全机器所有 agent。
| 场景 | 用户可能的表达 | 动作 |
|---|---|---|
| install 前 | "我要装 X，先扫一下" / "scan https://github.com/xxx/skill" | 强制先 scan，风险分 > MEDIUM 需用户确认 |
| 合规检查 + 云端 merge | "检查 skill 规范" / "合规检查 X" / "跟云端比对" / "merge skill" / "同步 skill 到云端" / "检查并更新 skill" | 第 8 节三向 merge |
| 已装 skill 体检 | "扫一下 skill-maintenance" / "audit my skills" | 跑 scan，按风险分排序 |
| 批量体检 | "把 ~/.openclaw/skills/ 全扫一遍" | 跑下面 7.4 的批量命令 |
| 看报告 | "显示上次扫描的 json 报告" | 用 --format json 重跑指定 skill |
铁律：install 类操作（clone 到 skills/、推送 GitHub、覆盖 SKILL.md）必须在 scan 通过后执行。HIGH/CRITICAL 风险的 skill 不装，MEDIUM 风险的 skill 列 issues 让用户决定。
~/.openclaw/skills/developer/skillspector/（同级）/tmp/skillspector-probe/SkillSpector/.venv/bin/skillspector（NVIDIA SkillSpector v2.2.3）| Risk Score | Severity | 含义 | 建议 |
|---|---|---|---|
| 0-19 | LOW | 安全 | 直接装 |
| 20-49 | MEDIUM | 提示 | 看 issues 列表，人工 review 后再装 |
| 50-79 | HIGH | 警告 | 必须人工 review 全部 issues 后再装 |
| 80-100 | CRITICAL | 危险 | 不装，告警用户 |
⚠️ 误报注意：很多合法 skill 会被标 MEDIUM（典型如 "External Transmission" 因为 skill 文档里有 API URL，或 "File System Enumeration" 因为 skill 需要读 ~/.openclaw/）。真问题要看 HIGH/CRITICAL + Confidence ≥ 70% 的 issue。
permissions 字段skillspector 对本地网关调用和** shell 工具脚本会持续报 HIGH，即使加了 --no-llm 也无法消除。这类不是漏洞，是设计行为。标准响应是在 YAML frontmatter 中声明 permissions 字段**，让 skillspector 知道这是已知的合法能力。
典型误报场景：
| Pattern ID | Pattern Name | 触发原因 | 是误报的条件 |
|---|---|---|---|
| SC2 | External Transmission | curl HTTP 请求 | 目标地址是 127.0.0.1 或 localhost（本地网关） |
| LP3 | Shell Script Presence | 存在 .sh 脚本文件 | 脚本只含 curl / base64 / jq 等系统工具，无外部脚本下载 |
| LP1 | Tool Spawning | skill 调用 shell 脚本 | 脚本是静态工具（本地网关调用），非动态恶意代码 |
| E1 | Excessive File Access | 访问 ~/.hermes/ 或 ~/.openclaw/ | skill 自身配置文件，属于正常工作范围 |
判断流程：
127.0.0.1 / localhost → 误报，加 permissionsapi.openai.com 等）→ 核查是否 skill 自身必需调用permissions 后重扫仍有残留 HIGH → 标注为已知设计行为，在审计报告中说明，跳过该 skillpermissions 字段格式（加在 YAML frontmatter，与 name/description 同级）：
---
name: example-skill
description: "描述（description 值含中文/冒号/括号必须用双引号包裹）"
permissions:
- http://127.0.0.1:20128/ # 9Router 本地网关调用
- http://localhost/ # 本地服务调用
- filesystem:read:~/.openclaw/ # OpenClaw 配置读取
- filesystem:read:~/.hermes/ # Hermes 配置读取
---
实战案例（9router-image，2026-06-28）：
curl 127.0.0.1:20128）permissions: - http://127.0.0.1:20128/ 后重扫：仍有 4× SC2 HIGHpermissions 字段告知安装者该 skill 需要这些权限，但不改变 skillspector 静态扫描结果；静态分析无法理解运行时上下文，必然对本地网关调用报警permissions 字段的作用是消除后续安装警告，让 skill 作者对已知能力负责；skillspector 扫描本身保持原样⚠️ N HIGH (known design: local gateway curl + shell script)，skill 可正常安装注意：description 值含特殊字符时必须用双引号包裹，否则 YAML 解析器会警告：
（） → 必须加 "..." 包裹: → 冒号后有空格时无需引号，但冒号紧跟文字时需要\ → 在 YAML 双引号字符串中必须写成 \\定期（如每月 / 装完一波新 skill 后）跑一次，扫整个 skills/ 目录：
SS=/tmp/skillspector-probe/SkillSpector/.venv/bin/skillspector
# 批量扫描：所有系统级 skill
for d in ~/.openclaw/skills/*/*/; do
[ -d "$d" ] || continue
skill_name=$(basename "$d")
# 跳过 skillspector 自己（避免循环）
[ "$skill_name" = "skillspector" ] && continue
# 跳过软链
[ -L "$d" ] && continue
# 只扫有 SKILL.md 的
[ -f "$d/SKILL.md" ] || continue
echo "=== $skill_name ==="
$SS scan "$d" --no-llm --format terminal 2>&1 | grep -E '(Risk Score|Severity|CRITICAL|HIGH)' | head -10
echo
done
输出排序建议：把扫描结果按风险分倒序排列，先处理 CRITICAL > HIGH > MEDIUM。
# 扫描单个 skill（装前必跑）
SS=/tmp/skillspector-probe/SkillSpector/.venv/bin/skillspector
$SS scan <path-or-git-url> --no-llm --format terminal
# JSON 报告（机器可读）
$SS scan <path> --no-llm --format json --output /tmp/scan-report.json
# Markdown 报告（贴飞书/Notion）
$SS scan <path> --no-llm --format markdown --output /tmp/scan-report.md
# SARIF 报告（GitHub Code Scanning 集成）
$SS scan <path> --no-llm --format sarif --output /tmp/scan.sarif
--no-llm 跳过 LLM 语义分析（快、准、免 API key）。有 LLM key 想去掉 --no-llm 改用：
SKILLSPECTOR_PROVIDER=openai + OPENAI_API_KEYSKILLSPECTOR_PROVIDER=anthropic + ANTHROPIC_API_KEYSKILLSPECTOR_PROVIDER=nv_inference + NVIDIA_INFERENCE_KEY当用户要求对指定 skill 做合规/规范检查并与云端同步时，执行以下流程。
输入：用户指定 cat/skill（如 operations/radar-daily-report）
⚠️ 凭证文件保护规则（硬性约束）
以下文件在 merge 时永远使用 CLOUD 版本（不覆盖 LOCAL 的云端脱敏版）：
APPID、APPSECRET、access_token、API_KEY 字面量的 .md / .py / .json / .yaml / .txt 文件config、credentials、secret、token 的文件判断标准：LOCAL 有真实凭证（32+ 字符的 hex/base64，或 wx 开头的 16 位十六进制 appid 搭配明文 secret）vs CLOUD 只有 ***REDACTED*** 占位符。
操作：在 merge 前对这些文件单独做 git checkout HEAD -- <file>，保留云端脱敏版，不做任何合并。
Step 0：凭证预检（必须先做）
import re
from pathlib import Path
CRED_PATTERNS = [
r"['\"][0-9a-f]{32,}['\"]", # 32+ hex (APPSECRET)
r"['\"][A-Za-z0-9+/]{40,}={0,2}['\"]", # 40+ base64
r"wx[0-9a-f]{16}", # WeChat APPID
]
def has_real_credential(path: Path) -> bool:
"""检查文件是否含真实凭证（非占位符）"""
content = path.read_text()
redacted = "***REDACTED***" in content or "REDACTED" in content
for pat in CRED_PATTERNS:
hits = re.findall(pat, content, re.I)
for line in content.split('\n'):
for hit in hits:
if hit in line and not line.strip().startswith('#'):
return True # 真实凭证
return False
def scan_for_real_creds(local_dir: Path) -> list[Path]:
"""扫描 skill 目录下所有含真实凭证的文件"""
flagged = []
for f in local_dir.rglob("*"):
if f.is_file() and f.suffix in ['.md', '.py', '.json', '.yaml', '.txt']:
try:
if has_real_credential(f):
flagged.append(f)
except:
pass
return flagged
预检结果解读：
| 场景 | 处置 |
|---|---|
| LOCAL 无凭证文件 | 正常 merge |
| LOCAL 有凭证，CLOUD 有脱敏版 | 保留 CLOUD 脱敏版，不 merge 该文件 |
| LOCAL 有凭证，CLOUD 无此文件 | 凭证文件不 merge（用户需自行处理本地凭证） |
| CLOUD 有凭证（不应该） | 警告，阻断 merge，提示用户 |
Step 1：收集三方文件
import urllib.request, subprocess, json, base64
from pathlib import Path
TOKEN = open("~/.hermes/keys/github_token.txt").read().strip()
REPO = "/tmp/viceroy-skills_sync"
# LOCAL
local_text = Path("~/.openclaw/skills/{cat}/{skill}/SKILL.md").expanduser().read_text()
# BASE（git show HEAD:{path}，新增文件则空）
base_text = subprocess.run(
["git", "show", "HEAD:{CLOUD_PATH}"],
capture_output=True, text=True, cwd=REPO
).stdout
# CLOUD（GitHub HEAD 最新）
url = "https://api.github.com/repos/jacardl/viceroy-skills/contents/{CLOUD_PATH}"
req = urllib.request.Request(url, headers={
"Accept": "application/vnd.github.v3+json",
"Authorization": "token {TOKEN}"
})
resp = json.loads(urllib.request.urlopen(req).read())
cloud_text = base64.b64decode(resp["content"]).decode("utf-8", errors="replace")
Step 2：合规检查 LOCAL + CLOUD
| 检查项 | 标准 | 不合格处置 |
|---|---|---|
| YAML frontmatter | 以 ---\n...\n--- 包裹且 yaml.safe_load 可解析 | 报错，用户确认后跳过 |
description 值 | 含中文/冒号/(/) 等字符必须双引号包裹 | 自动加引号 |
--- 文档分隔符数量 | 恰好 2 个（frontmatter 开始 + 结束），body 内无多余 --- | 用 grep -n '^---#x27; 定位多余分隔符并删除 |
| 目录结构 | skills/{cat}/{skill}/ 格式 | 报错 |
| 本地 vs 云端字节级比对 | read_bytes() vs base64.b64decode(cloud_content) 相等 | 相等则跳过 merge（Pitfall G） |
⚠️ 字节 vs 字符陷阱（Pitfall G）：
stat().st_size是字节数，len(read_text())是 Unicode 字符数。当文件含中文/emoji 时二者不相等，但可能实际内容相同。判断"本地 vs 云端是否相同"必须用字节级比对，不能用字符数。 | 多余文件 | 顶层不含.git/node_modules/__pycache__/| 警告，用户确认后忽略 | | 目录结构 |skills/{cat}/{skill}/格式 | 报错 |
Step 3：三向合并（git merge-file）
import tempfile, subprocess
from pathlib import Path
def three_way_merge(local_path, cloud_text, base_text):
local_path = Path(local_path)
if cloud_text.strip() == local_path.read_text().strip():
return "identical", cloud_text
with tempfile.TemporaryDirectory() as td:
td = Path(td)
(td/"BASE").write_text(base_text)
(td/"LOCAL").write_text(local_path.read_text())
(td/"CLOUD").write_text(cloud_text)
cp = subprocess.run(
["git", "merge-file", str(td/"LOCAL"), str(td/"BASE"), str(td/"CLOUD")],
capture_output=True, text=True, cwd=str(td)
)
merged = (td/"LOCAL").read_text()
has_conflict = any(m in merged for m in ["<<<<<<<", ">>>>>>>", "======="])
if not has_conflict:
local_path.write_text(merged)
status = "cloud_updated" if merged.strip() == cloud_text.strip() else "merged"
return status, merged
else:
lines = [l for l in merged.splitlines()
if not l.startswith(("<<<<<<<", ">>>>>>>", "======="))]
clean = "
".join(lines)
local_path.write_text(clean)
return "conflict_resolved", clean
Step 4：推送 GitHub
def push_github(local_path, cloud_path, commit_msg, token):
local_path = Path(local_path)
content_b64 = base64.b64encode(local_path.read_text().encode()).decode()
url = "https://api.github.com/repos/jacardl/viceroy-skills/contents/{cloud_path}"
req = urllib.request.Request(url, headers={
"Authorization": "token {token}",
"Accept": "application/vnd.github.v3+json"
})
current = json.loads(urllib.request.urlopen(req).read())
data = json.dumps({
"message": commit_msg,
"content": content_b64,
"sha": current["sha"]
}).encode()
blob_req = urllib.request.Request(url, data=data, headers={
"Authorization": "token {token}",
"Content-Type": "application/json"
}, method="PUT")
result = json.loads(urllib.request.urlopen(blob_req).read())
return result["commit"]["sha"]
Step 5：输出报告
skill: {cat}/{skill}
合规检查:
YAML frontmatter: OK / FAIL
description 引号: OK / 已修复
文件结构: OK / WARN
三向 merge 结果:
local vs cloud: 对齐 / LOCAL新 / CLOUD新 / 冲突
merge status: {status}
GitHub 推送:
commit: {sha}
URL: https://github.com/jacardl/viceroy-skills/commit/{sha}
将下方保存为 /tmp/skill_merge.py，用法：python3 /tmp/skill_merge.py <cat> <skill>
#!/usr/bin/env python3
import sys, urllib.request, subprocess, tempfile, json, base64
from pathlib import Path
import yaml
TOKEN = open("/Users/apple/.hermes/keys/github_token.txt").read().strip()
REPO = "/tmp/viceroy-skills_sync"
def get_cloud(path):
url = "https://api.github.com/repos/jacardl/viceroy-skills/contents/" + path
req = urllib.request.Request(url, headers={"Authorization": "token " + TOKEN, "Accept": "application/vnd.github.v3+json"})
r = json.loads(urllib.request.urlopen(req).read())
return base64.b64decode(r["content"]).decode(), r["sha"]
def merge(local_p, cloud_text, base_text):
lp = Path(local_p)
if cloud_text.strip() == lp.read_text().strip():
return "identical", cloud_text
with tempfile.TemporaryDirectory() as td:
td = Path(td)
(td/"B").write_text(base_text)
(td/"L").write_text(lp.read_text())
(td/"C").write_text(cloud_text)
subprocess.run(["git", "merge-file", str(td/"L"), str(td/"B"), str(td/"C")],
capture_output=True, text=True, cwd=str(td))
merged = (td/"L").read_text()
if not any(m in merged for m in ["<<<<<<<",">>>>>>>","======="]):
lp.write_text(merged)
return ("merged", merged)
else:
lines = [l for l in merged.splitlines()
if not l.startswith(("<<<<<<<",">>>>>>>","======="))]
lp.write_text("
".join(lines))
return ("conflict_resolved", "
".join(lines))
def push(local_p, cloud_path, msg):
b64 = base64.b64encode(Path(local_p).read_text().encode()).decode()
url = "https://api.github.com/repos/jacardl/viceroy-skills/contents/" + cloud_path
req = urllib.request.Request(url, headers={"Authorization": "token " + TOKEN, "Accept": "application/vnd.github.v3+json"})
cur = json.loads(urllib.request.urlopen(req).read())
data = json.dumps({"message": msg, "content": b64, "sha": cur["sha"]}).encode()
r = urllib.request.Request(url, data=data, headers={"Authorization": "token " + TOKEN, "Content-Type": "application/json"}, method="PUT")
return json.loads(urllib.request.urlopen(r).read())["commit"]["sha"]
def check_compliance(text, label):
issues = []
if not text.startswith("---
"):
issues.append(label + ": missing YAML frontmatter")
else:
try:
end = text.index("
---
")
yaml.safe_load("---
" + text[4:end] + "
---")
except Exception as e:
issues.append(label + " YAML: " + str(e))
for line in text.splitlines():
ls = line.strip()
if ls.startswith("description:"):
val = ls.split(":", 1)[1].strip()
if any(c in val for c in ["（", "）", "《", "》"]) and not val.startswith('"'):
issues.append(label + " desc needs quotes: " + val[:60])
return issues
if __name__ == "__main__":
cat, skill = sys.argv[1], sys.argv[2]
local_p = str(Path.home() / (".openclaw/skills/" + cat + "/" + skill + "/SKILL.md"))
cloud_path = "skills/" + cat + "/" + skill + "/SKILL.md"
local_text = Path(local_p).read_text()
cloud_text, _ = get_cloud(cloud_path)
base_text = subprocess.run(["git", "show", "HEAD:" + cloud_path],
capture_output=True, text=True, cwd=REPO).stdout
for t, lbl in [(local_text, "LOCAL"), (cloud_text, "CLOUD")]:
issues = check_compliance(t, lbl)
for iss in issues:
print(" WARN: " + iss)
if not issues:
print(" " + lbl + ": compliance OK")
status, _ = merge(local_p, cloud_text, base_text)
print("merge: " + status)
if status != "identical":
sha = push(local_p, cloud_path, "merge: " + cat + "/" + skill + " (" + status + ")")
print("GitHub commit: " + sha[:7])
print("URL: https://github.com/jacardl/viceroy-skills/commit/" + sha)
else:
print("No changes needed (local == cloud)")
skillspector：本节就是 skillspector 在 skill-maintenance 下的"安装前 / 批量体检"工作流入口skill-github-sync：sync 前必须先跑本节 7.4 体检（确保本地要 push 的 skill 全部 LOW/MEDIUM）skill-creator：新 skill 写完后，发布前自己跑一次 7.5 自检向 jacardl/viceroy-skills 推送 skill 文件使用 GitHub REST API（blobs/trees/commits/refs）。必须使用有写入权限的 Token：
repo scopejacardl/viceroy-skills验证方法（创建 blob 不报 403 即代表有写入权限）：
curl -s -X POST -H "Authorization: token <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"content":"test","encoding":"utf-8"}' \
"https://api.github.com/repos/jacardl/viceroy-skills/git/blobs"
# 成功返回 {"sha":"..."}，403 = 无写入权限
Token 凭证保存路径：~/.hermes/keys/github_token.txt（兼容多环境：~/.openclaw/openclaw.json 也可）
所有 skill 推送到 jacardl/viceroy-skills 时，路径格式：
skills/{category}/{skill-name}/SKILL.md
示例：
skills/operations/aihot/SKILL.md
skills/product/tag-scoring/SKILL.md
skills/developer/skill-github-sync/SKILL.md
skills/ai/9router/SKILL.md
推送完成后验证：
curl -s -H "Authorization: token $TOKEN" \
"https://api.github.com/repos/jacardl/viceroy-skills/git/trees/main?recursive=1" | \
python3 -c "import sys,json; [print(f['path']) for f in json.load(sys.stdin)['tree'] if f['path'].endswith('SKILL.md')]"
# 统计 SKILL.md 文件数（系统级）
find ~/.openclaw/skills -name "SKILL.md" -type f | wc -l
# 列出所有 skill 名称（去重）
find ~/.openclaw/skills -name "SKILL.md" -type f | xargs -I{} dirname {} | xargs -I{} basename {} | sort -u
# 按分类统计
for cat in ai assistant creative developer operations product; do
count=$(find ~/.openclaw/skills/$cat -name "SKILL.md" -type f 2>/dev/null | wc -l)
echo "$cat: $count"
done
# 清理空目录 stub
find ~/.openclaw/skills -maxdepth 2 -name "DESCRIPTION.md" | while read f; do
dir=$(dirname "$f")
[ ! -f "$dir/SKILL.md" ] && echo "STUB: $dir"
done
# 跟 GitHub 仓库对照（需要 token）
python3 << 'EOF'
import urllib.request, json, os
token = open(os.path.expanduser("~/.hermes/keys/github_token.txt")).read().strip()
github = {}
for cat in ['ai','assistant','creative','developer','operations','product']:
url = f"https://api.github.com/repos/jacardl/viceroy-skills/contents/skills/{cat}"
req = urllib.request.Request(url, headers={'Accept':'application/vnd.github.v3+json', 'Authorization':f'token {token}'})
r = json.loads(urllib.request.urlopen(req, timeout=15).read())
github.update({item['name']: cat for item in r if item.get('type')=='dir'})
import os
local = set()
for root, _, files in os.walk(os.path.expanduser("~/.openclaw/skills")):
for f in files:
if f == "SKILL.md":
local.add(os.path.basename(root))
print("本地独有（候选 push）:", sorted(local - set(github.keys())))
print("GitHub 独有（候选 pull）:", sorted(set(github.keys()) - local))
EOF
安装新 skill 后，如果该 skill 在工作流中引用了其他 skill，
必须验证引用是否对齐。方法：grep 双侧 SKILL.md 提取
callee 的实际要求，对照 caller 的引用描述，以严重度表格输出。
详见 references/cross-skill-citation-check.md。
⚠️ 文件修改时间（mtime）是误导性的——skillhub 批量安装/更新时， 大量 skill 的 mtime 会被同步更新到同一日期（如 2026-05-18）， 造成"全部同时更新"的假象。判断"哪些 skill 从未被使用"必须用 session 历史查询。
Hermes 将所有 session 消息存储在 ~/.hermes/state.db，其中
messages.tool_calls 字段包含每次工具调用的 JSON。
查找 skill_view 调用：
import sqlite3
import json
import re
from collections import Counter
conn = sqlite3.connect(os.path.expanduser('~/.hermes/state.db'))
cursor = conn.cursor()
cursor.execute("""
SELECT tool_calls FROM messages WHERE tool_calls LIKE '%skill_view%'
""")
used_skills = Counter()
for row in cursor.fetchall():
if not row[0]:
continue
try:
tool_calls = json.loads(row[0])
for tc in tool_calls:
if tc.get('function', {}).get('name') == 'skill_view':
args = json.loads(tc['function']['arguments'])
name = args.get('name', '')
if name:
used_skills[name] += 1
except (json.JSONDecodeError, KeyError):
# 备用：正则提取
for m in re.finditer(r'"name"\s*:\s*"([^"]+)"', row[0]):
used_skills[m.group(1)] += 1
for skill, count in used_skills.most_common():
print(f"{count:3d}x {skill}")
find ~/.hermes/skills -name "SKILL.md" | while read f; do
skill=$(dirname "$f" | xargs basename)
echo "$skill"
done | sort -u
#!/usr/bin/env python3
"""对比：本地 skill vs session 历史中实际调用过的 skill"""
import sqlite3, json, re, os, subprocess
from collections import Counter
# 1. 获取所有本地 skill
result = subprocess.run(
['find', os.path.expanduser('~/.hermes/skills'), '-name', 'SKILL.md'],
capture_output=True, text=True
)
local_skills = set()
for line in result.stdout.strip().split('\n'):
if line:
skill_path = line.replace(os.path.expanduser('~/.hermes/skills/'), '').replace('/SKILL.md', '')
local_skills.add(skill_path)
# 2. 查询 session 历史
conn = sqlite3.connect(os.path.expanduser('~/.hermes/state.db'))
cursor = conn.cursor()
cursor.execute("SELECT tool_calls FROM messages WHERE tool_calls LIKE '%skill_view%'")
used_skills = set()
for row in cursor.fetchall():
if not row[0]:
continue
try:
for tc in json.loads(row[0]):
if tc.get('function', {}).get('name') == 'skill_view':
args = json.loads(tc['function']['arguments'])
name = args.get('name', '')
if name:
used_skills.add(name)
except:
pass
# 3. 找出从未使用的 skill
never_used = local_skills - used_skills
print(f"本地 skill 总数: {len(local_skills)}")
print(f"历史调用过: {len(used_skills)}")
print(f"从未使用: {len(never_used)} ({len(never_used)/len(local_skills)*100:.0f}%)")
print("\n按从未使用分组:")
from collections import defaultdict
by_cat = defaultdict(list)
for s in sorted(never_used):
cat = s.split('/')[0] if '/' in s else 'root'
by_cat[cat].append(s)
for cat in sorted(by_cat):
print(f" {cat}: {len(by_cat[cat])} 个")
如果只想快速看哪些 skill 最近有活动（不能证明实际使用）：
# 最近 30 天修改过的 SKILL.md
find ~/.hermes/skills -name "SKILL.md" -mtime -30 | while read f; do
echo "$(stat -f %Sm -t %Y-%m-%d "$f") $(dirname "$f" | xargs basename)"
done | sort -r
结论：mtime 只说明"这个文件最近被touch过"，不代表用户实际调用过该 skill。 区分"安装后从未被调用"和"被调用但文件没更新"的唯一方法是查 session 历史。
| 信号 | 含义 | 建议 |
|---|---|---|
| session 历史从未调用 + mtime 30天前 | 真正的废弃 skill | 可安全删除 |
| session 历史从未调用 + mtime 最近30天 | 安装后未激活 | 询问用户是否保留 |
| session 历史有调用 + mtime 30天前 | 可能在用但文件久未更新 | 检查是否需要更新 |
.archive/ 或 .curator_backups/ 目录 | 备份文件 | 确认后可删除 |
#!/usr/bin/env python3
"""
完整的技能使用情况分析脚本
从 SQLite session 历史中提取真实使用的技能，与本地技能对比
"""
import sqlite3, json, os, subprocess
from collections import defaultdict
SKILLS_DIR = os.path.expanduser('~/.hermes/skills')
DB_PATH = os.path.expanduser('~/.hermes/state.db')
# ── 1. 查询 session 历史中的 skill_view 调用 ──────────────────────────
conn = sqlite3.connect(DB_PATH)
cursor = conn.cursor()
cursor.execute("SELECT tool_calls FROM messages WHERE tool_calls LIKE '%skill_view%'")
raw_used = []
for row in cursor.fetchall():
if not row[0]:
continue
try:
for tc in json.loads(row[0]):
if tc.get('function', {}).get('name') == 'skill_view':
args = json.loads(tc['function']['arguments'])
name = args.get('name', '')
if name:
raw_used.append(name)
except:
pass
# ── 2. 别名标准化映射表 ─────────────────────────────────────────────
ALIASES = {
# 公众号系列大小写/路径别名
'zhiliComments': 'zhilicomments',
'social-media/.agents/skills/zhiliComments': 'zhilicomments',
'zhiliGitHub': 'zhiligithub',
'social-media/.agents/skills/zhiliGitHub': 'zhiligithub',
'zhilicomments-publish': 'zhilicomments',
'social-media:.agents/skills:zhilicomments': 'zhilicomments',
'social-media/.agents/skills/zhili-publish': 'zhili-publish',
'social-media/.agents/skills/zhiligithub': 'zhiligithub',
# skill-github-sync 系列别名
'skillgithub-sync': 'skill-github-sync',
'developer/skill-github-sync': 'skill-github-sync',
# geo 系列别名
'geo-content-strategy': 'geo-keyword-research',
'content-strategy/geo-keyword-research': 'geo-keyword-research',
# hv-analysis 别名
'research/hv-analysis': 'hv-analysis',
}
# 标准化：去重后的已使用技能集合
normalized_used = set()
for s in raw_used:
normalized_used.add(ALIASES.get(s, s))
# 顶级目录名也算（如 zhililong, renwei-writing）
if '/' not in s:
normalized_used.add(s)
print(f"Session 历史中调用过的 skill_view: {len(set(raw_used))} 种写法")
print(f"标准化后: {len(normalized_used)} 个")
# ── 3. 获取所有本地技能 ─────────────────────────────────────────────
result = subprocess.run(
['find', SKILLS_DIR, '-name', 'SKILL.md', '-type', 'f'],
capture_output=True, text=True
)
all_skills = []
for line in result.stdout.strip().split('\n'):
if line:
path = line.replace(SKILLS_DIR + '/', '').replace('/SKILL.md', '')
all_skills.append(path)
# ── 4. 判断技能是否被使用（关键：只看最后一级目录名） ─────────────
def is_used(skill_path):
name = skill_path.split('/')[-1]
if skill_path in normalized_used or name in normalized_used:
return True
# 别名后缀匹配
for alias in ALIASES:
if skill_path.endswith(alias):
return True
return False
# ── 5. 分类统计 ────────────────────────────────────────────────────
unused = [s for s in all_skills if not is_used(s)]
by_cat = defaultdict(list)
for s in sorted(unused):
cat = s.split('/')[0]
sub = '/'.join(s.split('/')[1:]) if '/' in s else s
by_cat[cat].append((sub, s))
print(f"\n本地技能总数: {len(all_skills)}")
print(f"从未使用: {len(unused)} ({(len(unused)/len(all_skills)*100):.1f}%)")
print(f"正在使用: {len(all_skills) - len(unused)}")
# ── 6. 按目录输出未使用技能 ───────────────────────────────────────
print("\n" + "="*60)
print("从未使用的技能（按目录）:")
print("="*60)
for cat in sorted(by_cat):
items = by_cat[cat]
result = subprocess.run(
['find', f'{SKILLS_DIR}/{cat}', '-name', 'SKILL.md'],
capture_output=True, text=True
)
total = len([l for l in result.stdout.strip().split('\n') if l])
unused_count = len(items)
if unused_count == total:
print(f"\n🗑️ {cat}/ (全部 {unused_count} 个未使用)")
else:
print(f"\n⚠️ {cat}/ ({unused_count}/{total} 个未使用)")
for sub, full in items[:5]:
print(f" └── {sub}")
if len(items) > 5:
print(f" └── ... 还有 {len(items)-5} 个")
# ── 7. 输出可安全删除的顶级目录 ────────────────────────────────────
print("\n" + "="*60)
print("可安全删除的顶级目录:")
print("="*60)
safe_dirs = []
for cat in sorted(by_cat):
items = by_cat[cat]
result = subprocess.run(
['find', f'{SKILLS_DIR}/{cat}', '-name', 'SKILL.md'],
capture_output=True, text=True
)
total = len([l for l in result.stdout.strip().split('\n') if l])
if len(items) == total:
safe_dirs.append(cat)
print(f" rm -rf {cat}/")
if safe_dirs:
print(f"\n批量命令: rm -rf {' '.join(safe_dirs)}")
Phase 1：分析确认
# 1. 跑分析脚本，确认未使用技能数量
python3 /tmp/analyze_skills.py
# 2. 输出：
# 本地技能总数: 225
# 从未使用: 192 (85.3%)
# 正在使用: 33
Phase 2：分批清理
每次清理前必须：
mkdir -p ~/.hermes/skills-cleanup-backup{1,2,3...} 备份# 第一批：备份目录 + 空目录
cd ~/.hermes/skills
mkdir -p ~/.hermes/skills-cleanup-backup
cp -r .archive .curator_backups ~/.hermes/skills-cleanup-backup/
rm -rf .archive .curator_backups
# 第二批：从未使用的顶级目录
mkdir -p ~/.hermes/skills-cleanup-backup2
for dir in blockchain communication dogfood email github migration mlops red-teaming web-development webpage-audit yuanbao; do
[ -d "$dir" ] && cp -r "$dir" ~/.hermes/skills-cleanup-backup2/ && rm -rf "$dir"
done
# 第三批：激进清理（删除目录下未使用的子技能）
mkdir -p ~/.hermes/skills-cleanup-backup3
# 读取未使用技能列表并逐个备份删除
while IFS= read -r skill; do
skill_dir=$(dirname "$skill")
if [ -n "$skill_dir" ] && [ "$skill_dir" != "." ]; then
cp -r "$skill_dir" ~/.hermes/skills-cleanup-backup3/ 2>/dev/null
fi
rm -rf "$skill"
done < /tmp/unused_skills.txt
Phase 3：验证统计
echo "清理前: $(cat /tmp/before_count.txt) 个技能"
echo "清理后: $(find ~/.hermes/skills -name 'SKILL.md' | wc -l) 个技能"
echo "共删除: $(($(cat /tmp/before_count.txt) - $(find ~/.hermes/skills -name 'SKILL.md' | wc -l))) 个"
# 验证保留的技能仍可用
for skill in zhililong renwei-writing zhili-publish; do
echo "验证: $skill"
# 调用一次 skill_view 测试
done
如需从备份恢复：
# 查看所有备份
ls -la ~/.hermes/skills-cleanup-backup*/
# 恢复指定目录
cp -r ~/.hermes/skills-cleanup-backup3/creative ~/.hermes/skills/
# 恢复后验证
find ~/.hermes/skills -name 'SKILL.md' | wc -l
# 确认无误后可删除备份（谨慎！）
rm -rf ~/.hermes/skills-cleanup-backup*
为什么会漏删（已踩坑）：
zhiliComments 和 zhilicomments 被当作不同技能zhililong）正确方法：
~/.hermes/state.db SQLite 数据库tool_calls 中的 skill_view 调用参数备份策略：
~/.hermes/skills-cleanup-backup{1,2,3...}/mv 比 rm 安全，trash > rm）developer/（skill 自身管理工具）⚠️ Pitfall H：别名未标准化导致漏报（2026-07-04 实测）
首次分析时用了精确路径匹配，漏掉了 ~110 个未使用技能。原因是 session 历史中的 skill_view 调用存在多种别名写法：
| 别名写法 | 标准化为 |
|---|---|
zhiliComments | zhilicomments |
social-media/.agents/skills/zhiliComments | zhilicomments |
zhiliGitHub | zhiligithub |
social-media/.agents/skills/zhiliGitHub | zhiligithub |
skillgithub-sync | skill-github-sync |
developer/skill-github-sync | skill-github-sync |
zhilicomments-publish | zhilicomments |
social-media:.agents/skills:zhilicomments | zhilicomments |
geo-content-strategy | geo-keyword-research |
dogfood（根目录） | 实际是 dogfood/dogfood |
标准化映射表（分析前必须先应用）：
skill_aliases = {
'zhiliComments': 'zhilicomments',
'social-media/.agents/skills/zhiliComments': 'zhilicomments',
'zhiliGitHub': 'zhiligithub',
'social-media/.agents/skills/zhiliGitHub': 'zhiligithub',
'skillgithub-sync': 'skill-github-sync',
'developer/skill-github-sync': 'skill-github-sync',
'zhilicomments-publish': 'zhilicomments',
'social-media:.agents/skills:zhilicomments': 'zhilicomments',
'social-media/.agents/skills/zhili-publish': 'zhili-publish',
'social-media/.agents/skills/zhiligithub': 'zhiligithub',
'geo-content-strategy': 'geo-keyword-research',
'content-strategy/geo-keyword-research': 'geo-keyword-research',
}
判断函数（必须用这个，不能只做字符串精确匹配）：
def is_used(skill_path):
name = skill_path.split('/')[-1] # 只取最后一级目录名
if skill_path in normalized_used or name in normalized_used:
return True
for alias, target in skill_aliases.items():
if alias == skill_path or skill_path.endswith(alias):
return True
return False
标准步骤（2026-07-04 实测有效）：
find ~/.hermes/skills -name "SKILL.md"cp -r <dir> ~/.hermes/skills-cleanup-backup/rm -rf <dir>确认命令示例：
# 备份（先做）
BACKUP=~/.hermes/skills-cleanup-backup
mkdir -p "$BACKUP"
for dir in blockchain mlops github; do
[ -d "$dir" ] && cp -r "$dir" "$BACKUP/" && rm -rf "$dir"
done
# 验证
echo "清理后: $(find ~/.hermes/skills -name 'SKILL.md' | wc -l) 个技能"
~/.hermes/state.db SQLite 数据库的 messages.tool_calls 字段，从 session 历史中提取真实 skill_view 调用记录，比文件 mtime 更准确。固化 Python 对比脚本 + mtime 参考命令 + 清理决策框架。新增 9.1 节 Pitfall H「别名未标准化导致漏报」—— 首次分析漏掉 110 个未使用技能是因为 zhiliComments/zhiliGitHub 等多种写法未映射到统一名称；固化标准化映射表 + 判断函数。新增 9.2 节「批量清理工作流」—— 实测有效的 10 步流程，含别名标准化 → 目录分组 → 用户确认 → 备份 → 执行 → 验证。--- 文档分隔符」—— body 内多余 --- 会让 YAML 多文档解析器报错；固化诊断命令（grep -n '^---#x27;）+ Python 删除脚本。新增 Pitfall G「字节 vs 字符数差异」—— UTF-8 文件 stat().st_size ≠ len(read_text())，导致本地 vs 云端文件大小比较失真；固化正确解法（read_bytes() 字节级比对）。SKILL.md Step 2 合规检查表新增 --- 数量检查 + 字节级比对步骤。config/ 类文件，对含真实凭证的 LOCAL 文件强制保留 CLOUD 脱敏版，防止明文 APPSECRET 上云。--- 识别（description 块内 --- 会被 yaml.safe_load 误判为第二个文档）；固化 /tmp/skill_merge.py 为快速调用脚本。