03
Skill Split · workflow

skill-quality-contract-and-split-audit

03-skill-quality-contract-and-split-audit.md
🧩
P1 source: claude-and-codex-sessions created: 2026-06-13
◉

WHAT IS THIS

定位

Skill 质量契约和拆分审计 workflow。它不只判断某个 SKILL.md 是否太长，还要判断它是否告诉 agent 做到什么程度算对、失败时怎么重试、跑偏经验怎么沉淀。

⚡

TRIGGERS

触发场景
▸一个 skill 同时承担分析、执行、验证、复盘，职责过多。
▸多个 skill 重复定义相同输入、输出、JSONL 或报告结构。
▸skill 只有步骤，没有验收标准。
▸运行后发现问题，但没有地方回写成 LESSONS.md 或 SOP。
▸拆分后接口不闭合，中间产物字段对不上。
↹

INPUT & OUTPUT

输入 / 产出
↘ INPUT
  • skills/*/SKILL.md
  • skills/*/LESSONS.md，如果已有。
  • docs/skill-quality-contract.md，如果已有。
  • 相关 scripts、tests、fixtures。
  • 最近失败案例或用户反馈。
↗ OUTPUT
  • Skill inventory。
  • 拆分候选列表。
  • 共享 contract 提取建议。
  • 每个 skill 的质量补丁。
  • 文档一致性测试，防止后续退化。
🪜

STEPS

编排步骤
  1. 1
    建 inventory
    统计每个 skill 的行数、触发词、职责数、输入输出、引用文件、脚本、测试。
  2. 2
    评估质量契约
    检查是否有闭环验收、反例检查、失败重试、复盘沉淀。
  3. 3
    检测职责过载
    标记同时包含规划、执行、验证、发布、复盘的 skill。判断是否应该拆成主 skill 加共享 reference。
  4. 4
    查重复协议
    找 JSON、JSONL、frontmatter、HTML report、summary 字段是否重复定义。
  5. 5
    设计共享包
    把稳定协议抽到 docs/skill-quality-contract.md、references/ 或 scripts/。
  6. 6
    补 LESSONS 入口
    每个 skill 建 LESSONS.md，记录误判样例、用户确认口径、失败重试策略。
  7. 7
    加一致性测试
    用 pytest 或脚本检查每个 skill 必须包含固定闭环段落和引用有效性。
⚙

AGENT ROLES

Agent 分工
⚙
Inventory Agent
统计结构和行数。
⚙
Duplication Agent
找重复协议和共享包候选。
⚙
Quality Agent
检查验收、反例、失败重试、复盘沉淀。
⚙
Split Planner
给出拆分边界。
⚙
Test Agent
补文档一致性测试。
·

拆分判断

拆分判断
  • skill 超过 250 行，且含多个独立产出。
  • skill 里既有任务流程，又有大量领域参考。
  • 同一段协议被三个以上 skill 复制。
  • 修改一个 skill 时必须同步改多个无关 skill。
    • 不急着拆分：
  • 长度较长但流程单一。
  • 只有一个稳定入口和一个稳定产出。
  • 大部分内容是必须完整阅读的安全规则。
✓

ACCEPTANCE GATE

验收 gate
⊘

FAILURE HANDLING

失败处理
⊘
如果拆分会破坏触发清晰度，先只抽共享 reference，不拆入口。
⊘
如果质量段落变成空话，必须绑定真实命令、字段或示例。
⊘
如果没有失败案例，不编造，先写“待沉淀”占位和记录规则。
⌘

TEMPLATE

run summary 建议字段
TEMPLATE
{
  "status": "success | partial | blocked | failed",
  "inputs": {},
  "outputs": [],
  "counts": {},
  "warnings": [],
  "blocked_reason": "",
  "next_action": ""
}