mcpField
W
Writing Skills

Writing Skills

github.com/obraAgent 工作流755516 次安装54 周前更新
代码仓库

关于 Writing Skills

Writing Skills 指导如何把测试驱动开发应用于文档，创建可复用的 Agent 技能。它通过子 Agent 压力场景检验技能，并据此发现和弥补说明中的漏洞。

主要功能

  1. 01以测试驱动方式编写技能
  2. 02用子 Agent 设计压力场景
  3. 03技能类型与选择指南
  4. 04文档结构和发现优化
  5. 05测试与重构循环

适用场景

  1. 01将成熟方法整理成可复用技能
  2. 02检验 Agent 是否遵循文档规则
  3. 03发现技能说明中的缺口
  4. 04改善技能的可发现性与精简度

安装

复制下面的命令，在终端中运行。

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

安装后在 Claude Code 中输入/writing-skills确认已加载。

附带文件graphviz-conventions.dotpersuasion-principles.md

详细介绍

编写技能

概述

编写技能就是将测试驱动开发应用于流程文档。

技能编写在 ${SUPERPOWERS_SKILLS_ROOT} 中（克隆到 ~/.config/superpowers/skills/）。 你在此仓库的本地分支中编辑技能。

你先编写测试用例（使用子 Agent 进行压力场景测试），观察测试失败（基线行为），再编写技能（文档），观察测试通过（Agent 遵循要求），最后进行重构（堵住漏洞）。

核心原则： 如果你没有亲眼观察过 Agent 在没有技能的情况下失败，就无法确定技能教得是否正确。

参见 skills/testing/test-driven-development，了解基本的 RED-GREEN-REFACTOR 循环。此技能将 TDD 应用于文档。

什么是技能？

技能是关于经过验证的技术、模式或工具的参考指南。技能帮助未来的 Claude 实例找到并应用有效的方法。

技能包括： 可复用的技术、模式、工具和参考指南

技能不包括： 讲述你曾如何解决某个问题的故事

技能的 TDD 对应关系

TDD 概念技能创建
测试用例使用子 Agent 的压力场景
生产代码技能文档（SKILL.md）
测试失败（RED）Agent 在没有技能的情况下违反规则（基线）
测试通过（GREEN）有技能时 Agent 遵循要求
重构堵住漏洞，同时保持合规
先编写测试编写技能之前运行基线场景
观察失败记录 Agent 使用的确切理由
最少代码编写技能，解决这些具体违规行为
观察通过验证 Agent 现在会遵循要求
重构循环找出新的理由 → 堵住漏洞 → 重新验证

整个技能创建过程都遵循 RED-GREEN-REFACTOR。

何时创建技能

适合创建的情况：

  • 你直觉上并不清楚某项技术
  • 你会在多个项目中再次参考它
  • 该模式适用范围广（并非特定于某个项目）
  • 其他人也会受益

不适合创建的情况：

  • 一次性解决方案
  • 其他地方已有充分文档说明的标准做法
  • 项目特定的约定（放入 CLAUDE.md）

技能类型

技术

按步骤执行的具体方法（condition-based-waiting、root-cause-tracing）

模式

解决问题的思维方式（flatten-with-flags、test-invariants）

参考

API 文档、语法指南、工具文档（office docs）

目录结构

所有技能都位于 ${SUPERPOWERS_SKILLS_ROOT} 的技能仓库中：

${SUPERPOWERS_SKILLS_ROOT}
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed

扁平命名空间——所有技能都集中在一个可搜索的位置

单独存放以下内容：

  1. 大型参考资料（100 行以上）——API 文档、完整语法说明
  2. 可复用工具——脚本、实用程序、模板

保留在正文中：

  • 原则和概念
  • 代码模式（少于 50 行）
  • 其他所有内容

SKILL.md 结构

