bestpractice_skill_writing_guide

Z3 全文↑ Z2 条目

道-方法 · 道层 skill 全文

本页是 <code>rules/skills/bestpractice_skill_writing_guide.md</code> 的逐字投影（仅隐私清洗，零改写）。

时点提示：本页是仓内文件 rules/skills/bestpractice_skill_writing_guide.md 的逐字投影（仅做隐私清洗：仓库根绝对路径→相对路径、家目录→~/；除此零改写）。若源文件后续有修订，以仓内真源为准。

Skill 写作指南（Meta-Skill）

元数据

类型: BestPractice
适用场景: 需要创建或重写 skill 文件时
创建日期: 2026-03-29

format_face:
  artifact: rules/skills/bestpractice_skill_writing_guide.md
  input_face: structured
  reasoning_face: free
  output_face: formatted
  reasoning_note: "Skill metadata and examples may be structured, but skill-design reasoning stays natural-language; formatting is only applied at the terminal output step."

这个文件是干什么的

Skill 文件是给 AI agent 的能力定义。写得好的 skill 让 agent 能可靠地完成任务，写得差的 skill 要么把 agent 变成一个机械执行清单的脚本，要么因为缺少关键边界和验收标准导致 agent 在错误的方向上展开。

本文件定义写好一个 skill 的核心原则、验收标准和已知陷阱。它不是一个模板，也不规定具体的章节顺序。

核心原则

原则一：结果确定性优先于过程确定性

传统写法是把任务拆成步骤：第一步做什么、第二步做什么、遇到 X 怎么办。这种写法的确定性在过程上，等价于你在用自然语言写一个脚本。问题在于，agent 有推理能力和工具调用能力，把它当脚本用是浪费。更重要的是，步骤式写法无法覆盖长尾 corner case，而 corner case 恰恰是 agent 比脚本更擅长处理的场景。

替代方案是把确定性从过程移到结果上：定义终点长什么样、怎么验证到了终点，让 agent 自己决定怎么到达。

实际操作中，一个 skill 文件需要回答的核心问题是：

目标：要完成什么。一句话说清楚。
验收标准：什么结果算成功。写到这种程度：一个没有任何上下文的 agent 拿到这些标准，也能判断自己做完了没有。如果判断不了，说明标准还不够具体。
可用资源：agent 可以调用哪些工具、读哪些文件、有哪些必须遵守的边界。
输出规格：产出物的格式、存放位置、schema。

这四样东西是 skill 文件的骨架。其他内容（方法论建议、行业知识、历史经验）都是围绕它们展开的。

原则二：写 enabling 的指导，而非 SOP

Skill 文件的读者是一个有推理能力的 agent，它的 context window 是稀缺资源。skill 文件的每一段文字都应该增加 agent 完成任务的概率，而非消耗它的注意力。

方法论建议可以写，但要以建议和约束的形式出现，agent 有权根据实际情况调整。例如"按行业板块分组分析"是一个好建议，因为它给出了一种有效的分析视角，但 agent 在面对某天只有一条宏观大新闻的情况时，应该有自由跳过分组直接做全局分析。

已知的坑和陷阱一定要写，因为这些是 agent 自己不容易发现的。一个具体的踩坑记录比十条泛泛的方法论更有价值。

两个判断标准可以帮助你决定一段内容是否应该写进 skill 文件。第一，如果删掉这段话，agent 完成任务的质量或概率会下降吗？如果不会，删掉它。第二，这段话是在描述"怎么做"还是在描述"做成什么样"？优先保留后者，前者只在确实能提升成功率时保留。

Skill 文件应该包含什么

以下是一个 skill 文件通常需要覆盖的内容区域。顺序和组织方式由你根据具体 skill 决定，不需要严格按照这个列表排列。

元数据。 类型（API Guide / Workflow / BestPractice / Tutorial）、适用场景、输出位置、创建和更新日期。

format_face:（可选，RT-56）。 当 skill 明确约束「模型输入结构 / 推理方式 / 输出格式」时，建议在元数据里声明三面，避免把结构化输出要求误扩散到推理过程。声明字段使用 input_face / reasoning_face / output_face；reasoning_face 只能是 free 或 natural，结构化只用于输入解析和末端输出。可用 format_face 检测器 lint 这三面是否齐全，工具路径查 tools/INDEX.md。

