Skill Sifter — AI Agent Skill 评估框架

用途

对任意 Skill 文档（SKILL.md）进行系统化质量评估，输出结构化评估报告，并给出可操作的优化建议。

适用场景：
- 评审新编写的 Skill 是否达到可用标准
- 诊断已有 Skill 为何效果不好
- 对比多个 Skill 方案选择最优
- 在发布前做质量门禁检查

核心评估模型：四层递进分析法

┌─────────────────────────────────────────────┐
│  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 分钟完成基础健康度扫描。

Layer 1: 定位分析 (Positioning)

目标

在深入细节之前，先建立"评估参照系"。定位不同，评判标准完全不同。

检查要素

1.1 元信息完整性

从 SKILL.md 的 frontmatter（YAML 头部）提取以下信息：

1.2 调用身份判定

根据 user-invocable 和文档上下文判断 Skill 的调用者类型：

调用者类型:
  ├── 用户直接调用 (user-invocable: true)
  │   → 评估标准偏向: 指令清晰度、触发语设计、输出友好性
  │
  ├── 其他 Skill 调用 (user-invocable: false)
  │   → 评估标准偏向: 接口契约清晰度、输入输出规范、错误码定义
  │
  └── 混合调用 (两者都有)
      → 需要同时满足两类标准，文档应有分层

1.2.1 Skill 类型识别

根据文档内容判定 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 权重应上调（需要展示分析过程）

1.3 约束域分析

识别 Skill 的操作边界：

1.4 定位判定输出

完成本层后应形成一句话定位：

> [Skill名称] 是一个 [调用类型] 的 Skill，通过 [工具集] 完成 [核心功能]，服务于 [目标场景]。

Layer 2: 结构审计 (Structure Audit)

目标

将文档按功能模块切分，计算各模块占比，识别结构失衡。

2.1 内容分区与标注

将 SKILL.md 按以下标准分类标注，并统计每类的行数占比：

2.2 结构健康度判定

健康信号:
  ✅ INSTRUCTION 占比最高（>25%）→ Skill 以操作指导为核心
  ✅ SCHEMA + INSTRUCTION 合计 > 50% → 核心内容充实
  ✅ 没有单一类别 > 40% → 内容分布均衡

警告信号:
  ⚠️ INSTRUCTION 占比 < 15% → "有数据定义，没行动指引"
  ⚠️ CODE 占比 > 25% → 代码应抽取为独立文件
  ⚠️ SCHEMA 占比 > 40% → 数据定义过重，建议分层
  ⚠️ ERROR 占比 = 0% → 完全没有异常处理指引

危险信号:
  🔴 INSTRUCTION 占比 = 0% → Skill 不可用，Agent 不知如何操作
  🔴 单一类别 > 60% → 文档严重失衡
  🔴 META 缺失 → 无法被正确识别和加载

2.3 信息密度评估

信息密度 = 不可删除内容行数 / 总行数

  > 80%  → 高密度，紧凑优质
  60-80% → 中密度，有优化空间
  40-60% → 低密度，需要精简
  < 40%  → 臃肿，需大幅重构

判定"可删除"的标准：
- 与其他段落信息重复
- Agent 无法操作的内容（面向人类的流程描述）
- 未被引用的完整代码块
- 过时的迁移说明/历史兼容性内容

Layer 3: 缺陷检测 (Defect Detection)

目标

从三个正交维度系统性扫描问题，确保无遗漏。

3.1 维度 A — 一致性检查 (Consistency)

> 核心问题：文档内部各段落之间是否自洽？

A1. 路径一致性

检查方法:
1. 提取目录结构定义中的所有路径
2. 提取代码/示例中引用的所有路径
3. 逐一比对，标记不匹配的路径

常见问题:
- 结构图用了新路径，代码仍用旧路径（迁移未完成）
- 目录名在不同位置拼写不一致（phases vs context）
- 文件名在结构定义和代码中不同（manifest.yml vs project.yml）

A2. 变量/符号一致性