---
name: Human-Readable Name
description: One-line summary of what this does
when_to_use: when [trigger/situation]
version: 5.1.0
languages: all | [typescript, python] | etc
dependencies: (optional) Required tools/libraries
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
[Small inline flowchart IF decision non-obvious]

Bullet list with SYMPTOMS and use cases
When NOT to use

## Core Pattern (for techniques/patterns)
Before/after code comparison

## Quick Reference
Table or bullets for scanning common operations

## Implementation
Inline code for simple patterns
@link to file for heavy reference or reusable tools

## Common Mistakes
What goes wrong + fixes

## Real-World Impact (optional)
Concrete results

Claude 搜索优化（CSO）

发现技能至关重要： 未来的 Claude 需要找到你的技能

1. 丰富的 when_to_use

目的： Claude 会阅读 when_to_use，判断要为当前任务加载哪些技能。要让它能回答：“我现在应该阅读此技能吗？”

格式： 以 “when” 开头，使其能组成 “Use [skill-path] when [your text]”

内容：

  • 使用具体的触发条件、症状和情境，表明此技能适用
  • 描述问题（竞态条件、行为不一致），而不是特定于语言的症状（setTimeout、sleep）
  • 除非技能本身特定于某项技术，否则触发条件应与技术无关
  • 如果技能特定于某项技术，应在触发条件中明确说明
# ❌ BAD: Too abstract, doesn't start with "when"
when_to_use: For async testing

# ❌ BAD: Mentions technology but skill isn't specific to it
when_to_use: when tests use setTimeout/sleep and are flaky

# ✅ GOOD: Starts with "when", describes problem not language symptom
when_to_use: when tests have race conditions, timing dependencies, or pass/fail inconsistently

# ✅ GOOD: Technology-specific skill with explicit trigger
when_to_use: when using React Router and handling authentication redirects

find-skills 输出示例：

Use skills/testing/condition-based-waiting/SKILL.md when tests have race conditions, timing dependencies, or pass/fail inconsistently
2. 关键词覆盖

使用 Claude 可能会搜索的词语：

  • 错误消息：“Hook timed out”、“ENOTEMPTY”、“race condition”
  • 症状：“flaky”、“hanging”、“zombie”、“pollution”
  • 同义词：“timeout/hang/freeze”、“cleanup/teardown/afterEach”
  • 工具：实际命令、库名称、文件类型
3. 描述性命名

使用主动语态，以动词开头：

  • ✅ creating-skills，而不是 skill-creation
  • ✅ testing-skills-with-subagents，而不是 subagent-skill-testing
4. 提高令牌效率（至关重要）

**问题：**入门工作流和频繁引用的技能会加载到每次对话中。每个令牌都很重要。

目标字数：

  • 入门工作流：每篇少于 150 个单词
  • 频繁加载的技能：总计少于 200 个单词
  • 其他技能：少于 500 个单词（仍应简洁）

技巧：

将详细内容移至工具帮助：

# ❌ BAD: Document all flags in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# ✅ GOOD: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.

使用交叉引用：

# ❌ BAD: Repeat workflow details
When searching, dispatch subagent with template...
[20 lines of repeated instructions]

# ✅ GOOD: Reference other skill
Always use subagents (50-100x context savings). See skills/using-skills for workflow.

精简示例：

# ❌ BAD: Verbose example (42 words)
your human partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

# ✅ GOOD: Minimal example (20 words)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]

消除冗余：

  • 不要重复交叉引用的技能中已有的内容
  • 不要解释命令本身已显而易见的内容
  • 不要为同一种模式提供多个示例

验证：

wc -w skills/path/SKILL.md
# getting-started workflows: aim for <150 each
# Other frequently-loaded: aim for <200 total

根据你要做的事或核心见解命名：

  • ✅ condition-based-waiting > async-test-helpers
  • ✅ using-skills，而不是 skill-usage
  • ✅ flatten-with-flags > data-structure-refactoring
  • ✅ root-cause-tracing > debugging-techniques

