skill-development-standard

Skill 开发规范——SKILL.md 撰写铁律、三层测试验证与发布前门禁检查清单。撰写新 skill、修订整理已有 skill、以面试官身份审阅他人 skill、发布/git push/PR 前自查时使用。核心目标是确保 skill 对 AI agent 可执行、对人类专家可审阅。

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，全部实测数字原样保留）：

1. 盘点有效载荷：先列全所有数字/参数/结论（阈值、R²、胜率、命令、字段名、文件路径），这些是必须保留的"有效性"。
2. 剥离历史：演进史、修复记录、A/B 复验明细、口径沿革 → 移入 references/research-history.md，正文只留当前权威值。历史进 references，不进正文。
3. 坑改禁令：把"此前是求和""旧口径会 X"改写为当前禁令——"不得用求和（会导致…）""定义按上表写死，勿改动"。让 agent 拿到的是规则，不是新闻。
4. 门禁复检：逐项核对 ① 有效数字是否全部仍在正文（抽查清单比对）② 溯源词扫描（区分技术术语，见下）③ 结构完整 ④ 体量 8-15k ⑤ frontmatter 合法。
5. 正文给引用指针：参考资料节列出 research-history.md，注明"供人类专家审阅可信度，agent 执行不依赖"。

溯源词扫描的误报豁免：技术/功能术语不是污染——"numpy 回退/东财回退"（机制）、"原始绝对值"（方法论术语）、"历史波动率"（指标名）、"三指数对比"（功能名）、"自备历史语料"（输入）。只删叙事/对账句（原报告/旧口径/此前/曾/修复），保留功能与指标术语。

测试验证：一个 Skill 测三层

skill 写完必须测试，核心思路是一个 Skill 测三层：能不能跑、能不能触发、有没有用。

第一层：能不能跑（基础验证）

确保 skill 本身能正常工作：

检查项	具体内容
路径正确性	references/、scripts/、templates/ 等引用文件能否读到
脚本可执行	关联的 shell/Python 脚本能否正常运行
输出格式	生成的产物是否符合预期格式（文件路径、内容结构）
步骤完整性	关键步骤有没有遗漏，流程能不能走通

第二层：能不能正确触发（入口验证）

测试入口准确性，准备一组真实用户可能会说的表达：

测试维度	具体做法
正向测试（应该触发）	准备 2-3 条真实用户可能说的自然语言，看 skill 是否被正确加载
反向测试（不该触发）	准备语义接近但不相关的需求，看是否误触发
边界测试	模糊表达、缩写、口语化说法是否能准确命中

典型问题诊断：

• 触发不足 → description 写得太抽象，未覆盖真实用户用语 → 收集更多真实表达补进 description
• 过度触发 → description 边界太宽，无关请求也被命中 → 收紧边界，增加"不适用"场景描述

第三层：结果有没有变好（基线对比）

用同一个任务对比启用与不启用 skill 的结果：

1. 准备 2-3 个有代表性的测试样本
2. 不使用 skill，直接让模型执行 → 记录基线得分
3. 使用 skill，让模型执行 → 记录 skill 得分
4. 对比两个得分，判断 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

1. 把交接报告当 skill 写。写"谁做的、怎么演进、和旧口径差多少"——这些是叙事，agent 用不上，专家看着累。历史进 git，skill 只留当前事实。
2. 用"旧口径"暗示修正。以为加上"旧口径测得 X"能保护自己，实际制造规格含糊。要么定一个口径，要么写自足分支。
3. 保留"原报告"式引用。读者（agent 或外部专家）拿不到该对象，句子必然悬空。要么删，要么把关键结论直接内联。
4. 堆砌溯源句当"严谨"。真正的严谨是把口径定义、判定线写死，不是记录数字的历史。
5. 审查时只查格式不查污染。门禁重点在语义（可执行性/单一事实），不在排版。
6. 溯源词扫描误伤技术术语。"numpy 回退""原始绝对值""历史波动率""三指数对比""自备历史语料"是机制/指标/功能名，不是污染；只有"原报告/旧口径/此前/曾/修复"类叙事对账句才需重写或删除。扫描时先建立技术术语豁免清单，避免把可执行的机制描述当成污染删掉。
7. 只测"能跑"不测"能触发"。脚本跑通不代表 description 命中准确。触发不足或过度触发都会让 skill 形同虚设，必须做正向/反向/边界测试。
8. 示例数据用 AI 生成的虚构值。AI 写 skill 时容易虚构产品代码、名称、样例数值，发布前必须人工核验为真实数据。
9. 忽略外部依赖变更。skill 引用的 API、数据源、工具升级或废弃时，skill 可能失效。定期检查依赖状态，核心业务准备降级方案。

Verification Checklist

• 对正文逐句做"一句话检验法"，无可删除的装饰句
• 扫描全文，无溯源词污染（原/旧/曾/此前/对比/改为）
• 每个数字/参数有唯一当前值 + 口径定义位置
• 步骤可直接照做：命令、路径、API、阈值均确定
• description 含真实问题示例，覆盖用户常用表达
• 三层测试全部通过：能跑 / 能触发 / 有效果
• 快速门禁 6 项全部勾选；发布场景深度审查 11 项全部勾选