writing-skills

概览

writing-skills 技能能做什么

writing-skills 是一个面向技能作者的 meta-skill，用于为 Claude 等 agent 编写、打磨和测试其它技能。它将经典的 Test-Driven Development (TDD) 应用到流程文档中，让你的技能做到：

• 基于真实的压力场景设计
• 针对实际的 agent 失败案例进行验证
• 通过迭代完善来弥补漏洞、降低“自我合理化”风险

你可以用 writing-skills 来设计这样的技能：agent 能够发现它、遵循它，并在时间压力、沉没成本偏见或激励冲突下仍然坚持执行。

writing-skills 适合谁

在以下情况下可以使用 writing-skills 技能：

• 你是为 Claude 或类似 agent 创建技能的 开发者
• 你是 团队负责人，要在 ~/.claude/skills 或 ~/.agents/skills/ 中规范化工作流
• 你是 文档负责人，需要保证技能不仅被阅读，更要被严格遵守
• 你是 测试人员，要在正式发布前验证技能是否真正改变了 agent 行为

它并不专注于一般性的“写作风格”，而是专门用于：编写高效、可测试的 agent 技能。

这个技能帮助解决什么问题

writing-skills 专为以下场景设计：

• 在压力下 agent 忽略或只部分遵守你的技能
• 你不确定某个新技能是否真的改变了行为
• 你需要一种可重复的方法，在部署前用 subagents 测试技能
• 你希望遵循 Anthropic 的技能编写最佳实践，而不是凭感觉摸索
• 你需要用 Graphviz 直观呈现并沟通复杂的技能工作流

如果你现有的技能更像一次性的故事或笔记，writing-skills 可以帮助你把它们重塑为 可复用、可测试的参考指南。

什么时候适合使用 writing-skills，什么时候不适合

适用场景：

• 要求严格执行的技能（TDD、验证流程、评审清单等）
• 具有真实 合规成本 的技能（时间投入、返工、发版延迟等）
• agent 可能试图绕过的技能（“就这一次破例”）
• 你希望衡量“遵从率”并看到可量化提升的技能

不太适用：

• 纯参考类技能（例如 API 语法、基础语言 cheatsheets）
• 明确设计为“没有可违反规则”的技能
• 你不需要 TDD 式测试或压力场景的轻量级笔记

如果你只是为一段对话随手记个非正式备忘，一般不需要 writing-skills。如果你希望一个技能经得住线上生产环境的压力，就很值得使用它。

使用方法

安装与基础配置

要在支持技能的环境中安装 writing-skills 技能：

npx skills add https://github.com/obra/superpowers --skill writing-skills

此命令会从 obra/superpowers 仓库拉取 writing-skills 技能，并将其注册到你现有技能列表中。

个人技能通常保存在针对不同 agent 的目录中，例如：

• ~/.claude/skills/ 用于 Claude Code
• ~/.agents/skills/ 用于 Codex 或类似 agent

请将 writing-skills 目录放置（或确认已放置）在对应的 skills 根目录下，这样 agent 才能在需要时加载 SKILL.md 等相关文件。

writing-skills 中的关键文件和目录

安装完成后，先查看以下文件，以便理解并应用整体工作流：

