Skill Guardian

Other

Skill 全生命周期守护者。—— 每日自动扫描所有 workspace，检测新增/变更的 Skill。功能一：动态发现所有 agent workspace 下的 Skill，无需手动配置扫描范围。功能二：功能重叠检测（新增时），若发现相似/重复则发出提醒。功能三：新增/变更 Skill 自动生成或更新使用指南。功能四：更新总览 README.md。 V2 升级：hash 变更检测 + 自动更新指南 + 静默退出 + 无 YAML frontmatter 兼容。触发时机：每日定时扫描、新建/修改 Skill、用户说"新技能检查"、"检查重复"、"生成使用指南"。

Install

openclaw skills install skill-lifecycle-guardian

Skill Lifecycle Guardian — 技能全生命周期守护者 (V2)

⚠️ 安装后必做：本 Skill 依赖定时 cron 驱动。安装后必须创建两个 cron：

① 每日全量扫描（兜底）：

openclaw cron add --job '{
  "name": "skill-guardian-daily-scan",
  "schedule": {"kind":"cron","expr":"0 6 * * *","tz":"Asia/Shanghai"},
  "sessionTarget": "main",
  "payload": {"kind":"systemEvent","text":"执行 skill-lifecycle-guardian 每日扫描。读 ~/.openclaw/workspace/memory/skill-registry.json，扫描所有 workspace+plugin-skills+skills 目录下的 SKILL.md，对比 hash 检测新增/变更，如有变更则走完整流程（重叠检测→生成指南→更新README），无变化则静默结束。"},
  "delivery": {"mode":"none"}
}'

② 每 3 小时变更检测（独立运行，有变更才通知）：

openclaw cron add --job '{
  "name": "guardian-change-detector",
  "schedule": {"kind":"cron","expr":"0 */3 * * *","tz":"Asia/Shanghai"},
  "sessionTarget": "isolated",
  "payload": {"kind":"agentTurn","message":"执行 skill-lifecycle-guardian 变更检测。\n\n⚠️ 关键约束：检测到变更后必须走完完整流程，禁止只更新 hash 就结束。\n\n步骤：\n1. 读取 ~/.openclaw/workspace/skills/skill-lifecycle-guardian/SKILL.md 了解完整工作流程\n2. 读 ~/.openclaw/workspace/memory/skill-registry.json\n3. 遍历所有已注册 Skill，md5sum 每个 SKILL.md 与 registry hash 对比\n\n判定与执行：\n- 全部 hash 一致 → 完全静默结束，不发通知\n- 任何 hash 不一致 → 严格按照 guardian SKILL.md 的【工作流程】章节执行：新 Skill（重叠检测→生成指南→更新README）、变更 Skill（更新指南→更新README→更新hash）。仅在执行完所有步骤后，简报变更结果（≤3行）。\n\n绝对禁止：只更新 registry hash 而不生成指南和更新 README。","timeoutSeconds":600},
  "delivery": {"mode":"announce","channel":"wecom","bestEffort":true}
}'

不创建 cron 则本 Skill 只能手动触发，不会自动守护。

守护 Skill 全生命周期：发现新建 → 检测变更 → 生成/更新指南 → 维护总览。

触发条件

满足以下任一即触发：

每日定时扫描（cron 0 6 * * *）：自动检测新增和变更的 Skill
检测到新 SKILL.md 文件：skills 目录下出现了之前不存在的 SKILL.md（手动触发时）
Skill 被修改 ⚡：任何 SKILL.md 被 edit 或 write 工具修改后，AI 必须在同一轮对话中触发 guardian 变更扫描（调用 sessions_send 到 main session，或直接在 main session 中执行本流程）
检测到已有 SKILL.md 内容变更：与 registry 中存储的 hash 不一致（cron 扫出时）
用户明确要求：说"检查新技能"、"有没有重复的skill"、"给这个skill生成使用指南"、"更新指南"
Skill 安装完成：clawhub install 没有 post-install hook，安装后由 cron（每 3h + 每日 6:00）hash-check 自动检测到新 SKILL.md 并触发扫描。安装后想立即扫描可以说「检查新技能」。

