技能撰写Skill writing-skills

---

name: writing-skills description: 用于创建新技能、编辑现有技能或在部署前验证技能工作 - 通过在使用子代理测试前编写过程文档来应用测试驱动开发，迭代直到抵御理性化攻击

写作技能

概述

写作技能是应用于过程文档的测试驱动开发。

个人技能位于代理特定目录中（Claude Code 的 ~/.claude/skills，Codex 的 ~/.codex/skills）

您编写测试用例（使用子代理的压力场景），观察它们失败（基线行为），编写技能（文档），观察测试通过（代理遵守），并重构（关闭漏洞）。

核心原则： 如果您没有观察代理在没有技能时的失败，您不知道技能是否教授了正确的东西。

必需背景： 您必须理解 superpowers:test-driven-development 才能使用此技能。该技能定义了基本的 RED-GREEN-REFACTOR 周期。此技能将 TDD 适配到文档。

官方指南： 有关 Anthropic 的官方技能作者最佳实践，请参见 anthropic-best-practices.md。本文档提供了额外模式和指南，以补充此技能中的 TDD 聚焦方法。

什么是技能？

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

技能是： 可重用技术、模式、工具、参考指南

技能不是： 关于您如何一次解决问题的叙述

技能的 TDD 映射

TDD 概念	技能创建
测试用例	使用子代理的压力场景
生产代码	技能文档 (SKILL.md)
测试失败 (RED)	代理在没有技能时违反规则（基线）
测试通过 (GREEN)	代理在有技能时遵守
重构	在保持遵守的同时关闭漏洞
先写测试	在编写技能前运行基线场景
观察失败	记录代理使用的确切理性化
最小代码	编写技能解决那些特定违反
观察通过	验证代理现在遵守
重构周期	找到新理性化 → 插入 → 重新验证

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

何时创建技能

创建当：

• 技术对您不直观明显
• 您会在项目中再次参考此
• 模式广泛适用（非项目特定）
• 其他人会受益

不为以下创建：

• 一次性解决方案
• 在其他地方很好文档化的标准实践
• 项目特定约定（放在 CLAUDE.md）

技能类型

技术

具有步骤的具体方法（条件等待、根因追踪）

模式

思考问题的方式（带标志展平、测试不变量）

参考

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

目录结构

skills/
  skill-name/
    SKILL.md              # 主要参考（必需）
    supporting-file.*     # 仅当需要时

扁平命名空间 - 所有技能在一个可搜索命名空间中

单独文件用于：

1. 重型参考 (100+ 行) - API 文档、全面语法
2. 可重用工具 - 脚本、实用程序、模板

保持内联：

• 原则和概念
• 代码模式 (< 50 行)
• 其他一切

SKILL.md 结构

Frontmatter (YAML)：

• 仅支持两个字段：name 和 description
• 最大总 1024 字符
• name：仅使用字母、数字和连字符（无括号、特殊字符）
• description：第三人称，包括它做什么和何时使用它
  • 以“Use when…”开头，聚焦触发条件
  • 包括具体症状、情况和上下文
  • 如果可能，保持低于 500 字符

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms] - [what the skill does and how it helps, written in third person]
---

# Skill Name

## Overview
这是什么？1-2 句核心原则。

## When to Use
[如果决策非明显，小内联流程图]

带症状和使用案例的子弹列表
何时不使用

## Core Pattern (for techniques/patterns)
前后代码比较

## Quick Reference
用于扫描常见操作的表或子弹

## Implementation
简单模式的内联代码
用于重型参考或可重用工具的文件链接

## Common Mistakes
出错什么 + 修复

## Real-World Impact (optional)
具体结果

Claude 搜索优化 (CSO)

发现关键： 未来的 Claude 需要找到您的技能

1. 丰富描述字段

目的： Claude 读取描述以决定为给定任务加载哪些技能。让它回答：“我现在应该读此技能吗？”

格式： 以“Use when…”开头，聚焦触发条件，然后解释它做什么

内容：

• 使用具体触发、症状和表示此技能适用的情况
• 描述问题（竞争条件、不一致行为）而非语言特定症状（setTimeout、sleep）
• 保持触发技术无关，除非技能本身是技术特定的
• 如果技能是技术特定的，在触发中明确
• 以第三人称写作（注入系统提示）

# ❌ 坏：太抽象、模糊、不包括何时使用
description: For async testing

