Skill 开发规范
Overview
skill.md 的本质是执行程序，不是交接报告。它同时被两类读者消费：AI agent（照步骤执行）与人类专家（审阅方法是否正确）。本规范解决三个核心问题——写得好：杜绝"溯源型元叙述"等污染，让 agent 拿到确定性指令，让专家一眼看穿方法对错，而非被迫考古；测得对：用三层测试验证 skill 能跑、能触发、有效果；发得稳：用门禁检查清单守住发布前的每一道关。
规范源自实际评审教训：skill 草稿中出现"原报告展示的样本外 R²≈0.52""原引用的 ΔR² 是在旧口径下测得的"等句子。这类句子让 agent 无法执行（悬空引用 + 口径含糊），也让专家被迫做三件事：判断哪句有效、寻找读者拿不到的外部报告核验、在旧口径与新口径之间当裁判。
When to Use
- 撰写一个新的 skill
- 修订、整理、诊断已有 skill
- 以面试官/审阅者身份评估他人的 skill
- 发布 skill / git push / 提交 PR 之前做自查
Don't use for: 项目交接文档、复盘报告、论文等叙事型文档——那些场景可以且应该写历史与溯源。
撰写铁律
铁律一：单一事实版本——只写事实，不写事实的来源
skill.md 里每个数字、参数、口径，就是当前唯一权威值。"这个数从哪来、何时测得、在哪个口径下测的"属于 commit message 或 references/ 文件，不进正文。
铁律二：单一现在时——只写"现在该怎么做"，不写"过去曾怎么做"
正文一律使用祈使句、确定式。版本演进史归 git log；若必须标注版本，写在 frontmatter 的 version 字段，不写进正文叙述。
铁律三：参数只留当前口径，不留新旧对账
同一参数存在多种口径时，二选一：
- 定一个口径，把定义写死在正文（如"R² 按口径 V3 计算，定义见 2.3 节"）；
- 或者写成显式分支："场景 X 用口径 A（定义…）；场景 Y 用口径 B（定义…）"，每个分支自足。
禁止出现"旧口径测得 X，新口径下会不同"这类暗示句——它告诉执行者"这个数可能不对"，却不告诉它现在该用哪个。
铁律四：溯源词警报
正文出现以下任一词汇，默认该句属于污染，需重写或删除，除非是显式场景分支： 原、旧、曾、此前、对比、改为、之前版本、原报告
铁律五：溯源分层——正文不写来源，产物必须带来源
skill.md 正文与 skill 生成的输出文件是两层，溯源规则相反：
- skill.md 正文：不写来源、不写口径历史（铁律一），这是执行层，保持干净可执行；
- 输出文件：必须带数据来源与口径说明（正文角标 + 文末溯源清单 + 数据截止日期），这是合规层，保证产物可核验。
对金融、数据类 skill 尤其如此：正文追求可执行，产物追求可追溯。
规则总表
| 规则 | 说明 |
|---|---|
| 只写事实，不写来源 | 数字/参数在 skill 中即当前权威值；来源、测时、口径归 commit message 或 references/ |
| 只写现在，不写过去 | 祈使句 + 单一现在时；版本史进 git，版本号进 frontmatter |
| 参数只留当前口径 | 要么定一个写死定义，要么写成自足的显式分支；禁止新旧口径对账句 |
| 删掉不影响执行的句子，即污染 | 用"一句话检验法"判断，见下 |
| 溯源词是警报 | 正文出现"原/旧/曾/此前/对比/改为"之一，默认重写或删除 |
| 溯源分层 | 正文不写来源（执行层），输出产物必须带来源（合规层） |
一句话检验法
对 skill.md 中每一句话执行检验：
问：这句话删掉，AI agent 执行会出错吗？
- 删掉会出错 → 保留，但重写成"现在式、确定式"（补上当前值/当前定义）
- 删掉没影响 → 删除。它是装饰或溯源，属于噪音
辅助警报：句子里含"原/旧/曾/此前/对比/改为" → 大概率污染。
脏→净示范
脏版（含溯源污染）：
原报告展示的"样本外 R²≈0.52"，原引用的 ΔR²=+0.0074 是在旧口径下测得的，本版本统一采用新口径，因此 R² 值与此前报告展示的略有差异。
净版（可执行）：
评估标准：样本外 R² 按口径 V3 计算，定义见 2.3 节。 基准模型样本外 R² = 0.52；加入因子 X 后 ΔR² = +0.0074。 判定线：ΔR² ≥ +0.005 视为因子有效。
改动要点：数字保留、口径定义前移、判定线写死、溯源句全删——历史进 git，口径进正文定义，agent 拿到确定性指令。
审阅/合并已有 skill 文档：落地流程
审阅他人文档或合并两份版本时，目标是有效性零损失 + 表述全净化（曾用此法把 27KB 溯源型文档净化为 15KB 可执行 skill，全部实测数字原样保留）：
- 盘点有效载荷：先列全所有数字/参数/结论（阈值、R²、胜率、命令、字段名、文件路径），这些是必须保留的"有效性"。
- 剥离历史：演进史、修复记录、A/B 复验明细、口径沿革 → 移入
references/research-history.md，正文只留当前权威值。历史进 references，不进正文。 - 坑改禁令：把"此前是求和""旧口径会 X"改写为当前禁令——"不得用求和（会导致…）""定义按上表写死，勿改动"。让 agent 拿到的是规则，不是新闻。
- 门禁复检：逐项核对 ① 有效数字是否全部仍在正文（抽查清单比对）② 溯源词扫描（区分技术术语，见下）③ 结构完整 ④ 体量 8-15k ⑤ frontmatter 合法。
- 正文给引用指针：参考资料节列出 research-history.md，注明"供人类专家审阅可信度，agent 执行不依赖"。
溯源词扫描的误报豁免：技术/功能术语不是污染——"numpy 回退/东财回退"（机制）、"原始绝对值"（方法论术语）、"历史波动率"（指标名）、"三指数对比"（功能名）、"自备历史语料"（输入）。只删叙事/对账句（原报告/旧口径/此前/曾/修复），保留功能与指标术语。
测试验证：一个 Skill 测三层
skill 写完必须测试，核心思路是一个 Skill 测三层：能不能跑、能不能触发、有没有用。
第一层：能不能跑（基础验证）
确保 skill 本身能正常工作：
| 检查项 | 具体内容 |
|---|---|
| 路径正确性 | references/、scripts/、templates/ 等引用文件能否读到 |
| 脚本可执行 | 关联的 shell/Python 脚本能否正常运行 |
| 输出格式 | 生成的产物是否符合预期格式（文件路径、内容结构） |
| 步骤完整性 | 关键步骤有没有遗漏，流程能不能走通 |
第二层：能不能正确触发（入口验证）
测试入口准确性，准备一组真实用户可能会说的表达：
| 测试维度 | 具体做法 |
|---|---|
| 正向测试（应该触发） | 准备 2-3 条真实用户可能说的自然语言，看 skill 是否被正确加载 |
| 反向测试（不该触发） | 准备语义接近但不相关的需求，看是否误触发 |
| 边界测试 | 模糊表达、缩写、口语化说法是否能准确命中 |
典型问题诊断：
- 触发不足 → description 写得太抽象，未覆盖真实用户用语 → 收集更多真实表达补进 description
- 过度触发 → description 边界太宽，无关请求也被命中 → 收紧边界，增加"不适用"场景描述
第三层：结果有没有变好（基线对比）
用同一个任务对比启用与不启用 skill 的结果：
- 准备 2-3 个有代表性的测试样本
- 不使用 skill，直接让模型执行 → 记录基线得分
- 使用 skill，让模型执行 → 记录 skill 得分
- 对比两个得分，判断 skill 是否带来增益
评分角度参考：
| 维度 | 说明 |
|---|---|
| 准确性 | 事实错误、逻辑漏洞是否减少 |
| 一致性 | 多次运行输出是否稳定，下限是否抬升 |
| 符合预期 | 输出是否更贴近用户真正想要的东西 |
| 效率 | 执行速度、是否需要额外修改 |
发布前门禁检查清单
与 deliverable-qa（交付物质量审查）联动：本清单定义 skill 专项检查维度，deliverable-qa 提供两档执行框架（快速门禁 / 深度审查）。
快速门禁（每次修改后、通用任务完成时）
- frontmatter 合法：以
---开头，name/description 存在，description ≤ 1024 字符 - description 附真实问题示例：含 1-2 条用户可能说的触发话术，作为触发测试的正向样本
- 溯源词扫描通过：正文无"原/旧/曾/此前/对比/改为"类句子
- 单一事实版本：每个数字/参数只有当前值，无新旧口径对账
- 一句话检验通过：删掉不改变执行的句子已全部删除
- 结构完整：Overview / When to Use / 正文 / Common Pitfalls / Verification Checklist
深度审查（发布 / git push / PR 前，必过）
- 快速门禁全部通过
- 三层测试通过：能跑（路径/脚本/输出/步骤）+ 能触发（正向/反向/边界）+ 有效果（基线对比）
- 样例数据为真实值：示例中的代码、名称、数值均已人工核验，非 AI 虚构
- 数字可验证：每个数字/参数能在 references/ 或正文定义处找到口径与来源
- 无悬空引用：正文不含"原报告"类读者拿不到的对象
- 发布目录干净：发布包只含 SKILL.md 与必要的 references/scripts/templates，无 reports/、output/ 等产物文件夹
- 依赖变更已检查：skill 引用的外部依赖（API/数据源/工具）近期无变更，或变更已同步进 skill
- 结构对齐 peers：与同分类下 2-3 个 peer skill 对比，风格与层级一致
- 体量合理：正文 8-15k 字符为宜，超过 20k 拆入 references/ 并由正文引用
- 版本号：仅在你确认后才更新 version 字段
- 相关引用可解析：related_skills 指向真实存在的 skill
Common Pitfalls
- 把交接报告当 skill 写。写"谁做的、怎么演进、和旧口径差多少"——这些是叙事，agent 用不上，专家看着累。历史进 git，skill 只留当前事实。
- 用"旧口径"暗示修正。以为加上"旧口径测得 X"能保护自己，实际制造规格含糊。要么定一个口径，要么写自足分支。
- 保留"原报告"式引用。读者（agent 或外部专家）拿不到该对象，句子必然悬空。要么删，要么把关键结论直接内联。
- 堆砌溯源句当"严谨"。真正的严谨是把口径定义、判定线写死，不是记录数字的历史。
- 审查时只查格式不查污染。门禁重点在语义（可执行性/单一事实），不在排版。
- 溯源词扫描误伤技术术语。"numpy 回退""原始绝对值""历史波动率""三指数对比""自备历史语料"是机制/指标/功能名，不是污染；只有"原报告/旧口径/此前/曾/修复"类叙事对账句才需重写或删除。扫描时先建立技术术语豁免清单，避免把可执行的机制描述当成污染删掉。
- 只测"能跑"不测"能触发"。脚本跑通不代表 description 命中准确。触发不足或过度触发都会让 skill 形同虚设，必须做正向/反向/边界测试。
- 示例数据用 AI 生成的虚构值。AI 写 skill 时容易虚构产品代码、名称、样例数值，发布前必须人工核验为真实数据。
- 忽略外部依赖变更。skill 引用的 API、数据源、工具升级或废弃时，skill 可能失效。定期检查依赖状态，核心业务准备降级方案。
Verification Checklist
- 对正文逐句做"一句话检验法"，无可删除的装饰句
- 扫描全文，无溯源词污染（原/旧/曾/此前/对比/改为）
- 每个数字/参数有唯一当前值 + 口径定义位置
- 步骤可直接照做：命令、路径、API、阈值均确定
- description 含真实问题示例，覆盖用户常用表达
- 三层测试全部通过：能跑 / 能触发 / 有效果
- 快速门禁 6 项全部勾选；发布场景深度审查 11 项全部勾选