检查方法:
1. 提取代码中所有变量定义
2. 提取代码中所有变量引用
3. 标记：已引用但未定义的变量（NameError 风险）
4. 标记：已定义但未引用的变量（冗余代码）

常见问题:
- 重构后变量名改了一半（MEMORY_DIR 未定义但被引用）
- 函数签名与调用处参数不匹配

A3. Schema 与代码一致性

检查方法:
1. 提取 Schema 中定义的所有字段
2. 提取代码中实际读写的字段
3. 标记：Schema 有但代码不处理的字段（幽灵字段）
4. 标记：代码处理但 Schema 未定义的字段（隐含字段）
5. 检查默认值是否覆盖所有 Schema 必需字段

常见问题:
- Schema 定义了 20 个字段，默认初始化只设置了 5 个
- 代码中硬编码了 Schema 未声明的字段名

A4. ID/编号策略一致性

检查方法:
1. 找出所有实体的 ID 生成逻辑
2. 验证各实体是否使用统一策略
3. 检查 ID 冲突/间隙处理

常见问题:
- 不同实体用不同 ID 策略（计数器 vs 文件计数）
- 删除记录后 ID 会冲突
- 无并发安全保障

一致性评分标准

3.2 维度 B — 必要性检查 (Necessity)

> 核心问题：每段内容是否不可替代？删除后是否影响 Skill 被正确调用？

逐块评估方法

对文档中每个内容块（以二级/三级标题为单位）执行：

必要性评估流程:
  │
  ├── Q1: 删除这段后，Agent 能否完成核心操作？
  │   ├── 不能 → 标记为 [必需]
  │   └── 能 → 继续 Q2
  │
  ├── Q2: 这段信息是否在其他地方重复出现？
  │   ├── 是 → 标记为 [重复]，建议删除较弱的版本
  │   └── 否 → 继续 Q3
  │
  ├── Q3: 这段内容的目标受众是否与 Skill 的调用者匹配？
  │   ├── 不匹配 → 标记为 [错配]，建议移至外部文档
  │   └── 匹配 → 继续 Q4
  │
  └── Q4: 这段内容的使用频率如何？
      ├── 每次调用都需要 → 标记为 [核心]
      ├── 偶尔需要 → 标记为 [可选]，考虑外部引用
      └── 几乎不需要 → 标记为 [冗余]，建议删除

分类标记

3.3 维度 C — 适配性检查 (Fitness)

> 核心问题：文档是否为正确的受众、用正确的语言、覆盖正确的场景？

C1. 语言适配

检查矩阵:

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()"

评分:
  所有操作都用工具语言描述    → 语言适配度: 高
  混合使用工具语言和编程语言  → 语言适配度: 中
  全部使用编程语言描述       → 语言适配度: 低

C2. 粒度适配

检查方法: 遍历 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%                       → 粒度适配: 不可用

C3. 场景覆盖度

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（不适用）的场景不计入分母。

Layer 4: 优化建议 (Optimization)

目标

基于前三层的发现，生成可操作的优化方案。

4.1 优化优先级矩阵

               影响面
          小          大
        ┌─────────┬─────────┐
  高    │  P2     │  P1     │
成本    │ 快速修复 │ 立即做   │
效益    ├─────────┼─────────┤
  低    │  P4     │  P3     │
        │ 可忽略  │ 规划做   │
        └─────────┴─────────┘

P1 (立即做):  影响大+效益高 → 如: 添加 Agent 操作指令
P2 (快速修复): 影响小+效益高 → 如: 修复变量引用 bug
P3 (规划做):  影响大+效益低 → 如: Schema 分层重构
P4 (可忽略):  影响小+效益低 → 如: 删除研究方向备注

4.2 六大标准优化方向

方向 1: 补充 Agent 操作手册 (INSTRUCTION 类)

触发条件: Layer 2 中 INSTRUCTION 占比 < 15%