# ❌ 坏：第一人称
description: I can help you with async tests when they're flaky

# ❌ 坏：提及技术但技能不特定于它
description: Use when tests use setTimeout/sleep and are flaky

# ✅ 好：以“Use when”开头，描述问题，然后它做什么
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests

# ✅ 好：技术特定技能，明确触发
description: Use when using React Router and handling authentication redirects - provides patterns for protected routes and auth state management

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 词（仍要简洁）

技术：

将细节移到工具帮助：

# ❌ 坏：在 SKILL.md 中记录所有标志
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# ✅ 好：参考 --help
search-conversations supports multiple modes and filters. Run --help for details.

使用交叉引用：

# ❌ 坏：重复工作流细节
When searching, dispatch subagent with template...
[20 lines of repeated instructions]

# ✅ 好：参考其他技能
Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.

压缩示例：

# ❌ 坏：详细示例 (42 词)
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"]

# ✅ 好：最小示例 (20 词)
Partner: "How did we handle auth errors in React Router?"
You: Searching...
[Dispatch subagent → synthesis]

消除冗余：

• 不要在交叉引用技能中重复
• 不要解释从命令明显的内容
• 不要包括相同模式的多个示例

验证：

wc -w skills/path/SKILL.md
# 入门工作流：目标每个 <150
# 其他频繁加载：目标总 <200

按您做什么或核心洞察命名：

• ✅ 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 vs B” 决策

绝不对以下使用流程图：

• 参考材料 → 表、列表
• 代码示例 → Markdown 块
• 线性指令 → 编号列表
• 无语义意义的标签（step1、helper2）

参见 @graphviz-conventions.dot 用于 graphviz 样式规则。

代码示例

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

选择最相关语言：

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

好示例：

• 完整且可运行
• 良好注释解释 WHY
• 来自真实场景
• 清晰显示模式
• 准备好适应（非通用模板）

不要：

• 用 5+ 语言实现
• 创建填空模板
• 编写人为示例

您擅长移植 - 一个伟大示例足够。

文件组织

自包含技能

defense-in-depth/
  SKILL.md    # 一切内联

当：所有内容适合，无需重型参考

带可重用工具的技能

condition-based-waiting/
  SKILL.md    # 概述 + 模式
  example.ts  # 工作助手以适应

当：工具是可重用代码，非仅叙述

带重型参考的技能

pptx/
  SKILL.md       # 概述 + 工作流
  pptxgenjs.md   # 600 行 API 参考
  ooxml.md       # 500 行 XML 结构
  scripts/       # 可执行工具

当：参考材料太大，无法内联

铁律（与 TDD 相同）

无技能没有先失败测试

这适用于新技能和现有技能的编辑。

先写技能再测试？删除它。重新开始。

编辑技能不测试？相同违反。

无例外：

• 非为“简单添加”
• 非为“仅添加部分”
• 非为“文档更新”
• 不要将未测试更改保持为“参考”
• 不要“适应”当运行测试时
• 删除意味着删除

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

测试所有技能类型

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

纪律强制技能（规则/需求）

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

测试用：

• 学术问题：他们理解规则吗？
• 压力场景：他们在压力下遵守吗？
• 多个压力组合：时间 + 沉没成本 + 疲劳
• 识别理性化并添加明确计数器

成功标准： 代理在最大压力下遵循规则

技术技能（操作指南）

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

测试用：

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

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

模式技能（心理模型）

示例： reducing-complexity、information-hiding concepts

测试用：

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

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

参考技能（文档/API）

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

测试用：

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

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

跳过测试的常见理性化

借口	现实
“技能明显清晰”	对您清晰 ≠ 对其他代理清晰。测试它。
“它仅是参考”	参考可能有缺口、不清晰部分。测试检索。
“测试过度”	未测试技能有问题。总是。15 分钟测试节省小时。
“我会测试如果问题出现”	问题 = 代理无法使用技能。在部署前测试。
“太繁琐测试”	测试比在生产中调试坏技能繁琐少。
“我确信它好”	过度自信保证问题。无论如何测试。
“学术审查足够”	阅读 ≠ 使用。测试应用场景。
“无时间测试”	部署未测试技能浪费更多时间稍后修复。

所有这些意味着：在部署前测试。无例外。

使技能抵御理性化

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

心理注意： 理解为什么说服技术有效帮助您系统应用它们。参见 persuasion-principles.md 用于研究基础（Cialdini, 2021; Meincke et al., 2025）关于权威、承诺、稀缺、社会证明和团结原则。