consumer:（可选，P1A-NEW-011）。 绝大多数 skill 默认给被派发的 worker 用，不需要这个字段。少数 skill 描述的是编排者（orchestrator）自己的运作纪律，而不是某个具体任务该怎么做——这种 skill 若被 worker 首步发现（skill_discovery，OD-9）误判为"适用"并注入进 worker 任务 prompt，会把编排纪律错当成执行指导。给这类 skill 的 frontmatter 加一行 consumer: orchestrator，skill_discovery 的候选过滤会据此把它排除在 worker 发现结果之外（不影响它被人或编排者自己直接读取引用）。不写这个字段 = 默认面向 worker，向后兼容。

目标与边界。 这个 skill 做什么、不做什么。边界尤其重要：一个清晰的"不做什么"比模糊的"做什么"更能防止 agent 跑偏。

验收标准。 可测试的成功条件。能自动化验证的写成自动化检查（跑脚本、检查 schema、对比阈值），不能自动化的写成人工审计标准。每条标准都应该足够具体，让 agent 能在运行时自行判断是否满足。

可用资源与边界。 工具清单、文件路径、外部依赖、必须遵守的限制条件。重点是哪些东西可以用，哪些东西不能做，哪些边界不能越过。

方法论建议。 agent 可以参考但不必严格遵循的分析框架、分组策略、优先级排序逻辑。这部分要写清楚哪些是硬约束、哪些是建议。

已知陷阱。 之前迭代中踩过的坑，附带具体的失败表现和应对方式。这是 skill 文件中投入产出比最高的部分之一。

这里要特别强调：不要在一开始凭空预测"可能的坑"来凑这一节。 已知陷阱应该来自实际失败、返工、误判或多轮迭代中的真实教训。一个新 skill 在初版时完全可以没有这一节，或者只留一个很短的占位说明。只有当某个错误真的发生过，且未来高概率会重复发生时，它才值得被写进 meta 层的已知陷阱。

输出规格。 格式、schema、存放路径。如果有 JSON schema，给一个完整示例比描述 schema 更容易让 agent 理解。

验收标准（这个 meta-skill 自身的）

一个 skill 文件写好之后，用以下标准检查。

结果导向检查。 文件中是否有明确的、可测试的验收标准？一个新 agent 只读这份 skill 文件，能否判断任务是否完成？如果不能，说明验收标准还不够具体。

无冗余步骤。 文件中是否有任何步骤式指令（"第一步...第二步..."）？如果有，检查每一步是否真的必要。大多数情况下可以改写为目标+约束的形式。仅当某个步骤的顺序对结果有实质影响时（例如"必须在 X 之前完成 Y，因为 Y 依赖 X 的输出"）才保留顺序要求。

陷阱覆盖。 是否记录了真实发生过的失败模式？如果这是一个全新的 skill，可以先留空。不要为了"看起来完整"而预测或编造陷阱；等实际踩坑后再补，价值更高。

边界清晰度。 agent 的关键边界是否足够明确？例如哪些工具能用、哪些结果算越界、哪些产物必须落盘、哪些限制条件不可违反。模糊的边界会让 skill 失去约束力。

信息密度。 文件长度是否合理？每一段是否都在增加 agent 完成任务的概率？如果一段话删掉后对结果没有明显影响，就应该考虑删掉。

常见陷阱

陷阱	表现	应对
把 skill 写成 SOP	通篇第一步第二步，agent 变成机械执行	改写为目标+约束+方法论建议的形式
验收标准模糊	"输出质量高"、"分析深入"	换成可测量的条件："所有判断必须引用 item_id"、"Brier Score 优于 naive baseline"
过度约束过程	规定 agent 必须用某种特定方法，遇到不适用的情况直接失败	把硬约束限于结果层面，方法论层面写成建议
遗漏边界条件	没说明异常情况怎么办（数据缺失、工具失败、超时）	至少覆盖"无数据"和"工具不可用"两种退化场景
堆砌背景知识	大段介绍领域知识，消耗 agent 的 context window	背景知识只保留直接影响任务执行的部分，其余通过文件路径引用
封装错误信息	CLI/工具把底层错误包装成笼统的 "something went wrong"，丢失 status_code、response body 等 debug 关键信息	透传原始错误细节（HTTP status、response body、exception type），让 AI agent 能从错误输出中直接定位根因。宁可多暴露信息，也不要让 agent 走一轮无意义的猜测
硬编码工具路径	工具移动后 skill 中的路径断裂，需要逐个修复	按名引用工具（如 `todo`），路径查 `tools/INDEX.md`
忘记更新 INDEX.md	新 skill 没人能找到	写完 skill 后立即更新 `rules/skills/INDEX.md`