⚠️ 触发条件 3（修改事件）依赖 AI 行为约束，不由系统事件驱动。需要该 Skill 使用者在其 AI 助手中配置行为规则：任何 SKILL.md 文件被修改后，AI 必须在同一轮对话中触发 guardian 扫描。未配置此规则时，修改 Skill 后的检测由 cron（② 每 3 小时）兜底。

数据存储

registry 文件路径：~/.openclaw/workspace/memory/skill-registry.json

{
  "skills": {
    "<skill-name>": {
      "path": "/path/to/SKILL.md",
      "dirname": "dirname",
      "description": "...",
      "hash": "md5-of-skill.md-content"
    }
  },
  "lastScan": "ISO8601-timestamp"
}

hash 计算方式：读取 SKILL.md 全文，计算 MD5（md5sum 或等价方式）。用于变更检测。

工作流程

第零步：变更检测（每日扫描专属）

仅在每日定时扫描时执行。手动触发跳过此步，直接进入第一步。

从 openclaw.json 读取所有 agent 的 workspace 路径
对每个 workspace + ~/.openclaw/plugin-skills/ + ~/.openclaw/skills/，查找 */SKILL.md
合并去重（以 name 为准）
对每个 SKILL.md 计算 MD5 hash

情况	判定	后续动作
name 不在 registry 中	🆕 新 Skill	走第一→四步
name 在，hash 不同	📝 已有 Skill 变更	跳过第一步（不重复重叠检测），仅走第三、四步（更新指南）
name 在，hash 相同	⏭️ 无变化	跳过，不处理

汇总变更结果：检测到 N 个新 Skill、M 个变更 Skill
更新 registry：所有扫描到的 Skill 的 hash 写回 registry，更新 lastScan
如果 N + M = 0 → 静默结束，不发通知

第一步：发现新 Skill

确定目标 Skill 的 SKILL.md 路径和内容：

