对任意 Skill 文档（SKILL.md）进行系统化质量评估，输出结构化评估报告，并给出可操作的优化建议。
适用场景：
┌─────────────────────────────────────────────┐
│ Layer 1: 定位分析 (Positioning) │
│ → 这个 Skill 是什么？给谁用？什么约束？ │
├─────────────────────────────────────────────┤
│ Layer 2: 结构审计 (Structure Audit) │
│ → 内容如何分布？比例是否合理？ │
├─────────────────────────────────────────────┤
│ Layer 3: 缺陷检测 (Defect Detection) │
│ → 三维度扫描：一致性 / 必要性 / 适配性 │
├─────────────────────────────────────────────┤
│ Layer 4: 优化建议 (Optimization) │
│ → 站在调用者角度，缺什么补什么 │
└─────────────────────────────────────────────┘
评估原则：一切以"Skill能否被正确、高效地调用"为衡量标准。
当接收到评估请求时，按以下顺序执行（详细说明见各 Layer 章节）：
Step 1 读取目标 Skill
├── Read SKILL.md 全文
├── Glob 同目录下其他关联文件
└── 记录总行数
Step 2 Layer 1 定位分析 (权重 15%)
├── 解析 frontmatter → 判定调用者类型
├── 识别 Skill 类型（[T]工具 / [O]编排 / [D]数据管理 / [K]知识）
├── 分析约束域
└── 输出一句话定位
Step 3 Layer 2 结构审计 (权重 25%)
├── 按类别标注每个段落（META/PURPOSE/INSTRUCTION/SCHEMA/EXAMPLE/CODE/REFERENCE/ERROR/CHECKLIST）
├── 计算各类别占比（参考 Skill 类型的理想占比）
└── 计算信息密度
Step 4 Layer 3 缺陷检测 (权重 35%)
├── 维度 A: 一致性检查（路径/变量/Schema/ID）
├── 维度 B: 必要性检查（逐块 Q1→Q4 决策树）
└── 维度 C: 适配性检查（语言/粒度/场景，场景先判定适用性）
Step 5 Layer 4 优化建议 (权重 25%)
├── 将发现项映射到优先级矩阵（P1-P4）
└── 对应到六大优化方向，给出具体修改建议
Step 6 输出评估报告
└── 按 templates/evaluation-report.md 模板输出
结构顺序: Executive Summary → 综合评分 → Layer 1-4 详细分析 → 优化后预期
> 💡 仅需快速检查？ → 直接使用 templates/quick-checklist.md，5 分钟完成基础健康度扫描。
在深入细节之前，先建立"评估参照系"。定位不同，评判标准完全不同。
从 SKILL.md 的 frontmatter（YAML 头部）提取以下信息：
| 字段 | 检查点 | 重要性 |
|---|---|---|
| name | 是否简洁、可识别、无歧义 | 高 |
| description | 是否一句话说清"做什么+何时用" | 高 |
| allowed-tools | 工具列表是否完整且无冗余 | 中 |
| user-invocable | 是否正确反映调用方式 | 高 |
| 语言 | description 和正文语言是否一致 | 中 |
根据 user-invocable 和文档上下文判断 Skill 的调用者类型：
调用者类型:
├── 用户直接调用 (user-invocable: true)
│ → 评估标准偏向: 指令清晰度、触发语设计、输出友好性
│
├── 其他 Skill 调用 (user-invocable: false)
│ → 评估标准偏向: 接口契约清晰度、输入输出规范、错误码定义
│
└── 混合调用 (两者都有)
→ 需要同时满足两类标准，文档应有分层
根据文档内容判定 Skill 所属类型，不同类型的评估权重和标准不同：
Skill 类型矩阵:
┌────────────────────┬───────────────────────────────────────────────┐
│ 类型 │ 特征 & 评估重点 │
├────────────────────┼───────────────────────────────────────────────┤
│ [T] 工具型 │ 执行具体操作（下载/转换/分析） │
│ (Tool-oriented) │ 评估重点: 命令精确度、参数覆盖、异常处理 │
│ │ 理想结构: INSTRUCTION >40%, SCHEMA 轻量 │
│ │ 示例: video-summarizer, sql-agent │
├────────────────────┼───────────────────────────────────────────────┤
│ [O] 编排型 │ 协调多个子 Agent/阶段完成复杂流程 │
│ (Orchestration) │ 评估重点: 阶段衔接、子Agent调用规范、产物链 │
│ │ 理想结构: INSTRUCTION >30%, REFERENCE 可偏高 │
│ │ 示例: boss-skill, project-manager │
├────────────────────┼───────────────────────────────────────────────┤
│ [D] 数据管理型 │ 管理结构化数据的增删改查和生命周期 │
│ (Data-management) │ 评估重点: Schema 严谨性、CRUD 完整性、状态流转│
│ │ 理想结构: SCHEMA 20-30%, INSTRUCTION >25% │
│ │ 示例: memory-manager, self-improving-agent │
├────────────────────┼───────────────────────────────────────────────┤
│ [K] 知识/分析型 │ 提供领域知识、分析框架或决策辅助 │
│ (Knowledge) │ 评估重点: 知识结构化程度、推理链路、输出格式 │
│ │ 理想结构: INSTRUCTION >25%, SCHEMA 可偏低 │
│ │ 示例: skill-sifter, code-reviewer │
└────────────────────┴───────────────────────────────────────────────┘
重要: 类型判定影响后续 Layer 2-4 的评估标准。
- [T] 工具型: ERROR 占比权重应上调（工具操作更容易出错）
- [O] 编排型: REFERENCE 占比标准应放宽（需要引用子 Agent）
- [D] 数据管理型: SCHEMA 占比标准应放宽（数据定义是核心）
- [K] 知识型: EXAMPLE 权重应上调（需要展示分析过程）
识别 Skill 的操作边界：
| 维度 | 分析问题 |
|---|---|
| 工具约束 | allowed-tools 能覆盖所有描述的操作吗？ |
| 文件系统约束 | 依赖的目录结构是否在文档中完整定义？ |
| 外部依赖 | 是否依赖其他 Skill、API、服务？是否明确声明？ |
| 状态依赖 | 是否假设某些文件/状态已存在？初始化流程是否覆盖？ |
完成本层后应形成一句话定位：
> [Skill名称] 是一个 [调用类型] 的 Skill，通过 [工具集] 完成 [核心功能]，服务于 [目标场景]。
将文档按功能模块切分，计算各模块占比，识别结构失衡。
将 SKILL.md 按以下标准分类标注，并统计每类的行数占比：
| 类别代码 | 含义 | 理想占比 |
|---|---|---|
| META | 元信息、头部声明 | 2-5% |
| PURPOSE | 用途、适用场景说明 | 5-10% |
| INSTRUCTION | Agent 操作指令/流程 | 25-40% |
| SCHEMA | 数据结构/格式定义 | 15-25% |
| EXAMPLE | 使用示例、调用演示 | 10-15% |
| CODE | 可执行代码/脚本 | 0-10% |
| REFERENCE | 参考资料、外部链接、研究方向 | 0-5% |
| ERROR | 错误处理/异常指引 | 5-10% |
| CHECKLIST | 检查清单、流程确认 | 3-5% |
健康信号:
✅ INSTRUCTION 占比最高（>25%）→ Skill 以操作指导为核心
✅ SCHEMA + INSTRUCTION 合计 > 50% → 核心内容充实
✅ 没有单一类别 > 40% → 内容分布均衡
警告信号:
⚠️ INSTRUCTION 占比 < 15% → "有数据定义，没行动指引"
⚠️ CODE 占比 > 25% → 代码应抽取为独立文件
⚠️ SCHEMA 占比 > 40% → 数据定义过重，建议分层
⚠️ ERROR 占比 = 0% → 完全没有异常处理指引
危险信号:
🔴 INSTRUCTION 占比 = 0% → Skill 不可用，Agent 不知如何操作
🔴 单一类别 > 60% → 文档严重失衡
🔴 META 缺失 → 无法被正确识别和加载
信息密度 = 不可删除内容行数 / 总行数
> 80% → 高密度，紧凑优质
60-80% → 中密度，有优化空间
40-60% → 低密度，需要精简
< 40% → 臃肿，需大幅重构
判定"可删除"的标准：
从三个正交维度系统性扫描问题，确保无遗漏。
> 核心问题：文档内部各段落之间是否自洽？
检查方法:
1. 提取目录结构定义中的所有路径
2. 提取代码/示例中引用的所有路径
3. 逐一比对，标记不匹配的路径
常见问题:
- 结构图用了新路径，代码仍用旧路径（迁移未完成）
- 目录名在不同位置拼写不一致（phases vs context）
- 文件名在结构定义和代码中不同（manifest.yml vs project.yml）
检查方法:
1. 提取代码中所有变量定义
2. 提取代码中所有变量引用
3. 标记：已引用但未定义的变量（NameError 风险）
4. 标记：已定义但未引用的变量（冗余代码）
常见问题:
- 重构后变量名改了一半（MEMORY_DIR 未定义但被引用）
- 函数签名与调用处参数不匹配
检查方法:
1. 提取 Schema 中定义的所有字段
2. 提取代码中实际读写的字段
3. 标记：Schema 有但代码不处理的字段（幽灵字段）
4. 标记：代码处理但 Schema 未定义的字段（隐含字段）
5. 检查默认值是否覆盖所有 Schema 必需字段
常见问题:
- Schema 定义了 20 个字段，默认初始化只设置了 5 个
- 代码中硬编码了 Schema 未声明的字段名
检查方法:
1. 找出所有实体的 ID 生成逻辑
2. 验证各实体是否使用统一策略
3. 检查 ID 冲突/间隙处理
常见问题:
- 不同实体用不同 ID 策略（计数器 vs 文件计数）
- 删除记录后 ID 会冲突
- 无并发安全保障
| 等级 | 标准 |
|---|---|
| A (优秀) | 0 个不一致项 |
| B (良好) | 1-2 个不一致项，均为低风险 |
| C (及格) | 3-5 个不一致项，或 1 个高风险项 |
| D (不合格) | >5 个不一致项，或 >2 个高风险项 |
> 核心问题：每段内容是否不可替代？删除后是否影响 Skill 被正确调用？
对文档中每个内容块（以二级/三级标题为单位）执行：
必要性评估流程:
│
├── Q1: 删除这段后，Agent 能否完成核心操作？
│ ├── 不能 → 标记为 [必需]
│ └── 能 → 继续 Q2
│
├── Q2: 这段信息是否在其他地方重复出现？
│ ├── 是 → 标记为 [重复]，建议删除较弱的版本
│ └── 否 → 继续 Q3
│
├── Q3: 这段内容的目标受众是否与 Skill 的调用者匹配？
│ ├── 不匹配 → 标记为 [错配]，建议移至外部文档
│ └── 匹配 → 继续 Q4
│
└── Q4: 这段内容的使用频率如何？
├── 每次调用都需要 → 标记为 [核心]
├── 偶尔需要 → 标记为 [可选]，考虑外部引用
└── 几乎不需要 → 标记为 [冗余]，建议删除
| 标记 | 含义 | 处理建议 |
|---|---|---|
| 🟢 [必需] | 删除会导致 Skill 不可用 | 保留并考虑增强 |
| 🔵 [核心] | 高频使用，核心价值 | 保留，放在文档前部 |
| 🟡 [可选] | 低频但有价值 | 保留或外部引用 |
| 🟠 [重复] | 与其他内容重叠 | 删除较弱版本 |
| 🔴 [错配] | 受众不对 | 移至外部文档 |
| ⚫ [冗余] | 无实际价值 | 删除 |
> 核心问题：文档是否为正确的受众、用正确的语言、覆盖正确的场景？
检查矩阵:
Agent 的操作原语 文档中的表达方式
───────────── ──────────────
Read file → 应出现: "Read {path}"
不应出现: "open(path) as f"
Write file → 应出现: "Write {path} with content"
不应出现: "f.write(data)"
Search files → 应出现: "Glob {pattern}"
不应出现: "os.listdir()"
Execute command → 应出现: "Bash: {command}"
不应出现: "subprocess.run()"
评分:
所有操作都用工具语言描述 → 语言适配度: 高
混合使用工具语言和编程语言 → 语言适配度: 中
全部使用编程语言描述 → 语言适配度: 低
检查方法: 遍历 Schema 中每个字段，问：
"Agent 是否有能力独立填充这个字段？"
├── Agent 可自主填充 → 合适
│ 例: id, title, created_at, status
│
├── Agent 可通过上下文推断 → 合适但需指引
│ 例: context, decision, consequences
│
├── 需要人类输入 → 不适合作为必填字段
│ 例: stakeholders.consulted[].input_status
│
└── 需要外部系统 → 不适合，除非声明外部依赖
例: approvals[].approved_at
粒度评分:
>80% 字段 Agent 可自主填充 → 粒度适配: 优
60-80% → 粒度适配: 良（需标注人工字段）
40-60% → 粒度适配: 差（需拆分核心/扩展）
<40% → 粒度适配: 不可用
8 类标准场景（先判定适用性，再评估覆盖度）:
┌────────────────────────────────────┬───────────┬─────────────────────┐
│ 场景 │ 是否覆盖 │ 适用性判定 │
├────────────────────────────────────┼───────────┼─────────────────────┤
│ 1. 首次初始化 (冷启动) │ □ 是 □ 否 │ ✅ 几乎所有 Skill │
│ 2. 正常操作 (CRUD 主流程) │ □ 是 □ 否 │ ✅ 几乎所有 Skill │
│ 3. 跨会话恢复 (上下文重建) │ □ 是 □ 否 │ ⚙️ 仅有状态的 Skill │
│ 4. 搜索/查询 (信息检索) │ □ 是 □ 否 │ ⚙️ 仅数据管理型 │
│ 5. 状态变更 (生命周期转换) │ □ 是 □ 否 │ ⚙️ 仅有状态流转的 │
│ 6. 异常处理 (文件损坏/缺失) │ □ 是 □ 否 │ ✅ 几乎所有 Skill │
│ 7. 容量管理 (数据增长/归档) │ □ 是 □ 否 │ ⚙️ 仅持久化数据的 │
│ 8. 多实体关联 (跨记录引用) │ □ 是 □ 否 │ ⚙️ 仅多实体的 │
└────────────────────────────────────┴───────────┴─────────────────────┘
适用性预判（根据 Layer 1 的类型识别）:
[T] 工具型: 必须覆盖 1,2,6 → 可选 3,4,5,7,8（按需标注 N/A）
[O] 编排型: 必须覆盖 1,2,3,5,6 → 可选 4,7,8
[D] 数据管理型: 必须覆盖 1,2,3,4,5,6 → 可选 7,8
[K] 知识型: 必须覆盖 1,2,6 → 可选 3,4,5,7,8
覆盖度评分 = 已覆盖的适用场景数 / 适用场景总数:
100% → 场景完备
75-99% → 基本可用，需补充
50-74% → 功能缺失，部分场景会失败
<50% → 不可用
注意: 标记为 N/A（不适用）的场景不计入分母。
基于前三层的发现，生成可操作的优化方案。
影响面
小 大
┌─────────┬─────────┐
高 │ P2 │ P1 │
成本 │ 快速修复 │ 立即做 │
效益 ├─────────┼─────────┤
低 │ P4 │ P3 │
│ 可忽略 │ 规划做 │
└─────────┴─────────┘
P1 (立即做): 影响大+效益高 → 如: 添加 Agent 操作指令
P2 (快速修复): 影响小+效益高 → 如: 修复变量引用 bug
P3 (规划做): 影响大+效益低 → 如: Schema 分层重构
P4 (可忽略): 影响小+效益低 → 如: 删除研究方向备注
触发条件: Layer 2 中 INSTRUCTION 占比 < 15%
优化模板:
## [操作名称]
**触发条件**: [什么时候执行这个操作]
**前置检查**: [执行前需要确认什么]
**步骤**:
1. [工具] [具体路径/参数] → [预期结果]
2. [工具] [具体路径/参数] → [预期结果]
3. ...
**成功标志**: [如何判断操作成功]
**失败回退**: [失败时做什么]
每个核心功能至少覆盖一个操作手册条目。
触发条件: 任何 Schema 定义超过 30 行，或包含 Agent 无法填充的字段
分层策略:
核心层 (Core):
- 只包含 Agent 必须/能够填充的字段
- 所有字段有明确默认值
- 行数控制在 15 行以内
扩展层 (Extended):
- 高级场景的额外字段
- 以外部模板文件引用
- 标注哪些需要人工输入
触发条件: 嵌入代码超过 50 行
处理方式:
- 完整脚本 → 移至独立文件（如 scripts/memory_ops.py）
- 在 SKILL.md 中只保留接口签名和一行调用示例
- 如果 Agent 不能直接运行该代码，将逻辑翻译为工具调用指令
触发条件: Layer 2 中 ERROR 占比 = 0%
必须覆盖的异常类型:
- 文件/目录不存在 → 初始化 or 报错？
- 文件格式错误/解析失败 → 修复 or 备份重建？
- ID/编号冲突 → 覆盖 or 跳号？
- 状态不一致（如 index 与实际文件不符）→ 以谁为准？
- 权限不足 → 降级处理 or 中止？
格式:
| 异常 | 检测方式 | 处理策略 | 恢复操作 |
|------|---------|---------|---------|
触发条件: Layer 3 维度 A 中发现 2+ 个不一致项
需统一的约定:
- ID 生成策略（计数器 vs 扫描 vs UUID）
- 文件命名规则（kebab-case vs snake_case）
- 时间格式（ISO 8601 统一）
- 路径引用方式（相对路径 vs 变量引用）
- 状态枚举值（统一大小写和可选值）
触发条件: Skill 声明了与外部系统集成，但未详细说明
需补充:
- 集成触发时机（创建时/更新时/定时批量）
- 数据同步格式（全量同步 vs 增量索引）
- 双向还是单向（只推送 vs 可查询）
- 失败重试策略
Step 1: 读取目标 Skill
├── Read SKILL.md 全文
├── Glob 同目录下其他关联文件
└── 记录总行数
Step 2: Layer 1 定位分析 (权重 15%)
├── 解析 frontmatter
├── 判定调用者类型
├── 识别 Skill 类型（工具/编排/数据管理/知识型）
├── 分析约束域
└── 输出一句话定位
Step 3: Layer 2 结构审计 (权重 25%)
├── 按类别标注每个段落
├── 计算各类别占比（参考 Skill 类型的理想占比）
├── 判定结构健康度
└── 计算信息密度
Step 4: Layer 3 缺陷检测 (权重 35%)
├── 维度 A: 一致性检查（逐项比对）
├── 维度 B: 必要性检查（逐块评估）
├── 维度 C: 适配性检查（语言/粒度/场景，场景需先判定适用性）
└── 汇总所有发现项
Step 5: Layer 4 优化建议 (权重 25%)
├── 将发现项映射到优先级矩阵
├── 对应到六大优化方向
├── 生成具体修改建议
└── 估算优化后的行数和效果
Step 6: 输出评估报告
└── 按 templates/evaluation-report.md 模板输出
报告结构顺序: Executive Summary → 综合评分 → Layer 1-4 详细分析 → 对比参考(如有) → 优化后预期
设计理由: 综合评分紧跟摘要，让读者在阅读详细分析前就能获得整体评价
当评估报告包含横向对比时：
标准对比指标（必选 6 项）: 总行数、信息密度、INSTRUCTION 占比、一致性等级、场景覆盖度、综合评分/等级
可选指标: 子文件生态、CODE/SCHEMA 占比
规则:
- 对比对象应为同类型或已评估过的 Skill
- 同一报告中的对比表格列数应一致
- 最后一行给出"核心差异"一句话总结
| 维度 | 权重 | 评分项 |
|---|---|---|
| 元信息完整性 | 10% | frontmatter 字段齐全、description 清晰 |
| 结构合理性 | 15% | 内容分布均衡、INSTRUCTION 占比达标 |
| 一致性 | 20% | 路径/变量/Schema/ID 策略一致 |
| 必要性 | 10% | 信息密度 >60%、无大量冗余 |
| 适配性 | 20% | 语言/粒度/场景适配 |
| 操作可执行性 | 15% | Agent 拿到文档能否直接执行 |
| 错误处理完备性 | 10% | 异常场景覆盖度 |
| 等级 | 分数 | 含义 |
|---|---|---|
| S | 90-100 | 卓越 — 可作为范例 Skill |
| A | 80-89 | 优秀 — 生产可用，小幅优化 |
| B | 70-79 | 良好 — 基本可用，需补充部分内容 |
| C | 60-69 | 及格 — 核心功能可用，多处待改进 |
| D | <60 | 不足 — 需要较大重构才能使用 |
为确保评分一致性，遵循以下校准原则：
1. 基准分计算:
- 严格按七维度加权计算，不做主观调整
- 每个维度按 1-10 分制打分，乘以权重得加权分
- 七维度加权分之和即为最终总分
2. 类型修正（基于 Layer 1 的 Skill 类型识别）:
┌────────────────┬───────────────────────────────────────────┐
│ Skill 类型 │ 维度权重修正 │
├────────────────┼───────────────────────────────────────────┤
│ [T] 工具型 │ 错误处理完备性 +5%，必要性 -5% │
│ [O] 编排型 │ 操作可执行性 +5%，必要性 -5% │
│ [D] 数据管理型 │ 一致性 +5%，错误处理完备性 -5% │
│ [K] 知识型 │ 适配性 +5%，错误处理完备性 -5% │
└────────────────┴───────────────────────────────────────────┘
注: 修正后各权重之和仍为 100%
3. 禁止的评分行为:
❌ "四舍五入加分" — 73.5 不可调为 76
❌ "生态加分" — 子文件丰富不可额外加总分
❌ "感觉加分" — 不可因"整体感觉好"而上调
✅ 子文件/生态质量通过"多文档体系评估"机制影响相关维度的单项得分
4. 边界等级判定:
- 分数恰好在边界（如 80.0）→ 取较高等级（A）
- 分数含小数 → 四舍五入到整数后判定等级
- 同一等级内不再细分（不使用 C+、B- 等标注）
评估报告按以下模板输出，按模板结构填充占位符：
templates/evaluation-report.md
templates/scorecard.md
templates/quick-checklist.md
输出原则：每个 Layer 的详细程度应与发现的问题数量成正比。无问题的维度可简要说明"无异常"，不必展开。
当被评估的 Skill 包含辅助文档（references/、scripts/ 等）时，需综合评估整个文档体系。
→ 详细的多文档评估流程、引用质量分级、评分调整原则，参见 references/multi-doc-evaluation.md
核心原则: SKILL.md 的自包含性仍是第一优先级。辅助文档是"加分项"而非"必需项"。
共 1 个版本