# Yy Check Skills Consistency

> 检查并修复 README.md 中的技能列表一致性，同步旧技能名到 install-skills.ts。 用于校验 skills/ 目录与技能表格的排序、条目和说明，以及技能名变更或删除后同步旧名称； README 说明必须是面向人的精简归纳，不用于逐字同步 SKILL.md 的 description 原文或触发规则。

- Skill: `bulls-cows/yy-check-skills-consistency` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bulls-cows/yy-check-skills-consistency`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bulls-cows/yy-check-skills-consistency/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bulls-cows (https://skillmd.com/u/bulls-cows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bulls-cows/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. 输出结果

```markdown
## 验证结果

### 排序检查

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

### 条目一致性检查

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

### 描述一致性检查

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

### 修复操作

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

### 旧技能名同步

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