动名词（-ing）适用于描述流程：

  • creating-skills、testing-skills、debugging-with-logs
  • 以主动形式描述你正在采取的行动
4. 内容重复

多次提及关键概念：

  • 在描述中
  • 在 when_to_use 中
  • 在概述中
  • 在章节标题中

在多个位置都能通过 grep 找到，能让内容更容易被发现

5. 交叉引用其他技能

编写引用其他技能的文档时：

使用不带 @ 前缀或 /SKILL.md 后缀的路径格式：

  • ✅ 推荐：skills/testing/test-driven-development
  • ✅ 推荐：skills/debugging/systematic-debugging
  • ❌ 不推荐：@skills/testing/test-driven-development/SKILL.md（会强制加载，消耗上下文）

为什么不使用 @ 链接：@ 语法会立即强制加载文件，在你需要之前就消耗 200k+ 上下文。

**读取技能引用：**使用 Read 工具读取 ${SUPERPOWERS_SKILLS_ROOT}/category/skill-name/SKILL.md

流程图的使用

digraph when_flowchart {
    "Need to show information?" [shape=diamond];
    "Decision where I might go wrong?" [shape=diamond];
    "Use markdown" [shape=box];
    "Small inline flowchart" [shape=box];

    "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
    "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
    "Decision where I might go wrong?" -> "Use markdown" [label="no"];
}

仅在以下情况使用流程图：

  • 不明显的决策点
  • 可能过早停止的流程循环
  • 决定“何时使用 A 而非 B”

绝不要将流程图用于：

  • 参考资料 → 表格、列表
  • 代码示例 → Markdown 代码块
  • 线性说明 → 编号列表
  • 没有语义意义的标签（step1、helper2）

参阅 @graphviz-conventions.dot，了解 graphviz 样式规则。

代码示例

一个出色的示例胜过许多平庸的示例

选择最相关的语言：

  • 测试技术 → TypeScript/JavaScript
  • 系统调试 → Shell/Python
  • 数据处理 → Python

优秀示例应当：

  • 完整且可运行
  • 注释清晰，解释原因
  • 来源于真实场景
  • 清楚展示模式
  • 可直接改用（而非通用模板）

不要：

  • 用 5 种或更多语言实现
  • 创建填空式模板
  • 编写牵强的示例

你很擅长移植代码，一个出色的示例就足够了。

文件组织

独立技能
defense-in-depth/
  SKILL.md    # Everything inline

适用情况：所有内容都能容纳其中，无需大量参考资料

带可复用工具的技能
condition-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt

适用情况：工具是可复用代码，而不只是叙述性内容

带大量参考资料的技能
pptx/
  SKILL.md       # Overview + workflows
  pptxgenjs.md   # 600 lines API reference
  ooxml.md       # 500 lines XML structure
  scripts/       # Executable tools

适用情况：参考资料太多，不适合内嵌

铁律（与 TDD 相同）

NO SKILL WITHOUT A FAILING TEST FIRST

此规则适用于新技能以及对现有技能的编辑。

先写技能再测试？删除它，重新开始。 编辑技能却不测试？同样违反规则。

没有例外：

  • 不适用于“简单的补充”
  • 不适用于“只是添加一个章节”
  • 不适用于“文档更新”
  • 不要将未经测试的更改保留为“参考资料”
  • 测试运行期间不要“顺便修改”
  • 删除就是删除

参阅 skills/testing/test-driven-development，了解这为何重要。相同原则也适用于文档。

测试所有类型的技能

不同类型的技能需要不同的测试方法：

约束纪律的技能（规则／要求）

示例： TDD、完成前验证、先设计再编码

测试方法：

  • 学术问题：他们是否理解规则？
  • 压力场景：他们在压力下是否遵守规则？
  • 多重压力叠加：时间 + 沉没成本 + 疲惫
  • 找出合理化说辞，并添加明确的反驳