• SKILL.md – 核心技能定义与 writing-skills 总览，包括 TDD 与技能的对应关系。
• anthropic-best-practices.md – 面向 Claude 的官方风格指南，说明如何写出简洁、易发现且效果好的技能。
• testing-skills-with-subagents.md – 实操指南，讲解如何设计和执行压力场景及测试 campaign。
• persuasion-principles.md – 帮助提升 agent 遵从度的循证型说服模式。
• graphviz-conventions.dot – 使用 Graphviz 表达技能工作流和流程时的约定与规范。
• render-graphs.js – 辅助脚本，用于从 SKILL.md 中抽取 ```dot 代码块并渲染为 SVG 图。
• examples/CLAUDE_MD_TESTING.md – 一个完整的测试 campaign 示例，针对不同版本的 CLAUDE.md 文档。

这些文件组合在一起，提供完整的技能 编写 + 测试 + 可视化 工作流。

核心流程：把 TDD 用在技能上

writing-skills 将 TDD 的思路直接应用到技能编写中。高层循环如下：

1. 先写测试用例（压力场景）

   • 设计真实情境，让 agent 有可能“合理化地”跳过或扭曲你预期的流程。
   • 使用 subagents 执行这些场景，并记录它们的行为。

2. 运行基线测试并观察失败

   • 在不加载新技能或更新技能的情况下执行这些场景。
   • 记录 agent 的失败点：他们跳过了什么、如何自我合理化、有哪些误解。

3. 编写或优化技能

   • 根据观察到的具体失败情况，撰写或更新 SKILL.md 及相关文件。
   • 使用 简洁、祈使句式 的语言，并考虑 context window 限制。

4. 在加载技能的情况下再次运行测试

   • 用同样的场景重跑一次，这次加载了你的技能。
   • 验证 agent 是否能发现、声明并遵循该技能。

5. 重构以堵住漏洞

   • 找出残留的自我合理化或不完全遵从问题。
   • 应用说服原则（权威、承诺等）增强执行力度。
   • 精简多余 tokens，让技能更简练。

这个循环对应经典 TDD 中的 RED → GREEN → REFACTOR，只是对象从代码变成了文档和流程约束。

使用 anthropic-best-practices.md 提升技能质量

anthropic-best-practices.md 提供了专门针对 Claude 生态的写作指南，包括：

• 为什么 精炼 的技能更有利于 context 利用和模型表现
• Claude 何时以及如何把 SKILL.md 和其他文件加载进 context window
• 如何编写“配得上 token 成本”的技能结构与章节

你可以把这个文件当作自审清单：

• 删除 Claude 已经“自带”的解释
• 专注于 可执行的模式、规则和工作流
• 让最重要的指令在结构上足够靠前、表达足够清晰

将这些实践与 writing-skills 的 TDD 循环结合，可以帮助你写出既 易被发现 又 高效 的技能。

使用 subagents 测试技能

testing-skills-with-subagents.md 将 TDD 思路扩展为一套具体的测试方法：

• 设计贴近生产环境压力的场景（时间紧、沉没成本、速度 vs 质量等）。
• 使用 subagents 模拟主 agent 的真实行为。
• 以结构化形式记录失败点和自我合理化模式。

这对以下类型的技能尤其重要：

• 强制执行耗时的最佳实践（如“先写测试再写实现”）
• 会与短期目标冲突的技能（如“快速上线” vs “充分验证”）
• 在人类明确要求“走捷径”时仍需坚持的技能

按该文件中的测试模板执行，你可以在技能真正触达终端用户前，先 在压力环境下完成验证。

在技能设计中应用说服原则

persuasion-principles.md 总结了一些也会影响 LLM 行为的心理学原则，例如：

• Authority（权威） – 对安全关键规则使用明确且不可协商的措辞
• Commitment（承诺） – 要求 agent 在使用某技能时先声明，并坚持既定路径
• Scarcity（稀缺） 等 – 谨慎使用，用来凸显关键实践的优先级

在实际写技能时，你可以：

• 对非可选步骤使用更强的祈使语气
• 要求 agent 在技能生效时显式声明：“I am using [Skill Name] now”
• 设计“必须完成”的清单，而不是仅供被动阅读的说明

目标不是“操纵”，而是确保 关键实践能够被持续且一致地执行。

使用 Graphviz 可视化技能流程

复杂技能通常适合用可视化方式呈现。writing-skills 提供：

• graphviz-conventions.dot – 推荐的图表结构和样式
• render-graphs.js – 一个 Node.js 脚本，用于从 SKILL.md 中抽取 ```dot 代码块并生成 SVG 文件。

渲染脚本的基本用法：

./render-graphs.js path/to/your/skill
# 或
./render-graphs.js path/to/your/skill --combine

这可以帮助你：

