mcpField
W
writing-skills

writing-skills

github.com/thedesignprojectAgent 工作流98174 次安装9 周前更新
代码仓库

关于 writing-skills

writing-skills 面向需要创建可复用 Agent 技能的人，将测试驱动开发用于文档编写，通过比较编写前后的 Agent 行为验证技能效果。

主要功能

  1. 01用压力场景测试技能
  2. 02比较有无技能时的行为
  3. 03根据观察到的失败编写文档
  4. 04修订文档以弥补漏洞
  5. 05技能结构与可发现性指南

适用场景

  1. 01将一项技巧整理成可复用技能
  2. 02检查技能是否改变 Agent 行为
  3. 03发现遵循缺口后改进技能

安装

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

$npx skills add https://github.com/thedesignproject/agent-skills --skill writing-skills

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

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

anthropic-best-practices.md
graphviz-conventions.dot
persuasion-principles.md
render-graphs.js
testing-skills-with-subagents.md
examples/
CLAUDE_MD_TESTING.md

详细介绍

编写 Skills

概述

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

个人 Skills 位于特定 Agent 的目录中（Claude Code 使用 ~/.claude/skills，Codex 使用 ~/.agents/skills/）

编写测试用例（通过子 Agent 设计压力场景），观察测试失败（基线行为），编写 Skill（文档），观察测试通过（Agent 遵守要求），然后重构（堵上漏洞）。

核心原则： 如果你没有观察过 Agent 在没有 Skill 时失败，就不知道 Skill 是否教会了正确的做法。

必备背景知识： 使用此 Skill 前，你必须理解 superpowers:test-driven-development。该 Skill 定义了基本的 RED-GREEN-REFACTOR 循环。此 Skill 将 TDD 应用于文档编写。

官方指南： Anthropic 官方的 Skill 编写最佳实践，请参阅 anthropic-best-practices.md。本文档提供了补充模式和指南，与此 Skill 以 TDD 为重点的方法相辅相成。

什么是 Skill？

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

Skills 是： 可复用的技巧、模式、工具和参考指南

Skills 不是： 关于某一次问题解决过程的叙述

Skills 的 TDD 映射

TDD 概念Skill 创建
测试用例与子 Agent 一起设计的压力场景
生产代码Skill 文档（SKILL.md）
测试失败（RED）Agent 在没有 Skill 时违反规则（基线）
测试通过（GREEN）提供 Skill 后 Agent 遵守要求
重构堵上漏洞，同时保持合规
先写测试编写 Skill 之前运行基线场景
观察失败记录 Agent 使用的确切合理化说辞
最少代码编写 Skill，针对这些具体违规行为
观察通过验证 Agent 现在是否遵守要求
重构循环找出新的合理化说辞 → 堵上漏洞 → 重新验证

整个 Skill 创建流程都遵循 RED-GREEN-REFACTOR。

何时创建 Skill

适合创建的情况：

  • 你觉得某种技巧并非直观易懂
  • 你会在多个项目中再次参考它
  • 该模式适用范围广（而非仅适用于特定项目）
  • 其他人也能从中受益

不适合创建的情况：

  • 一次性解决方案
  • 其他地方已有完善文档的标准实践
  • 项目特定的约定（应放入 CLAUDE.md）
  • 机械性约束（如果能用正则表达式或验证机制强制执行，就将其自动化；把文档留给需要判断的情况）

Skill 类型

技巧

包含具体步骤的方法（condition-based-waiting、root-cause-tracing）

模式

思考问题的方式（flatten-with-flags、test-invariants）

参考资料

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

目录结构

skills/
  skill-name/
    SKILL.md              # Main reference (required)
    supporting-file.*     # Only if needed

扁平命名空间——所有 Skills 都位于一个可搜索的命名空间中

以下内容使用独立文件：

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

以下内容保留在文档内：

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

SKILL.md 结构

Frontmatter（YAML）：

  • 两个必填字段：name 和 description（所有受支持字段请参阅 agentskills.io/specification）
  • 总计最多 1024 个字符
  • name：仅使用字母、数字和连字符（不使用括号或特殊字符）
  • description：使用第三人称，仅描述何时使用（而非它的功能）
    • 以“Use when...”开头，聚焦于触发条件
    • 包含具体症状、情形和上下文
    • 绝不要概述 Skill 的流程或工作流（原因请参阅 CSO 部分）
    • 尽量控制在 500 个字符以内
---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---

# 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）

对发现 Skill 至关重要： 未来的 Claude 必须能够找到你的 Skill

1. 丰富的描述字段

目的： Claude 会读取 description 来决定为给定任务加载哪些技能。让它回答："我现在应该读取这个技能吗？"

格式： 以"当……时使用"开头，聚焦触发条件

