writing-skills

writing-skills 技能概览

writing-skills 是做什么的

writing-skills 是一套用于创建、编辑和验证 agent skill 的 Skill Authoring 指南，采用测试驱动的工作流来写技能。它的核心思路很简单，但也很有明确立场：把 skill 写作当作面向流程文档的 TDD。不是先把建议写出来再期待它能奏效，而是先设计出有压力的场景，观察在没有 skill 时 agent 会如何失败，然后只写那些真正能改变行为的指导内容。

谁适合使用 writing-skills

最适合的读者，是为 Claude Code、Codex 风格的 agent 环境，或类似本地 skill 目录编写技能的人。尤其适合那些需要 agent 保持纪律、执行验证步骤，或在时间压力下也不能跳过流程的技能作者。

它真正解决的是什么问题

大多数用户真正需要的，并不是“帮我写 markdown”。他们需要的是一种可重复的方法，产出一个 agent 真的会发现、会遵循、而且在赶时间、过度自信或已经投入很多成本时仍会继续遵循的 SKILL.md。writing-skills 就是为这个问题设计的。

为什么这个技能不同于通用 prompt

通用 prompt 可以帮你起草一个 skill，但 writing-skills 提供的是一种验证 skill 是否真的改变行为的方法：

• 定义压力场景
• 在没有 skill 的情况下做基线测试
• 针对已观察到的失败模式撰写文档
• 重新测试并重构，堵住漏洞

因此，对于 Skill Authoring 来说，它比一句“一次性帮我写个 skill”的指令更有价值。

重要前提与取舍

采用 writing-skills 最大的门槛在于：它默认你已经理解这个仓库的 TDD 视角。这个 skill 明确要求具备 superpowers:test-driven-development 的背景。如果跳过这层基础，里面的写作建议可能会显得比预期更严格，或者测试味道过重。

它的取舍也很明确：这套工作流比凭直觉起草要慢，但在失败代价高、或者 agent 很容易为跳过 skill 找理由的场景下，会可靠得多。

如何使用 writing-skills 技能

writing-skills 的安装上下文

仓库中说明，个人 skills 应放在 agent 对应的目录下，例如 Claude Code 使用 ~/.claude/skills，Codex 使用 ~/.agents/skills/。如果你是通过 skill manager 从 obra/superpowers 仓库安装，请确认最终 skill 落在了你的 agent 实际会扫描的目录里。

如果你打算在安装前先手动评估，建议先看这些文件：

• skills/writing-skills/SKILL.md
• skills/writing-skills/testing-skills-with-subagents.md
• skills/writing-skills/anthropic-best-practices.md
• skills/writing-skills/examples/CLAUDE_MD_TESTING.md

先读这些文件，评估 writing-skills

如果想最快判断 writing-skills 是否适合你，推荐按这个顺序阅读：

1. SKILL.md：看主工作流和整体定位
2. testing-skills-with-subagents.md：看如何对 skills 运行 RED/GREEN/REFACTOR
3. anthropic-best-practices.md：看简洁版写作原则
4. examples/CLAUDE_MD_TESTING.md：看真实压力场景长什么样
5. persuasion-principles.md：如果你的 skill 需要抵抗“找理由跳过”的行为，再看这个
6. graphviz-conventions.dot 和 render-graphs.js：只有在你想用图表时再看

相比只扫一眼 SKILL.md 开头，这条阅读路径的信息密度更高，也更容易做安装判断。

writing-skills 需要你提供什么输入

writing-skills 在你带着具体证据来时效果最好，而不只是一个泛泛的话题。高质量输入通常包括：

• 你想创建或修改的具体 skill
• 你希望改变的 agent 行为
• 没有该 skill 时的失败案例
• agent 容易跳过流程的场景
• skill 最终要放置的目标目录和平台

弱输入示例：“Help me write a testing skill.”

强输入示例：“Create a skill that forces pre-deployment verification for database migrations. Agents currently skip rollback checks when fixes seem obvious.”

如何把粗略目标变成可用 prompt

一种好用的 writing-skills usage 方式，是一次把四个部分都提出来：

1. 压力场景
2. 基线失败预期
3. skill 结构
4. 验证计划

示例：

Use writing-skills for Skill Authoring.

Goal: Create a skill for release-checklist enforcement in ~/.claude/skills/release-checks.
Observed failures: agents skip smoke tests when changes look small; they rationalize that CI is enough.
Need:
- 3 pressure scenarios that trigger those shortcuts
- baseline RED expectations without the skill
- a concise SKILL.md outline
- refactor ideas to close loopholes after first test run
Keep it concise and optimized for discoverability.

