skill-review

技能审查技能

概述

skill-review 技能为审计 claude-skills 仓库中的技能提供了一套全面、系统的流程。它结合自动化技术验证与 AI 驱动的核查，确保技能始终准确、最新且质量上乘。

适用场景：

• 调查技能中疑似存在的问题
• 发布了主要的软件包版本更新（例如 better-auth 1.x → 2.x）
• 距上次验证已超过 90 天
• 将技能提交到市场之前
• 用户报告按照技能说明操作时出错
• 示例似乎已过时或相互矛盾

生产环境实证：成功审计 better-auth 技能（2025-11-08），发现 6 个严重/高优先级问题，包括导入不存在的 API；移除了 665 行错误代码，并使用正确模式实现了 v2.0.0。

---

快速开始

通过斜杠命令调用

/review-skill <skill-name>

示例：

/review-skill better-auth

通过技能调用（主动触发）

当 Claude 发现潜在问题时，可以提出建议：

User: "I'm having trouble with better-auth and D1"

Claude: "I notice the better-auth skill was last verified 6 months ago.
Would you like me to review it? Better-auth recently released v1.3
with D1 changes."

---

此技能的功能

9 阶段系统化审计

1. 审查前准备（5-10 分钟）

   • 在本地安装技能：./scripts/install-skill.sh <skill-name>
   • 检查当前版本和上次验证日期
   • 测试技能发现

2. 标准合规性（10-15 分钟）

   • 验证 YAML frontmatter（名称、描述、许可证）
   • 检查关键词是否全面
   • 验证描述是否采用第三人称风格
   • 确保目录结构符合规范

3. 官方文档核验（15-30 分钟）

   • 使用 Context7 MCP 或 WebFetch 验证 API 模式
   • 在 GitHub 上检查近期更新和问题
   • 对照 npm registry 验证软件包版本
   • 与生产环境仓库进行比较

4. 代码示例与模板审查（20-40 分钟）

   • 验证导入语句在当前软件包中确实存在
   • 检查 API 方法签名是否与官方文档一致
   • 确保各文件中的架构保持一致
   • 测试模板能否构建和运行

5. 跨文件一致性（15-25 分钟）

   • 比较 SKILL.md 与 README.md 中的示例
   • 验证“捆绑资源”部分是否与实际文件一致
   • 确保配置示例一致

6. 依赖项与版本（10-15 分钟）

   • 运行 ./scripts/check-versions.sh <skill-name>
   • 检查软件包更新中是否有破坏性变更
   • 验证“上次验证”日期是否为近期日期

7. 问题分类（10-20 分钟）

   • 按严重性分类：🔴 严重 / 🟡 高 / 🟠 中 / 🟢 低
   • 附证据记录问题（GitHub URL、文档链接、npm 更新日志）

8. 修复实施（30 分钟 - 4 小时）

   • 自动修复明确无歧义的问题
   • 仅在涉及架构决策时询问用户
   • 一致地更新所有受影响文件
   • 存在破坏性变更时升级版本

9. 修复后验证（10-15 分钟）

   • 测试技能发现
   • 验证模板是否有效
   • 检查是否仍有矛盾
   • 提交并附详细更新日志

自动化检查（通过脚本）

该技能会运行 ./scripts/review-skill.sh <skill-name>，检查以下内容：

• ✅ YAML frontmatter 语法和必填字段
• ✅ 软件包版本是否为最新（npm）
• ✅ 失效链接（HTTP 状态）
• ✅ 代码中的 TODO 标记
• ✅ 文件组织（预期目录是否存在）
• ✅ “上次验证”日期是否过旧

手动验证（AI 驱动）

Claude 会执行：

• 🔍 对照官方文档验证 API 方法
• 🔍 检查 GitHub 动态和问题
• 🔍 与生产环境仓库进行比较
• 🔍 核验代码示例是否正确
• 🔍 验证架构一致性

---

流程工作流

第 1 步：运行自动化检查

./scripts/review-skill.sh <skill-name>

根据输出识别技术问题。

Step 2：执行手动验证

对于 Phase 3：官方文档验证：

1. 使用 Context7 MCP（如果可用）：

   Use Context7 to fetch: /websites/<package-docs>
   Search for: [API method from skill]
   

2. 或使用 WebFetch：

   Fetch: https://<official-docs-url>
   Verify: [specific patterns]
   

3. 检查 GitHub：

   Visit: https://github.com/<org>/<repo>/commits/main
   Check: Last commit, recent changes
   Search issues: [keywords from skill]
   

4. 查找生产环境示例：

   WebSearch: "<package> cloudflare production github"
   Compare: Do real projects match our patterns?
   

对于 Phase 4：代码示例审查：

• 验证所有导入项均存在（检查官方文档）
• 检查 API 方法签名是否匹配
• 确保各文件中的 schema 一致
• 测试模板是否实际可用

Step 3：问题分类

🔴 严重 — 影响功能：

• 不存在的 API 方法／导入项
• 无效配置
• 缺少必需依赖

🟡 高 — 容易引起困惑：

• 不同文件中的示例相互矛盾
• 模式不一致
• 主要版本过时

🟠 中 — 降低质量：

• 次要版本陈旧（超过 90 天）
• 缺少文档章节
• 错误列表不完整