成功标准： Agent 在最大压力下仍遵守规则

技巧类技能（操作指南）

示例： 基于条件的等待、根因追踪、防御式编程

测试方法：

  • 应用场景：他们能否正确应用技巧？
  • 变化场景：他们能否妥善处理边界情况？
  • 信息缺失测试：说明中是否存在漏洞？

成功标准： Agent 能在新场景中成功应用技巧

模式类技能（思维模型）

示例： 降低复杂度、信息隐藏概念

测试方法：

  • 识别场景：他们能否识别何时适用该模式？
  • 应用场景：他们能否运用该思维模型？
  • 反例：他们是否知道何时不应应用？

成功标准： Agent 能正确判断何时以及如何应用模式

参考类技能（文档／API）

示例： API 文档、命令参考、库指南

测试方法：

  • 检索场景：他们能否找到正确的信息？
  • 应用场景：他们能否正确使用找到的信息？
  • 覆盖缺口测试：是否涵盖了常见用例？

成功标准： Agent 能找到并正确应用参考信息

跳过测试的常见合理化说辞

借口事实
“技能显然写得很清楚”对你来说清楚 ≠ 对其他 Agent 来说清楚。要测试。
“这只是参考资料”参考资料也可能存在漏洞或含糊不清的部分。要测试检索。
“测试是小题大做”未测试的技能总会有问题。15 分钟的测试可以省下数小时。
“出现问题时我再测试”出现问题 = Agent 无法使用技能。部署前就要测试。
“测试太繁琐了”测试比在生产环境中调试有缺陷的技能轻松。
“我确信它没问题”过度自信必然导致问题。无论如何都要测试。
“只做学术审查就够了”阅读 ≠ 使用。要测试应用场景。
“没时间测试”部署未经测试的技能，之后修复它会浪费更多时间。

以上所有说法都意味着：部署前先测试。没有例外。

防止技能被合理化说辞绕过

要求遵守纪律的技能（如 TDD）需要抵御合理化说辞。Agent 很聪明，在压力下会寻找漏洞。

心理学说明： 了解说服技巧为何有效，有助于你系统地运用它们。请参阅 persuasion-principles.md，了解有关权威、承诺、稀缺、社会认同和统一原则的研究基础（Cialdini，2021；Meincke 等人，2025）。

明确封堵每个漏洞

不要只陈述规则，还要禁止具体的变通做法：

```markdown Write code before test? Delete it. ``` ```markdown Write code before test? Delete it. Start over.

No exceptions:

  • Don't keep it as "reference"
  • Don't "adapt" it while writing tests
  • Don't look at it
  • Delete means delete
</Good>

### 回应“重精神轻字面”的说法

尽早加入基本原则：

```markdown
**Violating the letter of the rules is violating the spirit of the rules.**

这样可以杜绝一大类“我遵循了精神”的合理化说辞。

制作合理化说辞表

记录基线测试中的合理化说辞（见下文的“测试”部分）。Agent 提出的每个借口都要列入表中：

| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
创建危险信号列表

方便 Agent 在进行合理化时自我检查：

## Red Flags - STOP and Start Over

- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."

**All of these mean: Delete code. Start over with TDD.**
在 CSO 中补充违规迹象

在 when_to_use 中加入你即将违反规则时的迹象：

when_to_use: when implementing any feature or bugfix, before writing implementation code

面向技能的 RED-GREEN-REFACTOR

遵循 TDD 循环：

RED：编写失败测试（基线）

在不提供技能的情况下，让子 Agent 执行压力场景。记录具体行为：

  • 他们做出了哪些选择？
  • 他们用了哪些合理化说辞（原话）？
  • 哪些压力引发了违规？

这就是“观察测试失败”——编写技能前，必须先看看 Agent 自然会怎么做。

GREEN：编写精简技能

