AI技能审查SKILL：你的技能「体检中心」
鹿Sir约 9 分钟鹿Sir上线，见字如面。
在 AI Agent 生态爆发的今天，一个残酷的现实是：80% 的 SKILL 都存在结构性问题。
SKILL.md 动辄上千行、脚本散落在各处、逻辑漏洞频出、甚至绑定特定工具导致无法迁移...这些问题就像埋在地下的地雷，平时看似无害，一旦规模扩大就会引发系统性崩溃。
今天鹿Sir要介绍的 Skill Review（技能审查器），正是为解决这些问题而生。它像一位经验丰富的「代码医生」，为你的 SKILL 做全面体检，输出可执行的优化方案。
一、为什么需要 Skill Review？
SKILL 开发的三大痛点
随着 AI 技能市场的快速发展，SKILL 质量参差不齐的问题日益凸显：
结构混乱：SKILL.md 过长、资源文件散落、参考文档混入正文 逻辑缺陷：流程断层、边界未覆盖、指令模糊不可执行 兼容性差：绑定特定 Agent 工具，无法跨平台复用
一个真实案例：
某团队开发的 PDF 处理 SKILL，SKILL.md 长达 623 行，API 参数说明占了近一半。当需要适配新的 Agent 工具时，发现里面硬编码了 `.qoder/` 路径和 `qoder` CLI 命令——这意味着整个 SKILL 需要重写。
Skill Review 正是为避免这类悲剧而生。
二、核心能力：三维立体审查
Skill Review 采用「结构性 + 逻辑性 + 兼容性」三维审查模型，全面扫描 SKILL 的潜在问题：
维度一：结构性审查（脚本自动化）
维度二：逻辑性审查（LLM 深度分析）
维度三：Agent 兼容性审查
这是 Skill Review 的独特价值——确保 SKILL 可以在不同 Agent 工具间自由迁移：
三、核心突破：自我迭代的审查闭环
突破一：脚本 + LLM 协同审查
Skill Review 的创新之处在于人机协同：
脚本负责：结构检测、文件统计、权限检查等确定性任务 LLM 负责：逻辑分析、语义理解、优化建议生成
这种分工让审查既高效又深入——脚本毫秒级完成结构扫描，LLM 深度分析逻辑合理性。
突破二：P0/P1/P2 优先级分级
不是所有问题都需要立即修复。Skill Review 采用三级优先级：
这让开发者能聚焦关键问题，避免被大量低优先级建议淹没。
突破三：自我迭代模式
Skill Review 内置 `review-loop.py`，支持循环审查-修复直到无问题：
python3 scripts/review-loop.py <skill-dir> --max-iterations 5
这意味着：
自动检测结构性问题并修复 每次迭代后重新审查 直到所有 P0/P1 问题解决或达到最大迭代次数
四、实战演示：一个「病危」SKILL 的抢救过程
鹿Sir用一个真实案例，展示 Skill Review 如何挽救一个濒临废弃的复杂 SKILL。
被审查的 SKILL：data-migrator（数据迁移工具）
这是一个内部使用的数据迁移 SKILL，开发者反馈「时灵时不灵」「换个环境就报错」「别人没法接手」。
原始目录结构（混乱不堪）：
data-migrator/
├── manifest.json
├── SKILL.md # 1280 行！逻辑混乱
├── config.yaml # 配置散落在根目录
├── template.sql # 模板文件乱放
├── utils.py # 脚本也在根目录
├── migrate_logic.md # 参考文档混入
├── migrate_logic_detail.md # 还有一份更详细的
└── scripts/
└── run.sh # 只有一个空壳脚本
SKILL.md 结构（问题重重）：
没有「技能工作流」章节，步骤散落在各处 同时存在「使用说明」「操作步骤」「执行流程」三个类似章节 硬编码了 `.qoder/config.json` 路径 描述中写「仅在 Qoder 中可用」 边界条件缺失：没说明大数据量怎么处理
开发者说：「这 SKILL 我自己都用不下去。」
执行审查
"/skill-review 帮我审查 data-migrator 这个 SKILL
AI 启动 Skill Review，输出三级警报：
# 技能审查报告：data-migrator
## 🚨 结构概览（问题严重）
| 目录/文件 | 状态 | 说明 |
|-----------|------|------|
| manifest.json | ✅ | 元数据完整 |
| SKILL.md | ❌ | 1280 行，严重超标 |
| scripts/ | ⚠️ | 1 个脚本，但 utils.py 在根目录 |
| references/ | ❌ | 不存在，参考文档散落 |
| assets/ | ❌ | 不存在，模板文件乱放 |
## 🚨 P0 阻塞性问题
| 优先级 | 问题 | 影响 |
|--------|------|------|
| P0 | 缺少「技能工作流」章节 | AI 无法理解执行顺序 |
| P0 | 硬编码 `.qoder/config.json` | 无法在其他 Agent 工具运行 |
| P0 | 描述限定「仅在 Qoder 中可用」 | 直接丧失跨平台能力 |
## 🚨 P1 结构性问题
| 优先级 | 问题 | 影响 |
|--------|------|------|
| P1 | SKILL.md 1280 行，核心逻辑被淹没 | 维护困难，易出错 |
| P1 | migrate_logic.md 等参考文档混入根目录 | 结构混乱 |
| P1 | utils.py 在根目录，未脚本化 | 确定性操作依赖 LLM 推理 |
| P1 | config.yaml 散落在根目录 | 配置管理不规范 |
| P1 | template.sql 未归入 assets | 资源管理混乱 |
| P1 | 逻辑重复：「使用说明」「操作步骤」「执行流程」三处重复 | 修改时需改多处 |
## 🚨 P2 逻辑性问题
| 优先级 | 问题 | 影响 |
|--------|------|------|
| P2 | 缺少边界条件说明（大数据量、网络中断） | 生产环境易失败 |
| P2 | 异常处理描述模糊「适当重试」 | 无法执行 |
| P2 | 步骤之间缺少前置条件说明 | 执行者无所适从 |
## 🚨 Agent 兼容性问题
| 检查项 | 状态 | 问题 |
|--------|------|------|
| 工具名称绑定 | ❌ | 硬编码「Qoder」|
| 路径耦合 | ❌ | 硬编码 `.qoder/` 路径 |
| API 依赖 | ⚠️ | 依赖 Qoder 特有的环境变量 |
深度分析：为什么这个 SKILL 会「时灵时不灵」？
Skill Review 不仅列出问题，更分析了根因：
1. 结构混乱导致认知负担过重
1280 行的 SKILL.md，核心工作流被淹没在细节中 AI 每次执行都需要从大量无关信息中提取关键步骤 结果：执行不稳定，「有时能跑，有时跑不通」
2. 脚本与 LLM 未分离
utils.py 放在根目录，但 SKILL.md 里还在用文字描述相同逻辑 AI 有时调用脚本，有时自己推理，行为不一致 结果：「换个环境就报错」
3. 跨平台兼容性被忽视
硬编码 Qoder 特有路径和描述 在其他 Agent 工具中直接无法运行 结果：「别人没法接手」
4. 逻辑断层导致执行失败
没有明确的「技能工作流」章节 边界条件缺失，大数据量场景未覆盖 结果：生产环境「跑着跑着就挂了」
优化方案：从「病危」到「健康」
Skill Review 输出可执行的修复方案：
## 第一阶段：紧急抢救（解决 P0 问题）
1. 添加「技能工作流」章节
- 梳理核心步骤：数据导出 → 格式转换 → 数据导入 → 验证
- 每个步骤独立成节
2. 修复跨平台兼容性
- 删除「仅在 Qoder 中可用」描述
- 将 `.qoder/config.json` 改为参数化配置路径
- 使用环境变量或相对路径替代硬编码
## 第二阶段：结构重组（解决 P1 问题）
1. 创建标准目录结构
mkdir -p references assets scripts
2. 迁移参考文档
mv migrate_logic.md references/workflow.md
mv migrate_logic_detail.md references/advanced.md
mv config.yaml references/config-example.yaml
3. 迁移资源文件
mv template.sql assets/
4. 脚本化确定性操作
mv utils.py scripts/data_validator.py
完善 scripts/run.sh 为完整执行脚本
5. 精简 SKILL.md
- 保留核心工作流（< 300 行）
- 将详细说明移至 references/
- 合并重复的「使用说明」「操作步骤」「执行流程」
## 第三阶段：逻辑完善（解决 P2 问题）
1. 补充边界条件
- 大数据量：分批处理，每批 10000 条
- 网络中断：重试 3 次，间隔 5 秒
- 数据冲突：跳过或覆盖策略
2. 明确异常处理
- 将「适当重试」改为「失败时重试 3 次」
- 添加具体的错误码和对应处理
执行修复后的蜕变
告诉 AI「确认优化」后，SKILL 自动执行修复：
修复后的目录结构（清晰规范）：
data-migrator/
├── manifest.json # 元数据
├── SKILL.md # 268 行，核心工作流清晰
├── references/
│ ├── workflow.md # 详细工作流说明
│ ├── advanced.md # 高级用法
│ └── config-example.yaml # 配置示例
├── assets/
│ └── template.sql # SQL 模板
└── scripts/
├── run.sh # 主执行脚本
├── data_validator.py # 数据验证（原 utils.py）
└── batch_processor.py # 新增：分批处理脚本
SKILL.md 结构（一目了然）：
---
name: data-migrator
description: 数据库迁移工具，当用户需要迁移数据时触发
---
## 技能工作流
数据导出 → 格式转换 → 数据导入 → 验证
### 数据导出
从源数据库导出数据...
### 格式转换
转换为目标格式...
### 数据导入
导入目标数据库...
### 验证
校验数据完整性...
## 使用说明
...简要说明...
## 参考资料
- 详细工作流 → references/workflow.md
- 高级用法 → references/advanced.md
- 配置示例 → references/config-example.yaml
效果对比
开发者反馈：「像换了一个 SKILL，终于能放心交给别人用了。」
五、自由度匹配原则：什么时候该脚本化？
Skill Review 提出了一套「自由度匹配原则」，帮助开发者判断何时应该将逻辑沉淀为脚本：
脚本化信号：
相同代码反复写 LLM 多次推理相同逻辑 操作步骤固定、易出错 需要高可靠性
这让 SKILL 的设计从「凭感觉」变成「有标准」。
六、行业意义：从「能用」到「好用」的质量跃迁
这标志着 SKILL 开发从「野蛮生长」走向「工程化」。
七、最佳实践：如何用好 Skill Review？
场景一：新 SKILL 开发
SKILL 开发完成后，直接告诉 AI：
"「帮我审查一下这个 SKILL」
AI 会自动分析目录结构、检查逻辑完整性、输出优化建议。确保「出生」就是健康的。
场景二：存量 SKILL 治理
对已有 SKILL 进行质量盘点：
"「审查所有 SKILL，输出质量报告」
AI 会逐个检查，标记 P0/P1/P2 问题，建立 SKILL 质量基线。
场景三：持续优化
发现 SKILL 执行效果不佳时：
"「这个 SKILL 执行有问题，帮我审查优化」
AI 会结合执行反馈，定位是结构问题还是逻辑缺陷，给出针对性优化方案。
源码分享
原创不易，如果这个SKILL能解放你的生产力，欢迎购买我的SKILL合集，我会把所有实用的SKILL都打包好给你，里面的每个SKILL都是鹿Sir精心打磨过的~
网盘链接：
https://pan.baidu.com/s/1HVwxzBq5dGD8PHoPivDupg
提取码（即将失效）：