🟢 低 — 润色问题：

• 拼写错误、格式不一致
• 缺少可选元数据

Step 4：修复问题

满足以下条件时自动修复：

• ✅ 修复方式明确无歧义（根据文档使用正确的导入项）
• ✅ 证据明确
• ✅ 不影响架构

满足以下条件时询问用户：

• ❓ 存在多种有效方案
• ❓ 需要决定是否进行破坏性变更
• ❓ 需要进行架构选择

提问格式：

I found [issue]. There are [N] approaches:

1. [Approach A] - [Pros/Cons]
2. [Approach B] - [Pros/Cons]

Recommendation: [Default based on evidence]

Which would you prefer?

Step 5：评估版本升级

如果存在破坏性变更：

• 主版本：v1.0.0 → v2.0.0（API 模式发生变化）
• 次版本：v1.0.0 → v1.1.0（新增功能，向后兼容）
• 修订版本：v1.0.0 → v1.0.1（仅修复错误）

Step 6：生成审查报告

## Skill Review Report: <skill-name>

**Date**: YYYY-MM-DD
**Trigger**: [Why review performed]
**Time Spent**: [Duration]

### Findings

🔴 CRITICAL (N): [List with evidence]
🟡 HIGH (N): [List with evidence]
🟠 MEDIUM (N): [List with evidence]
🟢 LOW (N): [List with evidence]

### Remediation

**Files Modified**: [List]
**Version Update**: [old] → [new]
**Breaking Changes**: Yes/No

### Verification

✅ Discovery test passed
✅ Templates work
✅ Committed: [hash]

### Recommendation

[Final assessment]

---

示例：better-auth 审查

发现

问题 #1：不存在的 d1Adapter 🔴 严重

位置：references/cloudflare-worker-example.ts:17

问题：从 'better-auth/adapters/d1' 导入 d1Adapter，但该模块不存在

证据：

• 官方文档：https://better-auth.com/docs/integrations/drizzle
• GitHub：代码库中没有 d1Adapter 导出项
• 生产环境：4 个仓库使用 Drizzle/Kysely

修复：改为从 'better-auth/adapters/drizzle' 导入 drizzleAdapter

结果

• 删除的文件：3（过时模式）
• 创建的文件：3（正确模式）
• 变更行数：净增 +1,266
• 版本：v1.0.0 → v2.0.0
• 耗时：3.5 小时

---

捆绑资源

此技能引用了：

1. planning/SKILL_REVIEW_PROCESS.md — 完整的 9 阶段手动指南
2. scripts/review-skill.sh — 自动验证脚本
3. .claude/commands/review-skill.md — 斜杠命令定义

---

Claude 应调用此技能的时机

主动触发条件：

• 用户提到技能似乎已过时
• 提及软件包的主版本
• 用户报告按照技能操作时遇到错误
• 检查元数据发现距离上次验证已超过 90 天

明确触发条件：

• “review the X skill”
• “audit better-auth skill”
• “is cloudflare-worker-base up to date?”
• “check if tailwind-v4-shadcn needs updating”

---

Token 使用效率

不使用此技能：约 25,000 个 token

• 通过反复试错进行验证
• 重复查阅文档
• 不同文件中的修复不一致
• 缺少证据引用

使用此技能：约 5,000 个 token

• 系统化流程
• 清晰的决策树
• 基于证据的修复
• 完整的审查记录

节省：约 80%（20,000 个 token）

---

可预防的常见问题

1. 虚构的 API 适配器 — 不存在的导入项
2. 过时的 API 方法 — 签名已变更
3. schema 不一致 — 表名不同
4. 过时脚本 — 使用已弃用的方法
5. 版本滞后 — 软件包已超过 90 天未更新
6. 相互矛盾的示例 — 存在多种相互冲突的模式
7. 失效链接 — 返回 404 的文档 URL
8. YAML 错误 — 无效的 frontmatter 语法
9. 缺少关键词 — 不易被发现
10. 捆绑资源不完整 — 列出的文件实际不存在

---

最佳实践

1. 始终引用来源 - GitHub URL、文档链接、npm 更新日志
2. 不要猜测 - 根据当前官方文档进行核实
3. 系统化执行 - 完成全部 9 个阶段
4. 修正一致性 - 更新所有文件，而不只是一个文件
5. 详尽记录 - 编写详细的提交信息
6. 修复后测试 - 确认技能仍然有效

---

已知限制

• 检查链接需要网络访问
• 检查软件包版本需要安装 npm
• Context7 MCP 的可用性因软件包而异
• 搜索生产仓库可能需要 GitHub API
• 手动阶段需要人工判断

---

版本历史

v1.0.0（2025-11-08）

• 首次发布
• 9 阶段系统化审计流程
• 自动化脚本 + 手动指南
• 斜杠命令 + 技能封装
• 在 better-auth v2.0.0 审计中通过生产环境测试

---

其他资源

• 完整流程指南：planning/SKILL_REVIEW_PROCESS.md
• 代码仓库：https://github.com/jezweb/claude-skills
• 审计示例：参见流程指南附录 B（better-auth v2.0.0）

---

最后核实时间：2025-11-08 | 版本：1.0.0