工具引用规范

Skill 中引用工具时，按名引用，不写完整路径。

正确写法：

"使用 todo CLI"，开头声明"工具路径见 tools/INDEX.md"
命令示例写 todo add "标题" 而非 python3 tools/todo/todo.py add "标题"

错误写法：

在 skill 文件中硬编码 python3 tools/todo/todo.py、tools/send_email_to_myself.py 等完整路径

原因：工具可能被重组到子目录或重命名。路径只在 tools/INDEX.md 中维护，skill 通过名字间接引用。agent 执行时从 INDEX 查找实际路径。

同理，引用其他 skill 时用名字（如"参考 skill：workflow_deep_research_survey"），不写完整文件路径。skill 路径在 rules/skills/INDEX.md 中维护。

与现有 skill 的关系

写新 skill 之前，先读 rules/skills/INDEX.md 确认没有重复。如果已有类似 skill，优先修改而非新建。

格式参考可以看 rules/skills/workflow_deep_research_survey.md（调研类 skill 的范本）和 rules/skills/share_report.md（工具类 skill 的范本）。注意这些只是格式参考，核心原则（结果确定性、enabling 而非 SOP）比格式更重要。

新建即 Beta + 记录使用（治理底座，S-03/S-04，2026-06-05 启用）

新建任何 skill 默认进 Beta，正常使用、记录使用情况，迭代后再决定是否转正式。这条对所有新 skill 无条件生效，理由见段A 实现复盘（adhoc_jobs/landing_requirement_decomposition_20260531/PHASE_A_IMPLEMENTATION_ANALYSIS_20260605.md）：段A 在治理底座没建之前批量造了 6 个 skill、全平铺、零使用记录，是「前序服务后序」被违反的因果倒置。新 skill 要避免重蹈，必须从出生就带 Beta 隔离 + 使用记录。

四条硬约束：

位置即 Beta：新 skill 放 rules/skills/drafts/（= Beta 隔离层，对应状态机 raw draft → tested → beta/candidate → production）。不直接进 rules/skills/ 顶层（顶层 = production，只在过晋级门 + 人确认 + 走 workflow_version_evolution 后才进）。

Beta 元数据：frontmatter 的 status 字段标 draft (Beta) + 一句晋级条件（例：status: draft (Beta) — 晋级前需真实 PROMOTE-ONE 跑通 ≥1 个 draft）。这让任何读到它的 agent 一眼知道它是 Beta、证据等级 bounded、晋级前提是什么。

使用要被记录：skill 被路由使用（= Read 该 skill 文件）时，由 usage_hook 在 Read 路径自动写进 receipt 台账（settings.json PostToolUse matcher 含 Read，命中 rules/skills/ 下 skill 文件即写 tool='skill:<name>'，caller=真实 session_id）。注意这记的是 skill 文件的 Read 事件作为使用代理：查看式 Read 或编辑前的 Read 也会被记入，是可接受的过计数，远好于零捕获。不需要 skill 自己埋点，但创建者要知道：一个 skill 的真实价值靠台账里它被反复使用来证明，零使用记录 = 孤儿，是 workflow_landing_to_production GS-02 收口判据（landed = used+recorded）会卡的点。

晋级靠证据不靠时间：Beta → production 不是「放久了就转正」，是 workflow_landing_to_production 的 PROMOTE-ONE + 晋级门（真实使用记录 + 独立 verifier + 证据到 solid/cross_validated）+ 人确认。证据不够就一直留 Beta，诚实标 bounded。

测试与产物存放（A-06/A-08）：skill / 工具的测试材料和测试版本走 原始材料 → 测试版实现 → 真实条件测试 → Beta 的产物 pipeline，存在对应 adhoc_jobs/<topic>/ 的 tests/ research/ impl/ 子目录（WORKSPACE L44），不散落进 session。版本演进打 tag 的判定查 workflow_version_evolution（draft/bounded 不打 tag，→production 才打）。

← 返回道层 skill 索引 · 返回方法论区