这种提法远比“帮我写一份 polished 的 skill 文档”有效，因为它把 skill 需要修复的失败模型直接提供出来了。

推荐的 writing-skills 使用工作流

一个实用的流程通常是这样：

1. 定义要约束的行为
2. 写出 2–5 个压力场景
3. 在没有 skill 的情况下测试 agent
4. 记录其具体的合理化说辞和捷径
5. 只针对这些失败起草 SKILL.md
6. 在加载 skill 后重新测试
7. 如果 agent 仍会滑过去，就继续收紧措辞
8. 删掉所有没有提升遵循率的说明

最后这一步很重要，因为仓库里附带的 best-practices 明确强调了 token 效率和指令简洁性。

什么时候测试驱动方法最值得用

当你的 writing-skills for Skill Authoring 面向的是有遵循成本的 skill 时，这套方法最有价值，比如：

• 需要额外测试
• 验证流程更慢
• 需要做文档检查
• 要求重启或返工
• 规则本身和“求快”激励相冲突

如果只是纯参考型 skill，例如 API 语法速查表，agent 通常没有太大动机绕过内容，这种方法的重要性就没那么高。

如何使用 subagent 测试参考

testing-skills-with-subagents.md 是非常实用的配套文档。它帮助你测试 skill 在真实压力下是否还能成立，而不只是“在平静情况下看起来说得通”。以下场景建议重点阅读：

• 需要场景模板时
• 需要 RED/GREEN/REFACTOR 对应关系时
• 需要捕捉 rationalization 时
• 需要看由压力驱动的不遵循案例时

如果你的第一版看上去没问题，但实际采用效果差，这个文件通常是最快的改进入口。

可以借鉴示例场景，但不要生搬硬套 writing-skills

examples/CLAUDE_MD_TESTING.md 的价值在于，它展示了压力场景到底应该是什么样：时间压力、沉没成本、权威压力、熟悉性偏差。常见错误是把这些场景原封不动复制到完全不同的 skill 上。

更好的做法，是把“压力类型”迁移到你自己的工作流里。例如：

• deployment skill → 紧急上线和害怕回滚
• review skill → 过度自信和追求速度
• security skill → “就这一次”的合理化
• style skill → 采用成本较低，所以测试可以更轻量

persuasion 指南如何融入工作流

persuasion-principles.md 不是凑数文件；它存在的原因是，有些 skill 即使流程写清楚了，依然会失效。如果你的 skill 需要强制 agent 执行那些它们通常会抗拒的行为，更强的措辞可能会有帮助。该文件给出了一些具体模式，比如 authority、commitment 和显式声明。

但要谨慎使用。目的不是让 skill 更“响亮”，而是让那些必须执行的动作更难被合理化地跳过。

会直接影响输出质量的简洁规则

这个仓库最有价值的提醒之一，是 skills 会共享上下文预算。writing-skills 不是让你写得更多，而是让你只写那些真正能改变行为的内容。

好的信号：

• 触发条件具体
• 必做动作明确
• 示例简短，并直接对应真实失败
• 背景说明最少化

不好的信号：

• 很长的动机型文案
• 重复定义
• 过程历史回顾
• Claude 本来就知道的泛泛 “best practices”

可选的图表工具

该 skill 目录中包含 render-graphs.js，如果安装了 graphviz，它可以从 SKILL.md 里提取 dot 代码块并渲染成 SVG 图。这个功能是可选的，主要适合工作流里存在分支状态或 review gate，需要人类以可视化方式检查的情况。使用 writing-skills skill 本身并不依赖它，但它能帮助维护者排查流程复杂度。

writing-skills 技能 FAQ

如果我本来就会写 prompts，还有必要安装 writing-skills 吗？

有，前提是你的问题在于可靠性，而不是起草速度。普通 prompt 可以很快生成一份看起来不错的 skill；而 writing-skills 的价值在于，当 agent 面临压力时，你仍然能更有把握地确认最终 skill 会改变行为。

writing-skills 对新手友好吗？

部分友好。写作层面本身不难理解，但方法论默认你能接受 TDD 风格的思考方式。刚接触 Skill Authoring 的用户，最好先读仓库里和 TDD 相关的材料，否则很容易把这套流程误解为不必要的仪式感。

什么情况下 writing-skills 不适合？

以下情况可以跳过 writing-skills：

