writing-skills

概述

这项技能要求以测试驱动开发（TDD）的方法编写文档和技能。通过在编写内容之前定义技能必须实现的目标，我们可以确保功能清晰，并避免产生“虚构效用”或泛泛而谈、缺乏依据的建议。

铁律

NO SKILL WITHOUT A FAILING TEST FIRST 如果没有预先编写测试用例，技能往往会偏离目标，变成无法解决特定用户问题的泛泛之谈。测试用例能让技能扎根于实际需求。

状态机

digraph writing_skills_flow {
    "Start" [shape=doublecircle];
    "Step 1: Define User Problem" [shape=box];
    "Step 2: Write Failing Test Case" [shape=box];
    "Step 3: Define Acceptance Criteria" [shape=box];
    "Step 4: Author Skill Content" [shape=box];
    "Step 5: Run Test Case" [shape=box];
    "Gate: Pass Test?" [shape=diamond];
    "Done" [shape=doublecircle];

    "Start" -> "Step 1: Define User Problem";
    "Step 1: Define User Problem" -> "Step 2: Write Failing Test Case";
    "Step 2: Write Failing Test Case" -> "Step 3: Define Acceptance Criteria";
    "Step 3: Define Acceptance Criteria" -> "Step 4: Author Skill Content";
    "Step 4: Author Skill Content" -> "Step 5: Run Test Case";
    "Step 5: Run Test Case" -> "Gate: Pass Test?";
    "Gate: Pass Test?" -> "Done" [label="pass"];
    "Gate: Pass Test?" -> "Step 4: Author Skill Content" [label="fail"];
}

何时使用此技能

• 从头创建新的 Agent 技能。
• 重构现有技能以添加新功能。
• 将粗略草稿升级为可用于生产环境的技能。
• 调试输出质量不佳的技能。

何时不使用此技能

• 不需要持久技能指令的简单任务执行。
• 一般对话回复。

核心流程

步骤 1：定义用户问题

找出用户面临的具体失败模式或知识缺口。如果用户没有这项技能，会发生什么？（来源：系统设计）

步骤 2：编写失败测试用例

起草一个示例提示词或场景，让通用大模型（或当前技能）无法通过。这是 TDD 的“红”阶段。（来源：系统设计）

步骤 3：定义验收标准

列出 3-5 项具体、可测试的行为，技能必须具备这些行为才能被视为成功。（来源：系统设计）

步骤 4：编写技能内容

按照适当的严谨度模板（完整严谨度或标准严谨度）编写技能。每项原则都必须直接针对步骤 1 中确定的失败模式。（来源：系统设计）

步骤 5：运行测试用例

使用新编写的技能执行步骤 2 中的失败测试用例。如果输出符合验收标准，则技能通过。（来源：系统设计）

跨技能调用

必需的子技能：无 推荐的子技能：prompt-optimizer — 用于完善测试用例和技能指令。

合理化说辞对照表

想法	事实
“我知道自己想说什么，不需要测试用例。”	没有测试，你就无法知道这项技能是否真的改变了大模型的行为。
“编写测试太费时间了。”	部署后修复有缺陷的技能要多花 10 倍时间。
“这项技能太简单，不适合用 TDD。”	简单技能最容易藏进泛泛而谈的内容。
“我写完技能再补测试。”	这违背了初衷；你会不自觉地编写一个技能已经能够通过的测试。

危险信号

出现以下想法时，意味着你必须停下来——你正准备走捷径：

• “我先写起来，看看会写成什么样” → 你跳过了步骤 1 和步骤 2。
• “没有这项技能也能通过测试用例” → 测试用例太弱，没有体现真正的失败模式。
• “看起来足够全面，我就假定它有效” → 你跳过了步骤 5。

诊断清单

• 是否记录了会失败的测试用例（提示词/场景）？
• 验收标准是否明确关联到失败测试用例？
• 技能中的每项原则是否都对应一项必要行为？
• 是否已针对该场景测试技能并确认通过？
• 技能是否不含泛泛而谈、无法付诸行动的建议？

来源

• 系统设计 — Pattern Lineage 和 writing-skills 定义。
• 系统设计 — Full Rigor 格式要求。