SKILL.md
skill-qc — 技能质控（L0 否决 + L1~L4 四层质控 + 实测验证）
Overview
对任意技能包执行技能质控，产出量化质控报告。方法论融合三大来源：
- Anthropic skill-creator 评估框架（魔搭 Skills 中心收录，40.6k 安装）——提供"实测验证"维度（触发准确性 / 真实任务 A/B / Token ROI），回答"文档正确之外，技能实际有没有用"
- 电子病历质控体系（卫健委《病案管理质量控制指标(2021版)》、地方标准 38 条单项否决、协和内涵质控标准、川大学报 2023 规则库分类）——提供"内容语义质量 + 逻辑质量"的制度化检查
- darwin-skill 自主优化闭环（Karpathy autoresearch 思路：8 维度 rubric + hill-climbing 迭代 + git ratchet）——提供"评估 → 修复 → 复查"的闭环纪律，移植为 skill-qc 四类增强机制（测试样例前置 / 独立评分 / 棘轮门禁 / 单点改动归因），详见「质控增强机制」一节
适用时机（触发本技能）：
- 发布 / 更新 / 分享 / 导入任何技能前
- 用户报告技能存在错误、矛盾、遗留旧结论后全面复查
- 认知升级（平台/接口/行为变化）后复查全文
- 技能被指出"只管追加没管前面逻辑"等系统性问题时
- 需要质控方法论指导（形式/内涵双层、缺陷分级、PDCA 闭环、技能评估）时
目录
- [质控流程（L0~L4）](#质控流程必须按序执行)
- [L0 单项否决](#l0-单项否决一票否决先查底线) - [L1 形式质控](#l1-形式质控结构化可脚本化) - [L2 内涵质控](#l2-内涵质控语义层需独立证据--判断) - [L3 分级闭环](#l3-分级闭环量化--持续改进) - [L4 实测验证](#l4-实测验证anthropic-框架回答技能实际有没有用)
- [执行步骤](#执行步骤)
- [Resources](#resources)
质控流程（必须按序执行）
L0 单项否决（一票否决，先查底线）
存在任一条 → 直接判不合格，停止评分，先修复：
- 用户明确纠正过的错误结论再次出现（如"禁止调用"类已被纠正的表述残留）
- 敏感凭据泄露：账号/密码/令牌/api_key/身份证/手机号出现在技能文件中
- 断言无任何证据锚点：关键结论无 L1~L4 任一证据来源
- 引用指向不存在的文件/章节：
references/XX.md无此文件，或带章节名引用但目标无此章节 - 危险指令：含删除生产数据、绕过安全校验等危险操作指导
模仿电子病历"先查单项否决项，再评内容"——底线缺陷一票定级，避免扣分掩盖大问题。
L1 形式质控（结构化，可脚本化）
| 检查项 | 方法 |
|---|---|
| 结构完整性 | SKILL.md 资源索引/方向表列出的文件 vs 实际文件；改名/删除后同步 |
| 格式规范 | frontmatter 字段、标题层级、表格列对齐、代码块闭合、常见错别字（语义判定识别形近字；可选脚本辅助 --typos） |
| token 一致性 | 端口、端点、版本号、概念词在各文件表述一致（脚本可查） |
| 引用存在性 | 提取全文被引文件名，与实际文件比对（grep/脚本） |
| 命名规范（Anthropic） | 技能名 ≤64 字符、小写+数字+连字符、动名词形式（processing-pdfs 而非 pdf-tool） |
| 描述规范（Anthropic） | description ≤1024 字符、第三人称、三要素=功能+触发词+范围（可选排除项） |
| 结构规范（Anthropic） | SKILL.md ≤500 行、引用仅一层深、>100 行加 TOC、正斜杠路径 |
| 反模式（Anthropic） | 选项过多无建议 / 时效性信息（写死日期条件）/ 术语不一致 / 深层嵌套引用 |
| 表述静态化（禁改动日志口吻） | 跨技能引用写"详见/见"；禁改动日志口吻全形态——跨引用动作动词、日期式"借鉴/新增"、括号式新增标注、括号日期式记录标注（"（日期+实测/用户确认/复盘…）"）与裸"日期+状态词"（记录归 90 日志）；形态族是 L2 语义判定维度（见 01「表述静态化」），质控专用文件豁免；脚本仅在 --changelog 传入自定义正则族时辅助 |
| 行尾 LF（无 CR） | 全包文本文件统一 LF；发布到外部平台（ModelScope 魔搭、Claude Code、OpenClaw 等 Anthropic Agent Skills 协议消费方）前必查——平台 SKILL.md 解析器不容忍 \r，frontmatter 的 ---/字段会被解析坏，直接判「格式不对」；PyYAML 本地校验通过 ≠ 平台通过（Python 容错 CRLF）；打包后从 zip 内读回再验。脚本可查（qc_check.py） |
| 描述触发词预算平衡 | description 在长度上限内，触发词按功能「重要度×口语化程度」分配篇幅；新增功能触发词不得挤掉既有功能；优先保留用户口语说法，开发术语进正文不进触发词；方向速记细节点到为止，细节放 references |
| description 无注释截断（YAML 空格+#） | frontmatter 的 description 不得含「空格 + #」——YAML plain scalar 中 # 前有空格即被当注释起始，description 从该处静默截断（yaml.safeload() 不报错、字段仍在，但触发词全丢、技能几乎不命中）；发布前用 yaml.safeload() 对照解析后/原始长度，解析后异常短即截断。脚本可查（qc_check.py）+ QC 代理用 yaml 复核 |
| 时效性 | 结论标注证据时间/平台版本；接口或行为变更后旧结论是否已更新 |
L2 内涵质控（语义层，需独立证据 + 判断）
核心原则（防退化）：L2 所有检查项都是单一语义问题，不是分类问题。不分解维度、不枚举关键词。 每个检查项只保留"判定该条是否成立"的唯一问题——质控代理（LLM）通读后逐句自问该问题，靠语义理解判断，不依赖任何维度拆分或关键词白名单。历史反复证明：维度分解和关键词示例永远枚举不全（L2-8 从五维一路补到六维仍漏某行业领域术语），每次补一维就是打地鼠。L2 只认语义，不认规则。
- 断言溯源（防"用错误验证错误"）：每一条关键断言必须有独立证据（源码+行/实测日期/用户原话）；事实清单条目禁止从旧文档复制
- 概念准确性：表述精确无歧义；用户纠正过的措辞不得残留
- 分类归属：内容放置符合使用者认知模型；章节主题纯粹
- 逻辑自洽：同一概念在不同文件表述一致；新旧结论不得矛盾共存
- 引用正确性：带章节名引用→核对目标章节存在；引用指向内容与目标匹配；相对引用（见下文）在重排后复核；文件改名后旧名引用清零
- 拷贝粘贴检测：通读识别相邻章节/跨文件的雷同表述（换词重写的语义雷同 grep 查不出）；脚本的相同段落检测仅作辅助线索（对应病历"文书重复质控"）
- 多源一致：同一事实在多处出现时，强制"主源+派生"模式——派生处标注引用关系；主源改动后派生处必须同步
- 去项目化（通用技能分享前必查）：通读全包、代入完全不相识的外部读者逐句自问一个唯一问题："换一个其他行业/项目/公司的用户来读，这句话会因为绑定了特定上下文而错误、费解或无关吗？"——语义判"是"即 P1。不分解维度、不枚举关键词、不设白名单——所有"绑定"类型（IP/项目名/行业词/库名/决策逻辑/本地路径/内部ID……）同归这一条判定。维度分解和关键词示例已被证伪（每次用户发现新类型就补维度→永远补不完），语义理解是唯一出路。沉淀自 nexent-integration 多次去项目化改造（用户先后指出 IP/项目名/本部署/库名/应用决策/行业术语等残留，每次新增维度而非根治）；元描述句不豁免——「范本 = …」「参考实现（…）」等自我介绍句的行业定语同属绑定（「某医院运营数据平台」须匿名为纯功能名「运营数据平台」），匿名化执行闭环（判可疑 → grep 定位同型 → 替换纯功能名 → 回读上下文 → 零残留）见 02 L2-8。
- 跨技能引用规范（L2-9）：领域正文（SKILL.md 主体 + 使用型 references，质控专用 90- 文件豁免）不得引用其他技能的内部编号/层级（如"遵循 skill-qc L2-8"）作为规则依据——使用者无从理解，属分类错位；亦不得含质控/创作元规则声明（如"示例标识符约定"——属质控范畴，示例内"以你的实现为准"标注已足够）；跨技能引用仅允许①质控专用文件指向 skill-qc 执行质控、②功能性方向指引（如"协议层见对接平台的集成技能"）两类
决策规则（发现矛盾时）：
- 高置信 → 自修：矛盾一方有 L1 用户原话 / L2 源码实证 / L3 端到端实测任一硬证据 → 直接修复并记录
- 低置信 → 请示用户：仅 L4 推断 / 两解都合理 / 涉及分类·命名·业务语义（使用者认知模型）→ 列出双方+证据+倾向，请用户裁决
证据分层：L1 用户原话 > L2 源码实证 > L3 端到端实测 > L4 工程推断（必须标注"推断"）
L3 分级闭环（量化 + 持续改进）
- 缺陷分级：
- P0（否决级）：对应 L0 单项否决，出现即不合格 - P1（严重）：概念错误、分类归属错误、逻辑矛盾、引用指向错误内容 → 必须修复后发布 - P2（轻微）：格式、措辞、token 不一致、结构瑕疵 → 可记录待优化
- 评分卡（参考病历百分制）：
- 满分 100；L0 触发直接 0 分不合格 - L1 形式质控 25 分（结构 8 / 格式 4 / token 5 / 引用存在 4 / 命名描述结构规范 4） - L2 内涵质控 45 分（溯源 10 / 概念 8 / 归属 8 / 自洽 8 / 引用正确(含跨技能) 6 / 拷贝+多源 5） - L3 闭环 10 分（缺陷分级 5 + 记录完整 5） - L4 实测验证 20 分（触发准确性 10 / 真实任务 A/B 5 / Token ROI 5） - 等级：≥90 甲（优秀）/ 75~89 乙（良好，修复 P1 后发布）/ <75 丙（不合格）
- PDCA 闭环：本次发现的问题 → 记入技能内"已发现问题表" → 更新事实清单 → 下次质控先复查是否复发 → 缺陷趋势
- 质控报告输出：按
references/03-qc-report-template.md模板输出，含：L0~L4 逐层结果、缺陷清单（级别+位置+证据）、评分卡、修复建议
L4 实测验证（Anthropic 框架，回答"技能实际有没有用"）
本层借鉴 Anthropic skill-creator 评估框架，与 L1~L3 的"文档正确性"互补——文档全对不代表技能有效。
执行前置（借鉴 darwin Phase 0.5，见「质控增强机制·增强 1」）：L4 评分前必须先在「执行步骤 6」设计测试样例并请用户确认，否则"实测表现"无打分依据。
- 触发准确性（评估 description 是否"该触发时触发、不该触发时不触发"）：
- 设计 ≥20 条测试查询：一半正例（应触发）+ 一半负例（不应触发，且要"相似但不触发"如"写代码"vs"审查代码"） - 正例覆盖中英文变体 + 同一任务不同说法 - 独立子代理模拟真实触发路径，逐条判定 TRIGGER / NO_TRIGGER - 计算 Recall = 正例命中率、Precision = 负例排除率；通过标准 Recall ≥90% 且 Precision ≥90%，否则需优化 description
- 真实任务表现（有技能 vs 无技能 A/B）：
- 设计 ≥4 个代表性场景（含简单 + 困难/边缘案例——困难场景是技能 ROI 最高处） - 每个场景分别"加载技能"和"不加载技能"各跑一次，同一任务 - 定义技能专属质量指标（审查类看信噪比/误报率；生成类看结构化方法论符合度；文档类看完整度/准确性） - 量化差异：有技能显著优于无技能 → 技能有价值；无差异 → 技能可能无效 - 洞察：基础能力（找 bug/覆盖路径）模型本来就会，技能的差异化价值在方法论层
- Token 成本效益（ROI）：
- 估算输入成本：SKILL.md 大小 + 触发场景的 reference 文件大小 - 对比输出规模：有/无技能的输出 token 差异 - ROI = 节省的开发时间价值 / 额外 token 成本（Anthropic 实测 go-code-reviewer 为 347 倍）
L4 为实测层，需要可运行环境与子代理；无法执行时（纯文档技能/无运行环境）在报告中标注"L4 未执行"，评分按 L1~L3 折算（L4 分项计为 0 并注明）。
质控增强机制（借鉴 darwin-skill 自主优化闭环）
借鉴
darwin-skill（自主优化闭环）的闭环纪律，skill-qc 内置四类增强机制。两者定位不同：darwin 是「迭代优化器」（hill-climbing 只保留改进），skill-qc 是「质量评估器」（L0~L4 判级）；以下把 darwin 中可复用的闭环纪律移植到 skill-qc 的「评估 → 修复 → 复查」环节。完整映射见references/01-qc-methodology.md§「借鉴 darwin-skill」。
增强 1：测试样例前置设计 + 用户确认（借鉴 darwin Phase 0.5）
- L4 实测前必须先设计测试样例：针对被评技能设计 ≥4 条代表性触发查询 / 任务场景（覆盖 happy path + 1 个边缘/歧义场景），展示给用户确认后再进入 L4 评分。
- 测试样例的质量决定评估方向是否正确——没有样例，"实测表现"维度无法打分（纯文档技能至少做 L4 触发准确性 20 条查询，见 L4.1）。
- 若子代理/运行环境不可用，L4 退化为「干跑验证」：模拟典型 prompt 的执行思路判断流程合理性，报告中标注
dry_run（同 darwin 原则，不跳过该维度）。
增强 2：独立评分原则（借鉴 darwin 设计哲学 #4）
- L4 实测必须用独立子代理评分：带技能跑 vs 不带技能 baseline 对比，避免「改完自己评」的同源偏差（与作者同源同错会失效）。
- L1/L2 自修也要刻意独立视角：自修缺陷时，修复后换一个角度复核（如 token 一致性、概念准确性），不在一个上下文里「改完直接认定对」。
增强 3：棘轮门禁（借鉴 darwin git ratchet）
- 修复缺陷后必须重跑 QC（至少 L0~L3），只有「分数不降 且 P0/P1 清零」的版本才保留。
- 无效改动（修复后引入新问题 / 分数下降）回退，并在「已发现问题表」记录失败尝试。
- 与 L3 PDCA 配合：本次修复 → 重测 → 对比分数 → 保留或回退 → 趋势统计。
增强 4：单点改动归因（借鉴 darwin 约束 #3）
- 修复缺陷时一次只改一个维度/区域（如只改 L2 概念准确性，或只改某文件的 token 一致性），便于归因「哪次改动解决了哪个缺陷」。
- 禁止一轮内同时改结构 + 内涵 + 描述——多变更混合会导致无法判断修复有效性。
执行步骤
- 读技能结构：
find <skill-dir> -type f列出全部文件 - L0 单项否决：逐条查 5 类底线缺陷（凭据泄露重点 grep 密码/token/key）
- L1 形式质控：优先跑脚本
scripts/qccheck.py <skill-dir>（自动查结构完整性/引用存在性/token 一致性/重复段落/命名描述规范/行尾 LF（L1-15）），再人工补格式、反模式与时效。⚠️ 错别字与改动日志口吻本质是语义判定（形近字、口吻需语义理解），默认由 L2 通读负责——qccheck.py 不内置词表，仅在--typos/--changelog传入自定义词表时才做机械辅助。发现新的日志口吻形态/错字时，正确反应是升维到语义判断（纳入 L2 通读的形态族判断范围），不陷入"漏检→补词"的死循环 - L2 内涵质控（语义通读，禁用 grep 判定）：先全包通读 SKILL.md + 全部 references + scripts 全文（不靠 grep 跳读）→ 代入"陌生读者"红队视角，逐句自问语义问题（去项目化核心问题 + 各 L2 检查问题）→ 抽取断言对照事实清单（若技能内有 90-qc 类清单）逐条核验证据 → 查概念/归属/自洽/引用正确性 → 主动查拷贝与多源一致。grep 仅用于 L1 形式检查；L2 内容判定必须靠语义理解
- L3 分级闭环：缺陷分级 → 评分卡 → 输出报告 → 修复建议
- L4 前置（借鉴增强 1）：设计 ≥4 条代表性触发查询/任务场景（覆盖 happy path + 1 个边缘/歧义场景），展示用户确认后再评 L4；纯文档技能至少设计 20 条触发查询（L4.1）。子代理/环境不可用则退化为干跑验证并标注
dry_run - L4 实测验证：子代理跑 A/B（带技能 vs baseline，独立评分见增强 2）→ 计算 Recall/Precision/ROI → 判定是否有效
- 修复 + 棘轮复查（借鉴增强 3/4）：按 P0→P1→P2 顺序、单点改动归因修复；修复后重跑 QC，仅保留「分数不降且 P0/P1 清零」的版本
- 汇报：向用户给出质控报告 + 待用户确认的修复项（涉及认知模型/分类/业务语义的低置信矛盾必须请示）
本技能自身同样适用本方法论：每次更新 skill-qc 后须按 L0~L4 自检（见
references/90-qc-ground-truth.md）。
Resources
references/01-qc-methodology.md— 质控方法论详解（Anthropic 评估框架 + 电子病历体系 + darwin-skill 闭环 三大来源、设计依据、边界声明）references/02-qc-checklist.md— 逐条可勾选检查清单（L0~L4 全项，执行时对照；L1 含行尾 LF（L1-15）/描述触发词预算（L1-16）/description 注释截断（L1-17）；L2 含跨技能引用规范（L2-9））references/03-qc-report-template.md— 质控报告输出模板 + 评分卡references/90-qc-ground-truth.md— 质控专用：本技能自身的核心结论/事实清单（防"用错误验证错误"），正常使用不读，仅自检时打开scripts/qc_check.py— 形式质控自动化脚本（结构完整性 / 引用存在性 / token 一致性 / 重复段落检测 / 命名描述结构规范 / 行尾 LF 检查（L1-15，发布外部平台前必查） / description 注释截断检测（L1-17，含「空格+#」即报）；跨技能引用自动豁免（技能名/UI 技能/配套技能 references/xx.md属 L2-9 允许的功能性方向指引，本目录不校验）；错别字与改动日志口吻检查默认不内置词表，仅--typos/--changelog传入自定义词表时执行，语义兜底归 L2 通读）