القائمة
在创建新技能、编辑现有技能或在部署前验证技能工作时使用
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | writing-skills |
| description | 在创建新技能、编辑现有技能或在部署前验证技能工作时使用 |
编写技能就是应用于流程文档的测试驱动开发。
个人技能位于特定于代理的目录中（Claude Code 为 ~/.claude/skills，Codex 为 ~/.agents/skills/）
你编写测试用例（带有子代理的压力场景），观察它们失败（基线行为），编写技能（文档），观察测试通过（代理合规），并重构（关闭漏洞）。
**核心原则：**如果你没有看到没有技能时代代理失败的情况，你就不知道技能是否教导了正确的事情。
**必备背景：**在使用此技能之前，你必须理解 superpowers:test-driven-development。该技能定义了基本的 RED-GREEN-REFACTOR 循环。此技能将 TDD 适应于文档。
**官方指导：**有关 Anthropic 的官方技能编写最佳实践，请参阅 anthropic-best-practices.md。本文档提供了补充此技能中 TDD 专注方法的额外模式和指南。
技能是经过验证的技术、模式或工具的参考指南。技能帮助未来的 Claude 实例找到并应用有效的方法。
**技能是：**可重用的技术、模式、工具、参考指南
**技能不是：**关于你如何解决一次问题的叙述
| TDD 概念 | 技能创建 |
|---|---|
| 测试用例 | 带有子代理的压力场景 |
| 生产代码 | 技能文档（SKILL.md） |
| 测试失败（RED） | 代理在没有技能的情况下违反规则（基线） |
| 测试通过（GREEN） | 代理在存在技能的情况下合规 |
| 重构 | 在保持合规的同时关闭漏洞 |
| 先编写测试 | 在编写技能之前运行基线场景 |
| 观察它失败 | 逐字记录代理使用的确切合理化 |
| 最小代码 | 编写解决那些特定违规的技能 |
| 观察它通过 | 验证代理现在合规 |
| 重构循环 | 找到新的合理化 → 堵塞 → 重新验证 |
整个技能创建过程遵循 RED-GREEN-REFACTOR。
在以下情况下创建：
不要创建用于：
具有遵循步骤的具体方法（基于条件的等待、根本原因跟踪）
思考问题的方式（用标志扁平化、测试不变式）
API 文档、语法指南、工具文档（office 文档）
skills/
skill-name/
SKILL.md # 主要参考（必需）
supporting-file.* # 仅在需要时
扁平命名空间 - 所有技能在一个可搜索的命名空间中
为以下内容分离文件：
保持内联：
前置内容（YAML）：
name 和 description（有关所有支持字段，请参阅 agentskills.io/specification）name：仅使用字母、数字和连字符（无括号、特殊字符）description：第三人称，仅描述何时使用（而非它做什么）
---
name: Skill-Name-With-Hyphens
description: 在 [特定触发条件和症状] 时使用
---
# 技能名称
## 概述
这是什么？核心原则用1-2句话。
## 何时使用
[如果决策不明显，则使用小型内联流程图]
带有症状和用例的项目列表
何时不使用
## 核心模式（用于技术/模式）
之前/之后代码比较
## 快速参考
用于扫描常见操作的表或项目
## 实现
简单模式的内联代码
繁重参考或可重用工具的文件链接
## 常见错误
哪里出错了 + 修复
## 现实世界影响（可选）
具体结果
**对发现至关重要：**未来的 Claude 需要找到你的技能
**目的：**Claude 读取描述以决定为给定任务加载哪些技能。使其回答："我现在应该阅读这个技能吗？"
**格式：**以"Use when..."开头以专注于触发条件
关键：描述 = 何时使用，而非技能做什么
描述应仅描述触发条件。不要在描述中总结技能的流程或工作流程。
**为什么这很重要：**测试表明，当描述总结技能的工作流程时，Claude 可能会遵循描述而不是阅读完整的技能内容。说"任务之间的代码审查"的描述导致 Claude 进行一次审查，即使技能的流程图清楚地显示了两次审查（规范合规然后代码质量）。
当描述更改为"在当前会话中执行具有独立任务的实现计划时使用"（无工作流程摘要）时，Claude 正确地阅读了流程图并遵循了两阶段审查流程。
**陷阱：**总结工作流程的描述创建了 Claude 将采用的捷径。技能正文成为 Claude 跳过的文档。
# ❌ 糟糕：总结工作流程 - Claude 可能遵循此而不是阅读技能
description: 在执行计划时使用 - 在任务之间进行代码审查，每任务分派子代理
# ❌ 糟糕：过多的流程细节
description: 用于 TDD - 先编写测试，观察它失败，编写最小代码，重构
# ✅ 好：仅触发条件，无工作流程摘要
description: 在当前会话中执行具有独立任务的实现计划时使用
# ✅ 好：仅触发条件
description: 在实现任何功能或错误修复之前，在编写实现代码之前使用
内容：
# ❌ 糟糕：太抽象、模糊，不包括何时使用
description: 用于异步测试
# ❌ 糟糕：第一人称
description: 当测试不稳定时，我可以帮助你进行异步测试
# ❌ 糟糕：提到技术但技能并非特定于它
description: 当测试使用 setTimeout/sleep 并且不稳定时使用
# ✅ 好：以"Use when"开头，描述问题，无工作流程
description: 当测试具有竞争条件、时间依赖性或不一致地通过/失败时使用
# ✅ 好：具有显式触发的技术特定技能
description: 当使用 React Router 并处理认证重定向时使用
使用 Claude 会搜索的词：
使用主动语态，动词优先：
creating-skills 而不是 skill-creationcondition-based-waiting 而不是 async-test-helpers**问题：**getting-started 和经常引用的技能加载到每个对话中。每个 token 都很重要。
目标字数：
技术：
将细节移至工具帮助：
# ❌ 糟糕：在 SKILL.md 中记录所有标志
search-conversations 支持 --text、--both、--after DATE、--before DATE、--limit N
# ✅ 好：引用 --help
search-conversations 支持多种模式和过滤器。运行 --help 了解详细信息。
使用交叉引用：
# ❌ 糟糕：重复工作流程细节
搜索时，使用模板分派子代理...
[20行重复指令]
# ✅ 好：引用其他技能
始终使用子代理（节省 50-100x 上下文）。必需：使用 [other-skill-name] 进行工作流程。
压缩示例：
# ❌ 糟糕：冗长的示例（42 字）
你的人类伙伴："我们以前是如何在 React Router 中处理认证错误的？"
你：我将搜索过去对话中的 React Router 认证模式。
[分派子代理，搜索查询："React Router authentication error handling 401"]
# ✅ 好：最小的示例（20 字）
伙伴："我们以前如何在 React Router 中处理认证错误？"
你：搜索中...
[分派子代理 → 综合]
消除冗余：
验证：
wc -w skills/path/SKILL.md
# getting-started 工作流程：目标是每个少于 150
# 其他经常加载：总共少于 200
按照你做的事情或核心见解命名：
condition-based-waiting > async-test-helpersusing-skills 而不是 skill-usageflatten-with-flags > data-structure-refactoringroot-cause-tracing > debugging-techniques动名词（-ing）适用于流程：
creating-skills、testing-skills、debugging-with-logs在编写引用其他技能的文档时：
仅使用技能名称，并带有显式需求标记：
**必需子技能：**使用 superpowers:test-driven-development**必备背景：**你必须理解 superpowers:systematic-debugging参见 skills/testing/test-driven-development（不清楚是否必需）@skills/testing/test-driven-development/SKILL.md（强制加载，消耗上下文）为什么没有 @ 链接：@ 语法立即强制加载文件，在需要之前消耗 200k+ 上下文。
digraph when_flowchart {
"需要显示信息？" [shape=diamond];
"可能出错的决定？" [shape=diamond];
"使用 markdown" [shape=box];
"小型内联流程图" [shape=box];
"需要显示信息？" -> "可能出错的决定？" [label="yes"];
"可能出错的决定？" -> "小型内联流程图" [label="yes"];
"可能出错的决定？" -> "使用 markdown" [label="no"];
}
仅将流程图用于：
切勿将流程图用于：
参见 @graphviz-conventions.dot 了解 graphviz 样式规则。
**为你的人类伙伴可视化：**使用此目录中的 render-graphs.js 将技能的流程图渲染为 SVG：
./render-graphs.js ../some-skill # 每个图单独
./render-graphs.js ../some-skill --combine # 所有图在一个 SVG 中
一个优秀的示例胜过许多平庸的示例
选择最相关的语言：
好的示例：
不要：
你擅长移植 - 一个优秀的示例就足够了。
defense-in-depth/
SKILL.md # 所有内联
何时：所有内容都适合，不需要繁重的参考
condition-based-waiting/
SKILL.md # 概述 + 模式
example.ts # 可适应的工作助手
何时：工具是可重用的代码，而不仅仅是叙述
pptx/
SKILL.md # 概述 + 工作流程
pptxgenjs.md # 600 行 API 参考
ooxml.md # 500 行 XML 结构
scripts/ # 可执行工具
何时：参考材料太大而无法内联
没有失败的测试，就没有技能
这适用于新技能和现有技能的编辑。
在测试之前编写技能？删除它。重新开始。 在没有测试的情况下编辑技能？同样的违规。
无例外：
**必备背景：**superpowers:test-driven-development 技能解释了为什么这很重要。同样的原则适用于文档。
不同的技能类型需要不同的测试方法：
**示例：**TDD、完成前验证、设计前编码
测试用：
**成功标准：**代理在最大压力下遵循规则
**示例：**基于条件的等待、根本原因跟踪、防御性编程
测试用：
**成功标准：**代理成功将技术应用于新场景
**示例：**降低复杂性、信息隐藏概念
测试用：
**成功标准：**代理正确识别如何/何时应用模式
**示例：**API 文档、命令参考、库指南
测试用：
**成功标准：**代理找到并正确应用参考信息
| 借口 | 现实 |
|---|---|
| "技能显然很清楚" | 对你清楚 ≠ 对其他代理清楚。测试它。 |
| "这只是一个参考" | 参考可能有漏洞、不清楚的部分。测试检索。 |
| "测试是过度的" | 未经测试的技能有问题。总是这样。15分钟测试可以节省数小时。 |
| "如果出现问题我会测试" | 问题 = 代理无法使用技能。在部署之前测试。 |
| "测试太繁琐" | 测试比在生产环境中调试糟糕的技能更不繁琐。 |
| "我确信它很好" | 过度自信保证有问题。无论如何测试。 |
| "学术审查就足够了" | 阅读 ≠ 使用。测试应用场景。 |
| "没时间测试" | 部署未经测试的技能会浪费更多时间来修复它。 |
所有这些都意味着：在部署之前测试。无例外。
强制执行纪律的技能（如 TDD）需要抵御合理化。代理很聪明，在压力下会找到漏洞。
**心理学注释：**理解为什么说服技术有效有助于你系统地应用它们。请参阅 persuasion-principles.md 了解关于权威、承诺、稀缺性、社会认同和团结原则的研究基础（Cialdini, 2021; Meincke et al., 2025）。
不要只是陈述规则 - 禁止特定的变通方法：
```markdown 在测试之前编写代码？删除它。 ``` ```markdown 在测试之前编写代码？删除它。重新开始。无例外：
</Good>
### 解决"精神与字面"参数
早期添加基础原则：
```markdown
**违反规则的字面就是违反规则的精神。**
这切断了整个类别的"我在遵循精神"合理化。
从基线测试中捕获合理化（请参阅下面的测试部分）。代理做出的每个借口都进入表中：
| 借口 | 现实 |
|--------|---------|
| "太简单无法测试" | 简单的代码会出错。测试需要30秒。 |
| "我稍后会测试" | 测试立即通过证明不了什么。 |
| "测试后达到相同的目标" | 测试后 = "这做什么？"测试前 = "这应该做什么？" |
使代理在合理化时易于自我检查：
## 红旗 - 停止并重新开始
- 测试前的代码
- "我已经手动测试过了"
- "测试后达到相同的目的"
- "这关乎精神而非仪式"
- "这不同，因为..."
**所有这些都意味着：删除代码。用 TDD 重新开始。**
添加到描述：你将要违规时的症状：
description: 在实现任何功能或错误修复之前，在编写实现代码之前使用
遵循 TDD 循环：
在没有技能的情况下使用子代理运行压力场景。记录确切的行为：
这是"观察测试失败" - 在编写技能之前，你必须看到代理自然做什么。
编写解决那些特定合理化的技能。不要为假设情况添加额外内容。
使用技能运行相同的场景。代理现在应该合规。
代理找到了新的合理化？添加显式反制。重新测试直到防弹。
**测试方法：**请参阅 @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 **为什么糟糕：**标签应具有语义含义
在编写任何技能之后，你必须停止并完成部署流程。
不要：
下面的部署检查清单对于每个技能都是强制性的。
部署未经测试的技能 = 部署未经测试的代码。这违反质量标准。
**重要：**使用 TodoWrite 为下面检查清单中的每个项目创建待办事项。
RED 阶段 - 编写失败的测试：
GREEN 阶段 - 编写最小技能：
name 和 description 字段的 YAML 前置内容（最多 1024 个字符；请参阅 spec）REFACTOR 阶段 - 关闭漏洞：
质量检查：
部署：
未来的 Claude 如何找到你的技能：
为此流程优化 - 尽早并频繁放置可搜索的术语。
创建技能就是文档的 TDD。
相同的铁律：没有失败的测试，就没有技能。 相同的循环：RED（基线）→ GREEN（编写技能）→ REFACTOR（关闭漏洞）。 相同的收益：更好的质量，更少的意外，防弹的结果。
如果你对代码遵循 TDD，请对技能遵循 TDD。这是应用于文档的相同纪律。
桌面/网关运行时内置的计划创建技能，用于生成可落盘、可调度、可批次执行的结构化计划包。
桌面/网关运行时内置的计划执行技能，用于按批次执行结构化计划包中的单个任务文件。
Use when demonstrating or verifying VibeWindow local plugin packaging, including plugin skills, MCP servers, hook declarations, and interface metadata.
当需要在编码前创建或更新实施计划时使用，尤其适用于多步骤功能开发、重构、包含多个活动部件的缺陷修复，或需要拆分为可独立执行并跟踪进度的任务文件的请求。
当你有书面实现计划需要在单独会话中执行，并带有审查检查点时使用
通过 `rustcodegraph` 命令行界面使用 RustCodeGraph 理解、导航或脚本化操作已索引代码库。当用户要求使用 RustCodeGraph、需要高性能搜索检索代码、需要符号/源码/调用流上下文、调用方/被调用方/影响分析或受影响测试选择时使用。