编写能解决这些特定合理化借口的技能。不要为假设情形添加额外内容。

使用技能再次运行相同场景。Agent 现在应该会遵从要求。

REFACTOR：堵住漏洞

Agent 找到了新的合理化借口？添加明确的反驳。重新测试，直到滴水不漏。

请参阅 skills/testing-skills-with-subagents，了解以下内容：

  • 如何编写压力场景
  • 压力类型（时间、沉没成本、权威、疲惫）
  • 如何系统地堵住漏洞
  • 元测试技术

反模式

❌ 叙事示例

“在 2025-10-03 的会话中，我们发现空的 projectDir 导致了……” **为什么不好：**过于具体，无法复用

❌ 多语言稀释

example-js.js、example-py.py、example-go.go **为什么不好：**质量平庸，维护负担重

❌ 流程图中的代码
step1 [label="import fs"];
step2 [label="read file"];

**为什么不好：**无法复制粘贴，难以阅读

❌ 通用标签

helper1、helper2、step3、pattern4 **为什么不好：**标签应具有语义

停止：开始下一个技能前

编写任何技能后，你都必须停止并完成部署流程。

不要：

  • 未经测试就批量创建多个技能
  • 当前技能尚未验证就转到下一个技能
  • 因为“批量处理效率更高”而跳过测试

以下部署清单对每个技能都必须执行。

部署未经测试的技能，就等于部署未经测试的代码。这违反了质量标准。

技能创建清单（TDD 改编版）

重要：使用 TodoWrite 为以下每个清单项目创建待办事项。

RED 阶段——编写失败测试：

  • 创建压力场景（纪律类技能需包含 3 种以上组合压力）
  • 在不使用技能的情况下运行场景——逐字记录基线行为
  • 找出合理化借口／失败中的模式

GREEN 阶段——编写精简技能：

  • 名称应描述你要做什么或核心见解
  • 编写包含丰富 when_to_use 内容的 YAML frontmatter（包括症状！）
  • 贯穿全文添加搜索关键词（错误、症状、工具）
  • 编写清晰的概述，说明核心原则
  • 针对 RED 阶段发现的具体基线失败提供解决方案
  • 将代码内联，或使用 @link 链接到单独文件
  • 提供一个出色的示例（不要使用多种语言）
  • 使用技能运行场景——验证 Agent 现在会遵从要求

REFACTOR 阶段——堵住漏洞：

  • 找出测试中出现的新合理化借口
  • 添加明确的反驳（如果是纪律类技能）
  • 根据所有测试迭代构建合理化借口表
  • 创建危险信号列表
  • 重新测试，直到滴水不漏

质量检查：

  • 仅在决策不明显时使用小型流程图
  • 提供快速参考表
  • 包含常见错误部分
  • 不讲述叙事故事
  • 仅在需要工具或大量参考资料时添加辅助文件

部署：

  • 将技能提交到 git，并推送到你的 fork（如果已配置）
  • 考虑通过 PR 回馈上游（如果对广泛用户都有用）

发现工作流

Claude 将来如何找到你的技能：

  1. 遇到问题（“测试不稳定”）
  2. 搜索技能——使用 find-skills 工具（搜索技能仓库）
  3. 找到 SKILL.md（丰富的 when_to_use 内容与需求相符）
  4. 浏览概述（这是否相关？）
  5. 阅读模式（快速参考表）
  6. 查看示例（仅在实施时）

针对这一流程进行优化——尽早且频繁地放置可搜索的词语。

核心要点

创建技能就是对流程文档应用 TDD。

同一条铁律：没有先编写失败测试，就不创建技能。 同一个周期：RED（基线）→ GREEN（编写技能）→ REFACTOR（堵住漏洞）。 同样的好处：质量更高、更少意外、结果滴水不漏。

如果你对代码遵循 TDD，也要对技能遵循 TDD。这是将同一种规范应用于文档。

评论

支持 Markdown