关键：Description = 何时使用，而非技能做什么

description 应只描述触发条件。不要在 description 中总结技能的流程或工作流。

为什么这很重要： 测试表明，当 description 总结了技能的工作流时，Claude 可能会遵循 description，而不是读取完整的技能内容。一个写着"任务之间的代码审查"的 description 导致 Claude 只做了一次审查，尽管技能的流程图清楚地显示需要两次审查（规范符合性审查，然后是代码质量审查）。

当 description 改为仅"在执行具有独立任务的实现计划时使用"（不包含工作流总结）后，Claude 正确地读取了流程图并遵循了两阶段审查流程。

陷阱： 总结工作流的 description 制造了 Claude 会走捷径的通道。技能正文变成了 Claude 跳过的文档。

# ❌ BAD: Summarizes workflow - Claude may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ❌ BAD: Too much process detail
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# ✅ GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session

# ✅ GOOD: Triggering conditions only
description: Use when implementing any feature or bugfix, before writing implementation code

内容：

  • 使用具体的触发器、症状和表明此技能适用的情境
  • 描述问题（竞态条件、行为不一致），而非特定语言的症状（setTimeout、sleep）
  • 保持触发器与技术无关，除非技能本身是特定于技术的
  • 如果技能是特定于技术的，请在触发器中明确说明
  • 使用第三人称书写（注入到系统提示词中）
  • 绝不要总结技能的流程或工作流
# ❌ BAD: Too abstract, vague, doesn't include when to use
description: For async testing

# ❌ BAD: First person
description: I can help you with async tests when they're flaky

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

# ✅ GOOD: Starts with "Use when", describes problem, no workflow
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# ✅ GOOD: Technology-specific skill with explicit trigger
description: Use when using React Router and handling authentication redirects
2. 关键词覆盖

使用 Claude 会搜索的词语：

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

使用主动语态，动词优先：

  • ✅ creating-skills 而非 skill-creation
  • ✅ condition-based-waiting 而非 async-test-helpers
4. Token 效率（关键）

问题： getting-started 和频繁引用的技能会加载到每次对话中。每个 token 都很重要。

目标词数：

  • getting-started 工作流：每个 <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). REQUIRED: Use [other-skill-name] 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. 交叉引用其他技能

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

仅使用技能名称，并带有明确的要求标记：

  • ✅ 正确：**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development
  • ✅ 正确：**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging
  • ❌ 错误：See skills/testing/test-driven-development（不清楚是否为必需）
  • ❌ 错误：@skills/testing/test-driven-development/SKILL.md（强制加载，消耗上下文）

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

流程图使用

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 风格规则，参见 @graphviz-conventions.dot。

为你的真人搭档可视化： 使用此目录中的 render-graphs.js 将技能的流程图渲染为 SVG：

./render-graphs.js ../some-skill           # Each diagram separately
./render-graphs.js ../some-skill --combine # All diagrams in one SVG

代码示例

一个优秀的示例胜过许多平庸的示例

选择最相关的语言：

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

好的示例：

  • 完整且可运行
  • 注释良好，解释 WHY
  • 来自真实场景
  • 清晰地展示模式
  • 可直接改编（不是通用模板）

不要：

  • 用 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

这适用于新技能以及对现有技能的编辑。

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

没有例外：

  • 不适用于“简单添加”
  • 不适用于“只是添加一节”
  • 不适用于“文档更新”
  • 不要将未测试的改动保留为“参考”
  • 不要在运行测试时“改编”
  • 删除就是删除

必需背景： superpowers:test-driven-development 技能解释了这为何重要。同样的原则适用于文档。

测试所有技能类型

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

纪律约束型技能（规则/要求）

示例： TDD、verification-before-completion、designing-before-coding

测试方式：

  • 学术性问题：他们理解规则吗？
  • 压力场景：他们在压力下会遵守吗？
  • 多种压力叠加：时间 + 沉没成本 + 疲惫
  • 找出合理化借口并添加明确的应对措施

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

技术型技能（操作指南）

示例： condition-based-waiting、root-cause-tracing、defensive-programming

测试方式：

  • 应用场景：他们能正确应用该技术吗？
  • 变体场景：他们能处理边缘情况吗？
  • 缺失信息测试：指令有遗漏吗？

成功标准： Agent 成功将技术应用于新场景

模式型技能（心智模型）

示例： reducing-complexity、information-hiding 概念

测试方式：

  • 识别场景：他们能识别模式何时适用吗？
  • 应用场景：他们能使用该心智模型吗？
  • 反例：他们知道何时不该应用吗？

成功标准： Agent 正确识别何时/如何应用模式

参考型技能（文档/API）

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

测试方式：

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

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

跳过测试的常见合理化借口

