Yy Check Skills Consistency

yy-check-skills-consistency

描述

检查 README.md 中的技能列表与实际 skills/ 目录内容的一致性，验证排序、条目和说明是否匹配，并修复发现的问题。当技能名变更或技能被删除时，同步将旧技能名添加到 scripts/install-skills.ts 的 oldSkillNamesToDelete 数组中。

说明同步时，SKILL.md 的 frontmatter description 是技能用途的语义权威来源，但不是 README 说明列的逐字覆盖模板。README 技能列表主要给人看，说明列只应介绍技能是什么、解决什么问题，并且必须是精简归纳后的表达，不应直接照搬原文，也不应混入触发场景、排除条件或实现细节。说明列应使用无句号的短句式目录介绍，减少视觉噪声。

使用场景

• 需要验证 README.md 中的技能列表是否按字母顺序排序
• 需要验证技能列表与 skills/ 目录实际内容一致
• 需要修复技能列表的不一致问题
• 需要同步 README.md 技能列表说明，但希望保持面向人的精简归纳
• 技能名发生变更或技能被删除后，需要同步更新 scripts/install-skills.ts 中的旧技能名列表

不应触发：

• 只是查看 README.md 内容
• 只是检查 skills/ 目录内容
• 只是想把 SKILL.md 的 description 或正文原句直接复制到 README.md
• 不是技能相关的文档一致性检查

指令

步骤 1. 读取 README.md

• 读取项目根目录的 README.md 文件
• 提取技能列表部分的内容

步骤 2. 读取 skills/ 目录

• 列出 skills/ 目录下的所有子目录
• 过滤出有效的技能目录（包含 SKILL.md 的目录）
• 读取每个 SKILL.md 的 frontmatter description 字段，作为技能用途的语义权威来源
• 不要把 description 或正文原句默认视为 README 说明列的可直接复用文本

步骤 3. 验证字母顺序排序

• 检查 README.md 中的技能列表是否按字母顺序排序
• 如果未排序，记录需要调整的顺序

步骤 4. 验证条目一致性

• 比较 README.md 中的技能列表与 skills/ 目录中的实际技能
• 识别出只在 README.md 中存在的技能（冗余项）
• 识别出只在 skills/ 目录中存在的技能（缺失项）

步骤 5. 验证描述一致性与归纳质量

• 将 README.md 表格"说明"列中的描述与 SKILL.md 的 frontmatter description 逐条做语义比对
• 判断 README 现有说明是否已满足"面向人的精简归纳"要求
• 识别出需要保留的技能说明（可保留项）
• 识别出语义正确但接近原文直搬的技能说明（需改写项）
• 识别出语义偏离的技能说明（语义不一致项）
• 识别出混入触发场景、排除条件、示例或实现细节的技能说明（需简化项）

判定规则：

• 可保留项：已经是面向人的一句话介绍，只保留技能核心用途，表述简短，且明显不是从原文直接照搬
• 需改写项：语义正确，但仍明显沿用 description 或正文原句，只是轻微删减或换序，尚未形成适合 README 列表浏览的归纳表达
• 需简化项：混入"当用户……时""用于……时触发""不适用于……"这类路由信息，或包含长示例、边界清单、支持范围细节、实现细节
• 需收口项：说明主体已合格，但末尾保留句号或多余收尾标点，不符合 README 技能列表的紧凑展示要求
• 语义偏离：遗漏核心用途、错误描述适用范围，或把非关键细节误写成主用途

步骤 6. 生成验证报告

• 输出排序检查结果
• 输出条目一致性检查结果
• 输出描述一致性检查结果
• 区分列出可保留项、需改写项、语义不一致项、需简化项和需收口项

步骤 7. 修复问题

决策分支：

• 发现排序问题：按字母顺序重新排列技能列表
• 发现缺失项：在 README.md 中添加相应的技能条目，并基于技能内容归纳出面向人的精简说明
• 发现冗余项：从 README.md 中删除对应的技能条目
• 发现需改写项：在不改变技能核心介绍的前提下，改写为更短、更像目录说明的归纳表达
• 发现语义不一致项：以 description 为语义权威来源，重写 README.md 中对应条目的说明，并收敛为精简归纳
• 发现需简化项：先移除触发场景、排除条件和细节噪声，再归纳为一句技能介绍
• 发现需收口项：仅移除末尾句号或多余收尾标点，不改动说明主体
• 说明已符合要求：保留 README.md 中原有说明，不做替换
• 无问题：跳过修复

步骤 8. 同步旧技能名

维护 scripts/install-skills.ts 的 oldSkillNamesToDelete 数组。该数组的作用是：执行 npm run install:skills 时，脚本会先将当前 skills/ 目录中的技能与该数组合并，再统一调用 skills remove -g 卸载全局技能，最后重新安装。需要处理两类场景：

• 删除/重命名：将旧技能名加入数组，确保已安装的残留文件被清除
• 新增技能：如果新增技能名恰好在数组中已存在，需将其移除，避免脚本对该技能执行不必要的删除操作

信息来源：

• git 本地改动：通过 git diff 或 git status 检测 skills/ 目录中已删除、已重命名或新增的目录
• AI 聊天上下文：当前对话中用户明确告知的技能名变更、删除或新增信息

决策分支：

• 检测到技能删除（git 显示 skills/ 下某目录被删除，或用户明确告知删除了某技能）：将被删除的技能名添加到 oldSkillNamesToDelete 数组
• 检测到技能名变更（git 显示 skills/ 下某目录被重命名，或用户明确告知技能名变更）：将变更前的旧技能名添加到 oldSkillNamesToDelete 数组
• 检测到新增技能（git 显示 skills/ 下新增了目录，或用户明确告知新增了某技能）：检查新增技能名是否在 oldSkillNamesToDelete 数组中，若存在则从数组中移除
• 同时有删除、变更和新增：分别按上述规则处理
• 未检测到删除、变更或新增：跳过此步骤

操作要求：

• 添加前先检查 oldSkillNamesToDelete 数组中是否已存在该技能名，避免重复添加
• 移除前确认技能名确实存在于数组中，且该技能已作为新增技能存在于 skills/ 目录
• 保持数组的现有格式（单行一项，逗号分隔）
• 不修改数组中已有的旧技能名（冲突移除除外）

步骤 9. 输出结果

## 验证结果

### 排序检查

- 状态: ✅ 通过 / ❌ 未通过
- 详情: [具体说明]

### 条目一致性检查

- 状态: ✅ 通过 / ❌ 未通过
- 缺失项: [技能列表]
- 冗余项: [技能列表]

### 描述一致性检查

- 状态: ✅ 通过 / ❌ 未通过
- 可保留项: [技能名称及原因]
- 需改写项: [技能名称及改写原因]
- 语义不一致项: [技能名称及差异说明]
- 需简化项: [技能名称及压缩原因]
- 需收口项: [技能名称及收口原因]

### 修复操作

- [已执行 / 未执行] 修复操作
- 详情: [具体修复内容]

### 旧技能名同步

- 状态: ✅ 已同步 / ⏭️ 跳过（无删除、变更或新增冲突）
- 新增旧技能名: [技能列表 / 无]
- 移除冲突技能名: [技能列表 / 无]