明确关闭每个漏洞

不要仅陈述规则 - 禁止特定变通：

<Bad>

Write code before test? Delete it.

</Bad>

<Good>

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 字母”论点

早期添加基础原则：

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

这切断整个类“我遵循精神”理性化。

构建理性化表

从基线测试捕获理性化（参见测试部分）。代理制作的每个借口都进入表：

| 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?" |

创建红旗列表

让代理在理性化时自检容易：

## 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: use when implementing any feature or bugfix, before writing implementation code

RED-GREEN-REFACTOR 用于技能

遵循 TDD 周期：

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

运行压力场景与子代理 WITHOUT 技能。记录确切行为：

• 他们做了哪些选择？
• 他们使用了哪些理性化（逐字）？
• 哪些压力触发违反？

这是“观察测试失败” - 您必须在编写技能前观察代理自然做什么。

GREEN：编写最小技能

编写技能解决那些特定理性化。不要为假设案例添加额外内容。

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

REFACTOR：关闭漏洞

代理找到新理性化？添加明确计数器。重新测试直到无懈可击。

必需子技能： 使用 superpowers:testing-skills-with-subagents 用于完整测试方法：

• 如何编写压力场景
• 压力类型（时间、沉没成本、权威、疲劳）
• 系统插入孔
• 元测试技术

反模式

❌ 叙述示例

“In session 2025-10-03, we found empty projectDir caused…” 为什么坏： 太特定，不可重用

❌ 多语言稀释

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

❌ 流程图中的代码

step1 [label="import fs"];
step2 [label="read file"];

为什么坏： 无法复制粘贴，难读

❌ 通用标签

helper1、helper2、step3、pattern4 为什么坏： 标签应有语义意义

STOP：在移动到下一技能前

在编写任何技能后，您必须 STOP 并完成部署过程。

不要：

• 批量创建多个技能而不测试每个
• 在验证当前技能前移动到下一技能
• 跳过测试，因为“批处理更高效”

下面的部署清单对每个技能是强制性的。

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

技能创建清单（TDD 适配）

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

RED 阶段 - 编写失败测试：

• [ ] 创建压力场景（对纪律技能 3+ 组合压力）
• [ ] 运行场景 WITHOUT 技能 - 逐字记录基线行为
• [ ] 识别理性化/失败模式

GREEN 阶段 - 编写最小技能：

• [ ] 名称仅使用字母、数字、连字符（无括号/特殊字符）
• [ ] YAML frontmatter 仅带名称和描述（最大 1024 字符）
• [ ] 描述以“Use when…”开头，并包括具体触发/症状
• [ ] 描述以第三人称写作
• [ ] 关键词贯穿用于搜索（错误、症状、工具）
• [ ] 清晰概述带核心原则
• [ ] 解决 RED 中识别的特定基线失败
• [ ] 代码内联或链接到单独文件
• [ ] 一个优秀示例（非多语言）
• [ ] 运行场景 WITH 技能 - 验证代理现在遵守

REFACTOR 阶段 - 关闭漏洞：

• [ ] 从测试识别新理性化
• [ ] 添加明确计数器（如果纪律技能）
• [ ] 从所有测试迭代构建理性化表
• [ ] 创建红旗列表
• [ ] 重新测试直到无懈可击

质量检查：

• [ ] 仅如果决策非明显，小流程图
• [ ] 快速参考表
• [ ] 常见错误部分
• [ ] 无叙述讲故事
• [ ] 支持文件仅用于工具或重型参考

部署：

• [ ] 提交技能到 git 并推送到您的分支（如果配置）
• [ ] 考虑通过 PR 贡献回（如果广泛有用）

发现工作流

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

1. 遇到问题（“测试 flaky”）
2. 找到 SKILL（描述匹配）
3. 扫描概述（这相关吗？）
4. 读模式（快速参考表）
5. 加载示例（仅当实现时）

优化此流 - 早期和经常放置可搜索术语。

底线

创建技能是过程文档的 TDD。

相同铁律：无技能没有先失败测试。 相同周期：RED（基线） → GREEN（编写技能） → REFACTOR（关闭漏洞）。 相同好处：更好质量、更少惊喜、无懈可击结果。

如果您对代码遵循 TDD，对技能遵循它。这是相同纪律应用于文档。