skill-development-standard

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

Skill 开发规范

Overview

skill.md 的本质是执行程序，不是交接报告。它同时被两类读者消费：AI agent（照步骤执行）与人类专家（审阅方法是否正确）。本规范解决一个核心问题——确保 skill.md 撰写干净有效：杜绝"溯源型元叙述"等污染，让 agent 拿到确定性指令，让专家一眼看穿方法对错，而非被迫考古。

规范源自实际评审教训：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 中即当前权威值；来源、测时、口径归 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 拿到确定性指令。

发布前门禁检查清单

与 deliverable-qa（交付物质量审查）联动：本清单定义 skill 专项检查维度，deliverable-qa 提供两档执行框架（快速门禁 / 深度审查）。

快速门禁（每次修改后、通用任务完成时）

• frontmatter 合法：以 --- 开头，name/description 存在，description ≤ 1024 字符
• 溯源词扫描通过：正文无"原/旧/曾/此前/对比/改为"类句子
• 单一事实版本：每个数字/参数只有当前值，无新旧口径对账
• 一句话检验通过：删掉不改变执行的句子已全部删除
• 结构完整：Overview / When to Use / 正文 / Common Pitfalls / Verification Checklist

深度审查（发布 / git push / PR 前，必过）

• 快速门禁全部通过
• 数字可验证：每个数字/参数能在 references/ 或正文定义处找到口径与来源
• 无悬空引用：正文不含"原报告"类读者拿不到的对象
• 干跑验证：按 skill 步骤完整模拟执行一遍，确认每步可完成、命令/路径/API 可直接照做
• 结构对齐 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. 审查时只查格式不查污染。门禁重点在语义（可执行性/单一事实），不在排版。

Verification Checklist

• 对正文逐句做"一句话检验法"，无可删除的装饰句
• 扫描全文，无溯源词污染（原/旧/曾/此前/对比/改为）
• 每个数字/参数有唯一当前值 + 口径定义位置
• 步骤可直接照做：命令、路径、API、阈值均确定
• 快速门禁 5 项全部勾选；发布场景深度审查 8 项全部勾选