优化模板:
  ## [操作名称]
  **触发条件**: [什么时候执行这个操作]
  **前置检查**: [执行前需要确认什么]
  **步骤**:
  1. [工具] [具体路径/参数] → [预期结果]
  2. [工具] [具体路径/参数] → [预期结果]
  3. ...
  **成功标志**: [如何判断操作成功]
  **失败回退**: [失败时做什么]

每个核心功能至少覆盖一个操作手册条目。

方向 2: Schema 分层 (SCHEMA 类)

触发条件: 任何 Schema 定义超过 30 行，或包含 Agent 无法填充的字段

分层策略:
  核心层 (Core):
    - 只包含 Agent 必须/能够填充的字段
    - 所有字段有明确默认值
    - 行数控制在 15 行以内

  扩展层 (Extended):
    - 高级场景的额外字段
    - 以外部模板文件引用
    - 标注哪些需要人工输入

方向 3: 代码外置 (CODE 类)

触发条件: 嵌入代码超过 50 行

处理方式:
  - 完整脚本 → 移至独立文件（如 scripts/memory_ops.py）
  - 在 SKILL.md 中只保留接口签名和一行调用示例
  - 如果 Agent 不能直接运行该代码，将逻辑翻译为工具调用指令

方向 4: 增加错误处理指引 (ERROR 类)

触发条件: Layer 2 中 ERROR 占比 = 0%

必须覆盖的异常类型:
  - 文件/目录不存在 → 初始化 or 报错？
  - 文件格式错误/解析失败 → 修复 or 备份重建？
  - ID/编号冲突 → 覆盖 or 跳号？
  - 状态不一致（如 index 与实际文件不符）→ 以谁为准？
  - 权限不足 → 降级处理 or 中止？

格式:
  | 异常 | 检测方式 | 处理策略 | 恢复操作 |
  |------|---------|---------|---------|

方向 5: 统一设计约定 (CONSISTENCY 类)

触发条件: Layer 3 维度 A 中发现 2+ 个不一致项

需统一的约定:
  - ID 生成策略（计数器 vs 扫描 vs UUID）
  - 文件命名规则（kebab-case vs snake_case）
  - 时间格式（ISO 8601 统一）
  - 路径引用方式（相对路径 vs 变量引用）
  - 状态枚举值（统一大小写和可选值）

方向 6: 补充 RAG/集成接口 (REFERENCE 类)

触发条件: 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
- 同一报告中的对比表格列数应一致
- 最后一行给出"核心差异"一句话总结

评估记分卡

总分计算 (100分制)

等级判定

评分校准规则

为确保评分一致性，遵循以下校准原则：

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
• 5 分钟快速检查 → templates/quick-checklist.md

输出原则：每个 Layer 的详细程度应与发现的问题数量成正比。无问题的维度可简要说明"无异常"，不必展开。

多文档体系评估

当被评估的 Skill 包含辅助文档（references/、scripts/ 等）时，需综合评估整个文档体系。

→ 详细的多文档评估流程、引用质量分级、评分调整原则，参见 references/multi-doc-evaluation.md

核心原则: SKILL.md 的自包含性仍是第一优先级。辅助文档是"加分项"而非"必需项"。

注意事项

1. 评估是手段，不是目的 — 评估报告的价值在于其优化建议的可操作性
2. 不同类型 Skill 标准不同 — 先识别 Skill 类型（§1.2.1），再应用对应的评估标准
3. "完美"不存在 — 追求的是"适度"而非"完美"，过度优化本身也是问题
4. 版本迭代 — 评估应在每个大版本变更后重新执行
5. 多文档体系 — 评估时应主动扫描辅助文档，但 SKILL.md 的自包含性始终是核心评判标准
6. 评分纪律 — 严格按校准规则计算总分，不做"印象加分"或"四舍五入优待"
7. 场景适用性 — 评估场景覆盖度前先判定适用性，避免对无状态 Skill 误扣"跨会话恢复"等分数
8. 对比公平性 — 横向对比时只对比同类型或已评估的 Skill，使用标准化对比指标