• 向人类协作者清晰传达技能的流程
• 发现流程设计中的缺口或循环
• 通过在 SKILL.md 中直接嵌入 ```dot 代码块，让文档与可视化始终保持同步

将 writing-skills 适配到你的环境

该仓库给出的是值得你 适配 的模式，而不是需要“照搬”的模板。在把 writing-skills 纳入自己的工作流时可以：

• 保留 TDD 循环，但根据你的工具调整场景格式
• 根据团队习惯使用自己的目录结构，同时保持技能边界清晰
• 将测试 campaign 集成到既有的 CI、代码评审或发布流程

最终目标是构建一个 可重复、以测试驱动的技能编写工作流，并真正适配你的团队和基础设施。

常见问题（FAQ）

什么时候应该加载 writing-skills 技能？

在以下情况下可以加载 writing-skills：

• 创建将放入 ~/.claude/skills 或类似目录的新技能
• 编辑一个已经开始“跑偏”或逐渐被忽略的现有技能
• 为团队或生产环境准备要发布的技能
• 为带 subagents 的技能设计或执行测试 campaign

如果你只是一次性、临时地做些试验，可能无需跑完完整的 writing-skills 工作流。

使用 writing-skills 前需要先懂 TDD 吗？

需要。该技能明确依赖 superpowers:test-driven-development，writing-skills 默认你已经理解 RED → GREEN → REFACTOR 循环，并将其迁移到文档场景中：

• RED：在不加载技能的情况下运行场景，记录失败
• GREEN：新增或优化技能，让这些场景能够通过
• REFACTOR：提升清晰度、封堵漏洞、降低 token 成本

如果你对 TDD 还不熟悉，建议先加载并学习与 TDD 相关的技能。

writing-skills 如何帮助处理 Claude 特定行为？

writing-skills 面向 Claude 等环境设计，仓库中包含与 Anthropic 文档保持一致的 anthropic-best-practices.md。二者结合可以帮助你：

• 编写 Claude 能够稳定 发现 的技能
• 尊重 context window 和 token 预算
• 以适合 Claude 加载和使用的方式组织 SKILL 文件

如果你在搭建 Claude 的技能库，writing-skills 会尤其有价值。

writing-skills 能用在非技术或非代码类技能上吗？

可以，只要该技能描述的是可以通过场景进行测试的 可重复流程。例如：

• 事故响应清单（incident response checklists）
• Code review 工作流
• 文档评审或审批流程

关键在于这个流程必须具备：

• 代理可以遵守或违反的清晰规则
• 步骤被跳过时会产生的真实后果
• 能基于场景“有意义地测试遵从度”的条件

纯叙事性或故事性内容就不太适合作为写作对象。

examples/CLAUDE_MD_TESTING.md 是做什么用的？

examples/CLAUDE_MD_TESTING.md 是一个完整的示例，用来展示如何：

• 设计贴近现实的场景（时间压力、沉没成本、权威 vs 速度等）
• 针对不同版本的 CLAUDE.md 文档运行这些场景
• 对比不同版本在“发现和使用技能”方面的效果

你可以把它当作模板来设计自己的技能测试 campaign。

在 writing-skills 模型中，技能与故事或案例有何不同？

在 writing-skills 的框架里：

• 技能（skill） 是可复用的参考指南，编码了经过验证的模式、工具或工作流。
• 故事（story） 或案例只是在描述一次性解决某个具体问题的过程。

writing-skills 帮助你从一次性的故事，升级到 可泛化、可测试的技能，让后续的 agent 能在新的情境中发现并应用它们。

如果我的技能很长，会有问题吗？

会有影响，因为存在 context window 限制。anthropic-best-practices.md 解释了为什么精炼的技能表现更好：

• 起初只会加载元数据，但一旦读取了 SKILL.md，其中每一个 token 都会和对话历史争夺 context 空间。
• 你需要不断审视：每一段内容是否“值得占用”这些 tokens。

writing-skills 鼓励你：

• 删除重复或冗余的解释
• 必要时把示例移到支持文件中
• 让 SKILL.md 聚焦在让测试通过所必需的 核心流程和规则 上

如何判断 writing-skills 是否发挥了作用？

你会在以下方面看到效果：

• 在压力场景下曾经被忽略的技能，现在能被稳定遵守
• 新技能不再只是文字说明，而是附带 明确场景和测试用例
• 你能在具体场景下，清楚指出 agent 在“有技能”和“无技能”这两种情况下行为的差异

如果你无法展示带技能和不带技能之间的行为差别，可以回到 TDD 循环，结合 persuasion 和 testing 相关指南，对技能进行新一轮改写和测试。