mcpField
W
writing-skills

writing-skills

github.com/pcvelzAgent 工作流1.3k65 次安装1 周前更新
代码仓库

关于 writing-skills

writing-skills 是面向 Claude 技能作者的指南，将测试驱动开发用于流程文档，通过压力场景验证技能是否能改变 Agent 的行为。

主要功能

  1. 01以 RED-GREEN-REFACTOR 编写技能
  2. 02用子 Agent 压力场景测试技能
  3. 03提供技能结构与命名指导
  4. 04涵盖搜索优化与文件组织

适用场景

  1. 01编写可复用的 Agent 技能
  2. 02验证技能是否解决行为偏差

安装

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

$npx skills add https://github.com/pcvelz/superpowers --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

详细介绍

编写技能

概述

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

个人技能存放在 ~/.claude/skills/。

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

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

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

官方指南： 关于 Anthropic 官方的技能编写最佳实践，请参阅 anthropic-best-practices.md。本文档提供了其他模式和指南，用以补充此技能中以 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）

目录结构

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

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

单独存放以下内容：

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

内联保留：

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

SKILL.md 结构

Frontmatter（YAML）：

  • 两个必填字段：name 和 description（所有受支持字段请参阅 agentskills.io/specification）
  • 总计最多 1024 个字符
  • name：仅使用字母、数字和连字符（不要使用括号或特殊字符）
  • description：使用第三人称，仅描述何时使用（而非它的作用）
    • 以“Use when...”开头，聚焦于触发条件
    • 包含具体症状、情形和上下文
    • 绝不要概述技能的流程或工作流（原因见 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）

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

1. 丰富的描述字段

目的： Claude 会读取描述，判断是否要为给定任务加载相应技能。描述应能回答：“我现在应该阅读这个技能吗？”

格式： 以“Use when...”开头，聚焦于触发条件

关键：描述 = 何时使用，而非技能的用途

描述应仅说明触发条件。不要在描述中概述技能的流程或工作流。

为何重要： 测试发现，当描述概述技能的工作流时，Claude 可能会遵循描述，而不阅读完整的技能内容。一条写着“在任务之间进行代码审查”的描述，会让 Claude 只进行一次审查，即使技能流程图明确显示需要进行两次审查（先检查规格符合性，再检查代码质量）。

将描述改为仅写“Use when executing implementation plans with independent tasks”（不概述工作流）后，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. 提高令牌效率（关键）

问题： 入门和常用技能会加载到每一段对话中。每个令牌都很重要。

目标字数：

  • 入门工作流：每项少于 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-extended-cc:test-driven-development
  • ✅ 好：**REQUIRED BACKGROUND:** You MUST understand superpowers-extended-cc: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-conventions.dot，了解 Graphviz 样式规则。

**为你的搭档可视化：**使用此目录中的 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

优秀示例应当：

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

不要：

  • 用 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-extended-cc:test-driven-development 技能解释了这为何重要。相同原则也适用于文档。

测试所有技能类型

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

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

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

测试方法：

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

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

技术型技能（操作指南）

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

测试方法：

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

**成功标准：**Agent 能成功地将该技术应用于新场景

模式型技能（心智模型）

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

测试方法：

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

**成功标准：**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）

重要：使用 TaskCreate 为以下清单中的每一项创建任务。

RED 阶段 - 编写失败测试：

  • 创建压力场景（纪律类技能需包含 3 种或更多组合压力）
  • 在不使用技能的情况下运行场景 - 逐字记录基线行为
  • 找出合理化说辞/失败模式

GREEN 阶段 - 编写最简技能：

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

REFACTOR 阶段 - 堵住漏洞：

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

质量检查：

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

部署：

  • 将技能提交到 git 并推送到你的 fork（如果已配置）
  • 考虑通过 PR 贡献回社区（如果具有广泛用途）

发现工作流

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

  1. 遇到问题（“测试不稳定”）
  2. 找到 SKILL（描述相符）
  3. 浏览概述（这是否相关？）
  4. 阅读模式（速查表）
  5. 加载示例（仅在实施时）

针对这一工作流进行优化 - 尽早并频繁地使用便于搜索的术语。

评论

支持 Markdown