# Skill 质量评估详细清单

## 目录

- [维度一：元数据质量](#维度一元数据质量)
- [维度二：结构合理性](#维度二结构合理性)
- [维度三：内容质量](#维度三内容质量)
- [维度四：示例与模式](#维度四示例与模式)
- [维度五：脚本质量](#维度五脚本质量)
- [评分计算方法](#评分计算方法)
- [常见问题示例对比](#常见问题示例对比)

---

## 维度一：元数据质量（25分）

### 1.1 name 字段（5分）

| 检查项 | 分值 | 判断标准 |
|--------|------|----------|
| 格式合规 | 2 | 仅含小写字母、数字、连字符；不含 `anthropic`、`claude` 等保留字；≤64字符 |
| 语义明确 | 2 | 使用动名词形式（如 `processing-pdfs`）或名词短语，避免 `helper`、`utils`、`tools` 等模糊词 |
| 无 XML 标签 | 1 | name 中不含 `<`、`>` 等字符 |

**常见问题**：
- ❌ `my_skill`（含下划线）
- ❌ `claude-helper`（含保留字）
- ❌ `utils`（过于模糊）
- ✅ `processing-pdfs`、`code-review`、`analyzing-spreadsheets`

### 1.2 description 字段（20分）

| 检查项 | 分值 | 判断标准 |
|--------|------|----------|
| 第三人称写法 | 4 | 不含"我"、"你"、"I can"、"You can"；描述客观 |
| 包含 WHAT | 4 | 明确说明 skill 能做什么（具体能力，非泛泛而谈）|
| 包含 WHEN | 4 | 明确说明何时触发（触发场景、触发词）|
| 触发词充分 | 4 | 包含用户可能使用的多种表述方式，覆盖正式/非正式用语 |
| 适度 pushy | 2 | 对于容易 undertrigger 的 skill，description 应主动指出触发场景（"Make sure to use this when..."）|
| 无 XML 标签 | 1 | 不含 `<`、`>` 字符 |
| 长度合规 | 1 | ≤1024 字符，且非空 |

**评分说明**：
- WHAT 和 WHEN 是核心，各占 4 分
- description 是 skill 能否被调用的关键——模糊的 description 直接导致 skill 失效

**对比示例**：

❌ 差（0-2分的 description）：
```
description: 帮助处理文档
```
问题：没有说明做什么（WHAT），没有触发词（WHEN），用语模糊。

🟡 一般（10-14分）：
```
description: 分析 Excel 文件并生成报告。当用户需要处理 Excel 时使用。
```
问题：WHAT 尚可，但 WHEN 的触发词太少，缺少具体场景。

✅ 优秀（18-20分）：
```
description: 分析 Excel 电子表格、创建数据透视表、生成图表和统计摘要。当用户需要处理 Excel 文件、电子表格、.xlsx 数据、表格数据分析，或要求数据可视化时使用，即使用户没有明确提及"Excel"也应触发。
```

---

## 维度二：结构合理性（20分）

### 2.1 YAML Frontmatter（5分）

| 检查项 | 分值 | 判断标准 |
|--------|------|----------|
| frontmatter 存在 | 2 | 文件以 `---` 开头，包含 YAML 块 |
| name 字段存在 | 1.5 | frontmatter 中有 `name:` 字段 |
| description 字段存在 | 1.5 | frontmatter 中有 `description:` 字段 |

### 2.2 SKILL.md 长度（5分）

| 行数 | 得分 |
|------|------|
| ≤300 行 | 5 |
| 301-500 行 | 3-4（按比例）|
| 501-700 行 | 1-2（超出但可接受）|
| >700 行 | 0（必须拆分）|

**注意**：超过 500 行时，应将详细内容拆分到 reference 文件，SKILL.md 只保留概览和指针。

### 2.3 渐进式披露（5分）

| 检查项 | 分值 | 判断标准 |
|--------|------|----------|
| 详细内容外置 | 2 | 详细参考资料、大段示例等在单独文件，不堆在 SKILL.md |
| 引用清晰 | 2 | 在 SKILL.md 中明确指出何时读哪个文件（如"详见 [reference.md](reference.md)"）|
| 引用一级深 | 1 | reference 文件不再嵌套引用其他文件（SKILL.md → ref.md，不做 ref.md → detail.md）|

### 2.4 文件组织（5分）

| 检查项 | 分值 | 判断标准 |
|--------|------|----------|
| 目录结构清晰 | 2 | scripts/、references/、assets/ 分类合理 |
| 文件命名语义化 | 2 | 文件名描述内容（`form_rules.md` 优于 `doc2.md`）|
| reference 文件有目录 | 1 | 超过 100 行的 reference 文件顶部有目录 |

---

## 维度三：内容质量（25分）

### 3.1 简洁性（10分）

核心原则：**不解释 Claude 已知的内容**。每段内容都应通过以下测试：
- "Claude 真的需要这个解释吗？"
- "这段话值得它占用的上下文空间吗？"

| 检查项 | 分值 | 判断标准 |
|--------|------|----------|
| 无过度解释 | 4 | 不解释 LLM 普遍已知的概念（什么是 PDF、什么是 API 等）|
| 内容精炼 | 3 | 每个部分都在提供 Claude 没有的新信息或新约束 |
| 无冗余重复 | 3 | 没有重复表达同一意思的段落 |

### 3.2 时效性（5分）

| 检查项 | 分值 | 判断标准 |
|--------|------|----------|
| 无硬编码日期 | 3 | 不含"在 2025年X月之前..."等表述 |
| 旧内容处理得当 | 2 | 废弃方法用 `<details>` 折叠或标注"已废弃" |

### 3.3 术语一致性（5分）

| 检查项 | 分值 | 判断标准 |
|--------|------|----------|
| 同一概念统一术语 | 3 | 不混用 "API endpoint"/"URL"/"route"/"path" 等 |
| 术语与行业规范一致 | 2 | 使用该领域的标准用语 |

### 3.4 指令清晰度（5分）

| 检查项 | 分值 | 判断标准 |
|--------|------|----------|
| 使用祈使句 | 2 | 指令用主动语态（"Run xxx"而非"xxx should be run"）|
| 解释为什么而非只说做什么 | 3 | 提供操作的理由，帮助 Claude 在边界情况做出正确判断 |

---

## 维度四：示例与模式（15分）

### 4.1 示例质量（8分）

| 检查项 | 分值 | 判断标准 |
|--------|------|----------|
| 有具体示例 | 3 | 提供输入/输出对，而非抽象描述 |
| 示例覆盖主要场景 | 3 | 示例代表真实使用场景，不是toy示例 |
| 示例格式一致 | 2 | 输入/输出格式统一、易于阅读 |

### 4.2 工作流设计（7分）

| 检查项 | 分值 | 判断标准 |
|--------|------|----------|
| 复杂任务有步骤清单 | 3 | 多步骤任务提供可复制的清单（`- [ ] 步骤 1`）|
| 有反馈循环 | 2 | 关键操作后有验证步骤（"如果失败则..."）|
| 条件分支清晰 | 2 | 不同场景有明确的分叉指引 |

---

## 维度五：脚本质量（15分，无脚本则跳过，权重重分配）

### 5.1 路径规范（3分）

| 检查项 | 分值 | 判断标准 |
|--------|------|----------|
| 使用正斜杠 | 3 | 所有文件路径使用 `/`，不使用 `\` |

### 5.2 错误处理（6分）

| 检查项 | 分值 | 判断标准 |
|--------|------|----------|
| 有 try/except | 3 | 关键操作有异常处理，而非直接报错 |
| 错误信息有帮助 | 3 | 错误信息具体，说明问题所在和可能的解决方案 |

### 5.3 代码质量（6分）

| 检查项 | 分值 | 判断标准 |
|--------|------|----------|
| 无魔法数字 | 3 | 关键参数有注释说明取值理由（为什么超时30秒？）|
| 有清晰的函数文档 | 3 | 函数有 docstring 说明功能和参数 |

---

## 评分计算方法

### 综合得分计算

```
综合得分 = 元数据(25%) + 结构(20%) + 内容(25%) + 示例(15%) + 脚本(15%)
```

若无脚本，将脚本权重平均分配给其他维度：
```
综合得分 = 元数据(29%) + 结构(24%) + 内容(29%) + 示例(18%)
```

### 等级划分

| 综合得分 | 等级 | 建议 |
|----------|------|------|
| 90-100 | 🏆 优秀 | 可直接发布，小幅打磨 |
| 80-89 | 🟢 良好 | 有小问题，针对性修复 |
| 70-79 | 🟡 待改进 | 多个问题，需要认真优化 |
| 60-69 | 🟠 较差 | 重大问题，建议重写关键部分 |
| 0-59 | 🔴 不合格 | 建议大幅重构 |

---

## 常见问题示例对比

### 问题1：description 过于模糊

❌ 原始：
```yaml
description: 帮助用户处理各种文档相关的任务和操作
```

✅ 优化后：
```yaml
description: 从 PDF 中提取文本和表格数据、填写 PDF 表单、合并多个 PDF 文件。当用户提到 PDF 文件处理、表单填写、文档提取，或上传了 .pdf 文件需要操作时使用，即使用户没有明确说"PDF"也应触发（如"帮我把这个文件的内容提取出来"）。
```

### 问题2：SKILL.md 过度解释

❌ 原始（160+ tokens 的冗余内容）：
```markdown
## 什么是 Excel 文件
Excel 文件（.xlsx）是微软 Office 套件中的电子表格格式，广泛用于数据存储和分析。
要处理 Excel 文件，您需要安装相应的 Python 库。有多个库可以处理 Excel，
我们推荐使用 openpyxl，因为它功能强大且易于使用...
```

✅ 优化后（30 tokens，假设 Claude 已知这些）：
```markdown
## 读取 Excel

使用 openpyxl：
```python
import openpyxl
wb = openpyxl.load_workbook("file.xlsx")
```
```

### 问题3：Windows 路径

❌ 原始：
```markdown
运行：`python scripts\analyze_form.py input.pdf`
```

✅ 优化后：
```markdown
运行：`python scripts/analyze_form.py input.pdf`
```

### 问题4：时间敏感信息

❌ 原始：
```markdown
注意：2025年8月之前请使用旧版 API v1，之后切换到 v2。
```

✅ 优化后：
```markdown
## 当前方法
使用 v2 API。

<details>
<summary>旧版 v1 API（已废弃）</summary>
...
</details>
```

### 问题5：自由度设置不当

❌ 原始（提供过多选项，让 Claude 困惑）：
```markdown
您可以使用 pypdf、pdfplumber、PyMuPDF、pdf2image 或其他库...
```

✅ 优化后（提供默认值+逃生舱口）：
```markdown
使用 pdfplumber 进行文本提取。

对于需要 OCR 的扫描版 PDF，改用 pdf2image + pytesseract。
```