• 纯参考型的简单 skill
• 不打算复用的一次性笔记
• 基本不存在违背指引诱因的话题
• 无法做任何前后对比测试的场景

这些情况下，更轻量的编写方式通常就足够了。

writing-skills 与 Anthropic 的 skill best practices 有什么不同？

附带的 anthropic-best-practices.md 重点在于：skill 要简洁、易发现、节省上下文。writing-skills 则多加了一层“行为改变”的视角：先观察失败，再只写那些能修复失败的内容。两者是互补关系，不是互相替代。

writing-skills 需要额外的仓库工具吗？

不需要。要从这套方法中获益，并不依赖什么大型工具链。最关键的是测试指南和示例。图表渲染只是可选项，核心的编写工作流也没有必须依赖的辅助脚本。

可以用 writing-skills 来修改已有 skill 吗？

可以，而且这恰恰是它最适合的用途之一。如果一个 skill 已经存在，但 agent 仍然忽视它或误用它，writing-skills 可以帮助你定位真实失败模式，删掉无用内容，重写那些真正关键的指令。

如何改进 writing-skills 技能

从已观察到的失败出发，而不是从理想文档出发

想提升 writing-skills 的产出质量，最快的方法就是带着失败证据来。如果你只描述理想流程，输出通常会变得泛泛而空。如果你提供的是 agent 实际走过的捷径，最终得到的 skill 往往会更锋利，也更短。

提供更有力的压力场景

好的场景必须让“跳过 skill”这件事真的有诱惑力。建议包含：

• 时间压力
• 来自过往经验的自信
• 沉没成本
• 来自人类的权威压力
• “这个修复很明显”的叙事框架

这些条件最能暴露出你的指令到底是太软，还是太模糊。

记录 agent 的原话式合理化，而不是笼统概括

不要把失败简单总结成“ignored the skill”。要记录 agent 实际说了什么、或明显暗示了什么：

• “This is a small change”
• “CI will catch it”
• “I already know this pattern”
• “Reading the skill would take too long”

这些合理化说辞，决定了你后续修订 writing-skills usage prompt 和最终 skill 措辞时，必须正面回应什么。

在遵循性关键的位置收紧措辞

如果这个 skill 的目的是强制执行不可选行为，模糊表达会直接伤害效果。把柔性的建议，替换成明确的触发条件和必做动作。persuasion 指南在这里有帮助，但最关键的改进其实来自具体性：

• 什么时候加载 skill
• 第一步必须做什么
• 哪些内容不能跳过
• 什么才算成功

删除所有不能改变行为的内容

writing-skills skill 输出里常见的一类问题，就是解释过多。如果某一段既没有帮助发现 skill，也没有提升遵循率或测试效果，那就删掉。仓库里的 best-practices 文件之所以把这条列为核心规则，是有原因的。

第一次通过后，继续迭代

第一次跑出 “GREEN” 并不代表已经足够，尤其当该 skill 只在轻松条件下有效时更是如此。你应当用更苛刻的 prompt 和不同表述方式继续复测。重点看：当 agent 很赶、非常确定自己没问题，或者急于保住已经完成的工作时，这个 skill 是否仍然有效。

将 writing-skills 与仓库特定示例配套使用

如果你的团队有反复出现的工作流，最好在目标 skill 对应的领域里加入一个完整但精简的示例。与其继续堆抽象规则，这通常更能提升采用率。示例要短，并且经过压力测试，而不是做成百科全书式说明。

改进 prompt：要结构，不要润色

调用 writing-skills 时，优先要求这些内容：

• 场景列表
• 失败分析
• 精简的 skill 大纲
• 用于堵漏洞的修改建议

不要一上来就说“make it polished”或“make it comprehensive”。这类要求通常只会增加篇幅，并不会提升遵循率。

先判断这个 skill 是否真的有必要存在

writing-skills guide 带来的一个有价值结果，是帮助你识别：有些主题其实并不需要 skill。如果流程本来就很明显、风险很低，或者极少重复发生，那么 skill 可能只会增加维护成本，却换不来足够的行为收益。得出“没必要做成 skill”这个结论，本身就是对仓库质量的提升。

把 writing-skills 用于重构，而不只是创建

writing-skills 的最高价值场景，往往不是从零新建，而是在亲眼看到一个现有 skill 失效之后，再拿它来重构。这样一来，这套方法就不再只是“写文档”，而更接近行为工程；而这正是这个仓库最有实操价值的地方。