# 列出所有 skill 目录（三个来源合并扫描）
ls -d ~/.openclaw/workspace/skills/*/SKILL.md ~/.openclaw/plugin-skills/*/SKILL.md ~/.openclaw/skills/*/SKILL.md 2>/dev/null

扫描范围（动态发现，不再硬编码）：

守护者读取 openclaw.json 中所有 agent 的 workspace 字段，自动发现所有 {workspace}/skills/ 目录：

openclaw.json → 遍历 agents.list[].workspace → 找 {workspace}/skills/
  ├─ /root/.openclaw/workspace/skills/        (main agent)
  ├─ /root/.openclaw/workspace-team/skills/    (team agent)
  ├─ /root/.openclaw/workspace-study/skills/   (study agent)
  └─ ... 以后新增的 workspace 自动加入

加上两个系统级目录：

~/.openclaw/plugin-skills/ — 插件市场安装的 Skill
~/.openclaw/skills/ — 系统级 Skill

所有目录合并后去重（以 name 字段为准），确保不遗漏任何 Skill。

读取新 Skill 的 name、description 和正文内容。

第二步：功能重叠检测

仅对新 Skill 执行。变更的 Skill 跳过此步。

对比新 Skill 与所有已有 Skill，判断是否功能重叠。

检测方法：

读取每个已有 Skill 的 SKILL.md frontmatter（name + description）
从新 Skill 的 description 和正文中提取核心功能关键词
与每个已有 Skill 逐一对比，重点关注：
- 目标用户群体是否相同
- 核心操作是否重叠（如：都是管理待办、都是搜索）
- 触发词是否冲突
判定结果分三档：

重叠等级	判定标准	处理方式
🔴 高度重复	核心功能几乎一致，触发词重叠	必须提醒，建议合并而非新建
🟡 部分重叠	部分功能交集，但各有侧重	建议提醒，说明重叠点和差异点
🟢 无重叠	功能独立，无冲突	正常通过

输出格式（仅在检测到重叠时输出）：

⚠️ 功能重叠提醒

新 Skill：{new-skill-name}
已有 Skill：{existing-skill-name}
重叠等级：🔴高度重复 / 🟡部分重叠

重叠点：{具体描述}
差异点：{具体描述}
建议：{合并/保留两者/调整触发词}

已知的易混淆对（铁律1延伸）：

tencent-agent-storage（网盘）≠ tencent-cloud-cos（对象存储）
wecom-edit-todo（企微待办）≠ personal-assistant（个人助理待办）
wecom-doc-manager（企微文档）≠ tencent-docs（腾讯文档）

第三步：生成 / 更新用户使用指南

新 Skill → 生成指南；变更的 Skill → 覆盖更新已有指南。

目标目录：~/.openclaw/workspace/skills/user-guides/

生成流程：

读取 Skill 的 SKILL.md 全文
判断用户可见性（见下方规则）
如果是内部工具 → 跳过指南生成
如果是面向用户的 Skill：
- 提取核心功能点
- 为每个功能点编写自然语言示例
- 生成指南文件

文件命名：按编号递增，格式 {NN}-{中文名称}.md

查询现有最大编号：ls ~/.openclaw/workspace/skills/user-guides/ | grep -oP '^\d+' | sort -n | tail -1
新 Skill：新编号 = 最大编号 + 1
变更 Skill：找到已有指南文件，就地覆盖更新（编号不变、文件名不变）

指南格式（严格遵循）：

# {功能名称}使用指南

{emoji} **{一句话描述}**

## {主要操作1}
- 示例语句1
- 示例语句2

## {主要操作2}
- 示例语句1
- 示例语句2

💡 小提示：
- 提示1
- 提示2

关键原则：

每个操作配2-3个自然语言示例，让用户知道怎么说话
示例必须是用户视角的自然对话，不是命令行
小提示写用户容易忽略的注意事项
篇幅控制在15-30行，简洁为主

第四步：更新总览 README.md

更新 skills/user-guides/README.md：

读取当前 README.md
根据 Skill 的性质归类到对应分类（日常办公/文档与数据/信息获取/特色功能，或新增分类）
新 Skill：在对应分类表格中追加一行
变更 Skill：如果分类未变，更新对应条目；如果分类变了，移动条目
编号重新排列确保连续

如果 Skill 属于内部/开发者工具：

不生成用户指南
在 README.md 的"未列入的内部工具"部分追加/更新条目

用户可见性判断

在生成指南前，先判断该 Skill 是否面向普通用户：

面向用户（生成指南）：

功能通过自然语言对话即可使用
不需要技术背景（编程、CLI、API）
触发词是日常用语

内部工具（不生成指南，仅列入内部列表）：

需要编程/CLI操作
是其他 Skill 的依赖或内部调用
仅管理员/开发者使用
功能高度技术化（如浏览器自动化、CI/CD）

边界情况

场景	处理
新 Skill 与已有 Skill 高度重复	提醒用户，不自动合并，等用户决策
Skill 内容变更	重新生成对应指南、更新 README（如需要）
已有 Skill 被删除	从 registry 移除、保留指南文件（不自动删除）、标注为"已移除"
批量安装多个 Skill	逐个检测，汇总输出
用户拒绝生成/更新指南	跳过第三、四步
user-guides 目录不存在	自动创建
新 Skill 为内部工具	跳过指南生成，仅在 README 内部工具列表追加

变更通知格式

每日扫描完成后，仅在有变更时推送通知：

🔍 Skill 扫描报告（{日期}）

🆕 新增 Skill（{N}个）：
- {skill-name}：{简述}

📝 变更 Skill（{M}个）：
- {skill-name}：指南已更新

🔧 无需变更：
- 未发现功能重叠
- 总计追踪 {total} 个 Skill

如果 N + M = 0 → 静默，不发任何通知。