Skill Doctor

Skill Doctor —— Skill 体检诊断工具

流程

1. 读取指定 Skill 目录
2. 检查核心文件是否存在（SKILL.md、gotchas.md 等）
3. 调用脚本获取结构化报告：python scripts/analyze_skill.py --output json，得到每个检查项的得分、问题和建议
4. **针对每个低分项（ Agent 负责智能层（优化建议、用户交互、执行修改），脚本负责稳定层（评分计算、结构化输出）。脚本用法见 [scripts/analyzeskill.py](scripts/analyzeskill.py)。

九大体检项目

| 检查项 | 检查内容 | 通过标准 | |-------|---------|---------| | description检查 | 是否写成触发条件，不是功能说明 | 包含触发关键词，长度 收益为单次调用估算值，实际数值因Skill内容和使用方式而异。 > > 关于"耗时"的说明：报告中的"耗时"指设计缺陷产生的额外浪费，而非技能执行总时长。具体包括： > - gotchas 缺失 → Agent 反复踩坑调试（每次 2-5 分钟） > - 过度约束 → Agent 执行无意义的死板步骤（每步 10-30 秒） > - 脚本缺失 → Agent 每次重新编写相同代码（每次 1-3 分钟） > > 对比逻辑：优化前的数值 = 这些浪费的总和；优化后浪费归零 → ~0；"节省" = 被消除的浪费量。优化后技能执行本身仍需要时间，但不再有这些额外损耗。

优化建议呈现

生成报告后，将可优化项以清单形式展示给用户，每项包含：

### 🔧 可优化项

| # | 检查项 | 当前分 | 预期分 | 提升 | 工作量 | Token/次 | 时间/次 | 操作 |
|---|-------|--------|--------|------|--------|---------|---------|------|
| 1 | description | 50 | 90 | +40 | 低 | ~50 | — | 重写为触发条件 |
| 2 | gotchas | 40 | 90 | +50 | 中 | — | ~3min | 补充真实坑点 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... |

**接受全部优化后**：55分(D) → 85分(B)，提升30分

### 📈 综合收益（单次调用）
- Token 节省：~200/次
- 时间节省：~5分钟/次
- 踩坑规避：gotchas 补充后可避免常见错误

> **耗时统计口径**：此处"时间节省"指**设计缺陷导致的额外浪费**，非技能执行总时长：
> - gotchas 缺失 → Agent 反复踩坑调试（每次 2-5 分钟）
> - 过度约束 → Agent 执行无意义的死板步骤（每步 10-30 秒）
> - 脚本缺失 → Agent 每次重新编写相同代码（每次 1-3 分钟）
> - 优化前数值 = 浪费总和，优化后浪费归零，"节省" = 被消除的浪费量

请选择：
- **"全部接受"** — 一键优化所有项
- **"接受1,3"** — 只优化指定项
- **"跳过"** — 只看报告不做优化

用户确认后执行

1. 用户选择后，逐项修改对应文件
2. 每完成一项，标记状态
3. 全部完成后，重新运行体检生成对比报告

前后对比报告格式

## 📊 优化前后对比

| 检查项 | 优化前 | 优化后 | 变化 |
|-------|--------|--------|------|
| description | 50 (功能说明) | 90 (触发条件) | +40 ⬆️ |
| gotchas | 40 (空壳) | 90 (充实) | +50 ⬆️ |
| ... | ... | ... | ... |
| **总分** | **55 (D)** | **85 (B)** | **+30 ⬆️** |

### 📈 综合收益（单次调用）
| 维度 | 优化前 | 优化后 | 节省 |
|------|--------|--------|---------|
| Token | ~800/次 | ~600/次 | ~200/次 |
| 耗时浪费 | ~5min | ~0 | ~5min |
| 主文件 | 466行 | 75行 | -84% |

> 耗时浪费 = 设计缺陷导致的额外开销（踩坑调试、冗余步骤等），非技能执行总时长。见 [收益估算规则](#收益估算规则)。

### 已修改文件
- `SKILL.md` — 重写 description
- `gotchas.md` — 补充 5 个真实坑点

完整交互示例

见 [examples.md](examples.md) 示例9

评分等级

• A（90-100分）：优秀，遵循所有最佳实践
• B（75-89分）：良好，有少量优化空间
• C（60-74分）：合格，有明显改进点
• **D（ --output json # 步骤3：获取评分报告

python scripts/analyze_skill.py --output markdown # 可选：生成人类可读报告

脚本负责：评分计算、问题检测、等级判定（稳定层）
Agent 负责：优化建议生成、用户交互、文件修改执行（智能层）

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [liuchunming033](https://github.com/liuchunming033)
- **Source:** [liuchunming033/skill-doctor](https://github.com/liuchunming033/skill-doctor)
- **License:** MIT

Install and usage instructions live in the source repository linked above.