借口现实
“技能显然很清晰”对你清晰 ≠ 对其他 Agent 清晰。测试它。
“这只是个参考”参考可能有遗漏、章节不清晰。测试检索。
“测试是过度设计”未经测试的技能必定有问题。总是如此。15 分钟测试能省下数小时。
“有问题我再测试”问题 = Agent 无法使用技能。部署前就要测试。
“测试太繁琐”测试比在生产环境调试糟糕技能要不繁琐得多。
“我有信心它很好”过度自信必然带来问题。无论如何都要测试。
“学术评审就够了”阅读 ≠ 使用。测试应用场景。
“没时间测试”部署未经测试的技能，之后修复会浪费更多时间。

所有这些都意味着：部署前先测试。没有例外。

为技能加固以抵御合理化

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

心理学提示： 理解说服技巧为何有效，有助于你系统地应用它们。关于权威、承诺、稀缺、社会认同和统一原则的研究基础（Cialdini, 2021; Meincke et al., 2025），参见 persuasion-principles.md。

明确堵住每一个漏洞

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

```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>

### 应对“精神 vs 字面”的争论

尽早加入基础原则：

```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

在 description 中加入：你即将违反规则时的症状：

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

技能的 RED-GREEN-REFACTOR

遵循 TDD 循环：

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

在 WITHOUT 该技能的情况下，用 subagent 运行压力场景。记录确切行为：

  • 他们做了哪些选择？
  • 他们使用了哪些合理化（逐字记录）？
  • 哪些压力触发了违规？

这就是“看着测试失败”——在编写技能之前，你必须看到 Agent 自然会怎么做。

GREEN：编写最小技能

编写针对那些具体合理化的技能。不要为假设情况添加额外内容。

WITH 该技能运行相同场景。Agent 现在应该遵守。

REFACTOR：堵住漏洞

Agent 发现了新的合理化？添加明确的应对。重新测试直到无懈可击。

测试方法论： 完整测试方法论见 @testing-skills-with-subagents.md：

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

反模式

❌ 叙事式示例

“在 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 为什么不好： 标签应具有语义含义

停止：在进入下一个技能之前

编写 ANY 技能之后，你必须停止并完成部署流程。

不要：

  • 批量创建多个技能而不逐个测试
  • 在当前技能验证之前就进入下一个技能
  • 因为“批处理更高效”而跳过测试

下面的部署清单对 EACH 技能都是强制性的。

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

技能创建检查清单（适配 TDD）

重要：使用 TodoWrite 为下方每个检查项创建待办事项。

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

  • 创建压力场景（针对规范类技能，包含 3 种或更多压力因素）
  • 在不使用技能的情况下运行场景——逐字记录基线行为
  • 找出合理化说辞／失败行为中的模式

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

  • 名称仅使用字母、数字和连字符（不含括号／特殊字符）
  • YAML frontmatter 包含必需的 name 和 description 字段（最多 1024 个字符；参见 规范）
  • 描述以 "Use when..." 开头，并包含具体触发条件／症状
  • 描述使用第三人称撰写
  • 在全文中加入便于搜索的关键词（错误、症状、工具）
  • 提供清晰的概述，阐明核心原则
  • 解决在 RED 阶段发现的具体基线失败问题
  • 内嵌代码，或链接到单独的文件
  • 提供一个优秀示例（不使用多种语言）
  • 使用技能运行场景——验证 Agent 现在能够遵循要求

REFACTOR 阶段——堵住漏洞：

  • 找出测试中出现的新合理化说辞
  • 添加明确的反制措施（如果是规范类技能）
  • 根据所有测试迭代结果创建合理化说辞表
  • 创建危险信号列表
  • 反复重新测试，直到无懈可击

质量检查：

  • 仅在决策过程不明显时使用小型流程图
  • 添加快速参考表
  • 添加常见错误部分
  • 不要采用叙事性写作
  • 仅在工具或参考资料篇幅较大时使用辅助文件

部署：

  • 将技能提交到 git 并推送到你的 fork（如果已配置）
  • 考虑通过 PR 回馈贡献（如果对更多人有用）

发现工作流

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

  1. 遇到问题（"测试不稳定"）
  2. 找到 SKILL（描述与问题匹配）
  3. 浏览概述（这是否相关？）
  4. 查看模式（快速参考表）
  5. 加载示例（仅在实现时）

针对这个流程进行优化——尽早并频繁地加入便于搜索的术语。

总结

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

相同的铁律：没有先失败的测试，就不创建技能。 相同的循环：RED（基线）→ GREEN（编写技能）→ REFACTOR（堵住漏洞）。 相同的收益：质量更高、意外更少、结果无懈可击。

如果你对代码采用 TDD，也要对技能采用 TDD。这是将同样的规范应用于文档。

评论

支持 Markdown