jnMetaCode/superpowers-zh / skills/writing-skills
writing-skills
Verified当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.6 KB |
| anthropic-best-practices.md | markdown | 41.5 KB |
| examples/CLAUDE_MD_TESTING.md | markdown | 5.3 KB |
| graphviz-conventions.dot | other | 5.8 KB |
| persuasion-principles.md | markdown | 5.3 KB |
| references/bulletproofing.md | markdown | 2.0 KB |
| references/discovery.md | markdown | 5.8 KB |
| references/flowcharts.md | markdown | 1.2 KB |
| references/skill-template.md | markdown | 1.2 KB |
| render-graphs.jsexecutable | script | 5.5 KB |
| testing-skills-with-subagents.md | markdown | 12.1 KB |
SKILL.md
View on GitHub---
name: writing-skills
description: 当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用
version: "1.9.1"
license: MIT
metadata:
hermes:
tags: [skills, documentation]
---
# 编写技能
## 概述
**编写技能就是将测试驱动开发应用于流程文档。**
**个人技能存放在你所用运行环境的技能目录中**(Claude Code 上是 `~/.claude/skills/`)——其他运行环境的路径见 [codex-tools.md](../using-superpowers/references/codex-tools.md) 或 [gemini-tools.md](../using-superpowers/references/gemini-tools.md)。Codex、Copilot CLI 和 Gemini CLI 也都认 `~/.agents/skills/`,作为跨运行环境的别名。
你编写测试用例(带子智能体的压力场景),观察它们失败(基线行为),编写技能(文档),观察测试通过(智能体遵守规则),然后重构(堵住漏洞)。
**核心原则:** 如果你没有观察到智能体在没有该技能时失败,你就不知道这个技能是否教了正确的东西。
**必需背景:** 在使用此技能前,你必须理解 test-driven-development。该技能定义了基本的红-绿-重构循环。本技能将 TDD 适配到文档编写中。
**官方指南:** Anthropic 官方的技能编写最佳实践请参见 anthropic-best-practices.md。该文档提供了补充本技能 TDD 导向方法的额外模式和指南。
## 什么是技能?
**技能**是经过验证的技术、模式或工具的参考指南。技能帮助未来的 Claude 实例找到并应用有效的方法。
**技能是:** 可复用的技术、模式、工具、参考指南
**技能不是:** 关于你某次如何解决问题的叙事
## TDD 映射到技能
| TDD 概念 | 技能创建 |
|----------|---------|
| **测试用例** | 带子智能体的压力场景 |
| **生产代码** | 技能文档(SKILL.md) |
| **测试失败(红)** | 智能体在没有技能时违反规则(基线) |
| **测试通过(绿)** | 智能体在有技能时遵守规则 |
| **重构** | 在保持合规的同时堵住漏洞 |
| **先写测试** | 在编写技能之前先运行基线场景 |
| **观察失败** | 记录智能体使用的确切合理化借口 |
| **最小代码** | 编写针对那些具体违规行为的技能 |
| **观察通过** | 验证智能体现在遵守规则 |
| **重构循环** | 发现新的合理化借口 → 堵住 → 重新验证 |
整个技能创建过程遵循红-绿-重构。
## 何时创建技能
**创建条件:**
- 技术对你来说不是直觉上显而易见的
- 你会在不同项目中反复引用
- 模式具有广泛适用性(非项目特定)
- 其他人也会受益
**不要创建:**
- 一次性解决方案
- 其他地方有充分文档的标准实践
- 项目特定的约定(放在 CLAUDE.md 中)
- 机械性约束(如果可以用正则/验证强制执行,就自动化——文档留给需要判断的场景)
## 技能类型
### 技术类
有具体步骤的方法(condition-based-waiting、root-cause-tracing)
### 模式类
思考问题的方式(flatten-with-flags、test-invariants)
### 参考类
API 文档、语法指南、工具文档(office docs)
## 目录结构
```
skills/
skill-name/
SKILL.md # 主参考文档(必需)
supporting-file.* # 仅在需要时
```
**扁平命名空间** - 所有技能在一个可搜索的命名空间中
**分离文件的情况:**
1. **大量参考内容**(100+ 行)- API 文档、全面的语法说明
2. **可复用工具** - 脚本、实用程序、模板
**保持内联:**
- 原则和概念
- 代码模式(< 50 行)
- 其他所有内容
## SKILL.md 结构
**执行此步骤前,必须从磁盘读取** [完整指导](references/skill-template.md),按其中的规则执行;上下文压缩后再次读取。
## 技能发现优化(SDO)
**执行此步骤前,必须从磁盘读取** [完整指导](references/discovery.md),按其中的规则执行;上下文压缩后再次读取。
## 流程图使用
**执行此步骤前,必须从磁盘读取** [完整指导](references/flowcharts.md),按其中的规则执行;上下文压缩后再次读取。
## 代码示例
**一个优秀的示例胜过多个平庸的**
选择最相关的语言:
- 测试技术 → TypeScript/JavaScript
- 系统调试 → Shell/Python
- 数据处理 → Python
**好的示例:**
- 完整可运行
- 注释良好,解释为什么
- 来自真实场景
- 清晰展示模式
- 可以直接适配(不是通用模板)
**不要:**
- 用 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/ # 可执行工具
```
适用场景:参考资料太多无法内联
在正文里调用技能自带的脚本时,要通过解释器来调用(`bash scripts/tool.sh`、`node scripts/tool.js`),绝不用裸路径:有些运行环境的插件打包器会去掉可执行位,在那里裸写 `scripts/tool.sh` 会以 `Permission denied` 失败。
## 铁律(与 TDD 相同)
```
没有失败的测试就不写技能
```
这适用于新技能和对现有技能的编辑。
先写技能再测试?删掉它。重新开始。
编辑技能不测试?同样违规。
**无例外:**
- 不适用于"简单的添加"
- 不适用于"只是加一个章节"
- 不适用于"文档更新"
- 不要保留未测试的更改作为"参考"
- 不要在运行测试时"调整"
- 删除就是删除
**必需背景:** test-driven-development 技能解释了为什么这很重要。相同的原则适用于文档。
## 测试所有技能类型
不同类型的技能需要不同的测试方法:
### 纪律执行类技能(规则/要求)
**例如:** TDD、完成前验证、编码前设计
**测试方式:**
- 学术性问题:它们理解规则吗?
- 压力场景:它们在压力下遵守吗?
- 多重压力组合:时间 + 沉没成本 + 疲惫
- 识别合理化借口并添加明确的反驳
**成功标准:** 智能体在最大压力下遵循规则
### 技术类技能(操作指南)
**例如:** condition-based-waiting、root-cause-tracing、defensive-programming
**测试方式:**
- 应用场景:它们能正确应用技术吗?
- 变体场景:它们能处理边界情况吗?
- 缺失信息测试:说明是否有遗漏?
**成功标准:** 智能体成功将技术应用于新场景
### 模式类技能(心智模型)
**例如:** reducing-complexity、information-hiding 概念
**测试方式:**
- 识别场景:它们能识别模式何时适用吗?
- 应用场景:它们能使用心智模型吗?
- 反例:它们知道何时不应用吗?
**成功标准:** 智能体正确识别何时/如何应用模式
### 参考类技能(文档/API)
**例如:** API 文档、命令参考、库指南
**测试方式:**
- 检索场景:它们能找到正确的信息吗?
- 应用场景:它们能正确使用找到的内容吗?
- 覆盖测试:常见用例是否都涵盖了?
**成功标准:** 智能体找到并正确应用参考信息
## 跳过测试的常见合理化借口
| 借口 | 现实 |
|------|------|
| "技能显然很清晰" | 对你清晰 ≠ 对其他智能体清晰。测试它。 |
| "这只是参考资料" | 参考资料可能有遗漏、不清楚的地方。测试检索。 |
| "测试太过了" | 未测试的技能总有问题。15 分钟测试省下数小时。 |
| "有问题再测试" | 问题 = 智能体无法使用技能。在部署前测试。 |
| "测试太繁琐" | 测试比在生产中调试坏技能少繁琐得多。 |
| "我有信心它很好" | 过度自信保证出问题。无论如何都要测试。 |
| "学术审查就够了" | 阅读 ≠ 使用。测试应用场景。 |
| "没时间测试" | 部署未测试的技能比后面修复浪费更多时间。 |
**以上所有都意味着:部署前测试。无例外。**
## 让形式匹配失败类型
在写指导内容之前,先给基线失败**归类**。能让某一类失败变得无懈可击的形式,用在另一类上会**可测量地反噬**。
| 基线失败 | 正确的形式 | 错误的形式 |
|---|---|---|
| 压力之下跳过/违反规则(明知故犯) | 禁令 + 合理化借口表 + 红线(见下方"让技能经受住合理化的考验") | 软性建议("优先……"、"考虑……") |
| 遵守了,但产出的**形状**不对(提示词臃肿、结论被埋、复述规格) | 正面配方或契约:直接说明产出**是什么** —— 它由哪些部分组成、按什么顺序 | 禁令清单("不要复述"、"绝不旁白") |
| 在他们**本来就会产出**的东西里漏掉了必需元素 | 结构性手段:在他们要填的模板里放一个 REQUIRED 字段或占位槽 | 在模板附近写散文式提醒 |
| 行为**应当取决于某个条件** | 挂在可观察谓词上的条件句("如果简报存在,就引用它") | 无条件规则 + 一堆例外条款 |
**为什么禁令在"塑形"类问题上会反噬:** 在存在竞争性激励时(比如"让提示词自包含"),智能体会**跟"不要 X"讨价还价**。在针对分派提示词指导做的同题措辞对照测试里,禁令组产出的不想要的内容明显**多于**配方组(两组分布完全分离),甚至比"完全不给指导"的对照组还差 —— 请对你自己的场景做微型测试,别想当然,但**永远不要把禁令当默认选择**。配方留不下可讨价还价的空间:产出要么符合所说的形状,要么不符合。
**无论你选哪种形式,都适用的规则:**
- **不要加"视情况"从句。** "不要 X,除非它很重要"会重新打开谈判 —— 在同一批措辞测试里,给一个胜出的配方追加**一条**"视情况"从句,就把它从稳定退化成了飘忽。真正的例外要表达成**它自己的**条件句,挂在可观察的谓词上。
- **豁免条款不会限定作用域。** "这条长度限制不适用于代码块",照样会压制代码块。如果产出里有一部分必须豁免,就**重构结构让规则碰不到它**,而不是写豁免。
## 让技能经受住合理化的考验
**执行此步骤前,必须从磁盘读取** [完整指导](references/bulletproofing.md),按其中的规则执行;上下文压缩后再次读取。
## 技能的红-绿-重构
遵循 TDD 循环:
### 红:编写失败的测试(基线)
在没有技能的情况下运行压力场景。逐字记录行为:
- 它们做了什么选择?
- 它们使用了什么合理化借口(原文)?
- 哪些压力触发了违规?
这就是"观察测试失败"——在编写技能之前你必须看到智能体自然会怎么做。
### 绿:编写最小技能
编写针对那些具体合理化借口的技能。不要为假设情况添加额外内容。
用技能运行相同的场景。智能体应该现在遵守。
### 重构:堵住漏洞
智能体找到了新的合理化借口?添加明确的反驳。重新测试直到无懈可击。
### 先做措辞微型测试,再跑完整场景
完整的压力场景是最后一道关卡,但它每轮迭代都又慢又贵。先用**微型测试**验证措辞本身:
1. **每次调用一个全新上下文的样本** —— 一次裸 API 调用,或者没有 API 权限时用一个单发子智能体。system prompt 放**这条指导实际会存在的真实上下文**(完整的 skill 或提示词模板,不是把指导单独拎出来);user message 放一个会**诱发该失败**的任务。
2. **永远带一个"不给指导"的对照组。** 如果对照组根本没表现出那个失败,那就没什么可修的 —— 停下,别写这条指导。
3. **每个变体至少 5 次重复。** 单个样本会骗人。
4. **每一条被标记的命中都要人工读一遍。** 想用程序打分可以,但模板回声和被引用的反例会**伪装成命中**;只看自动计数会同时高估失败和成功。
5. **方差本身就是一个指标。** 指导真正生效时,多次重复会收敛到同一种形状。5 次重复出现 5 种不同解读,说明这个措辞**没有约束力** —— 先收紧形式,别急着加字。
微型测试验证的是**措辞**;对纪律执行类技能,它**不能替代**压力场景。
**测试方法论:** 参见 @testing-skills-with-subagents.md 了解完整的测试方法:
- 如何编写压力场景
- 压力类型(时间、沉没成本、权威、疲惫)
- 系统地堵住漏洞
- 元测试技巧
## 反模式
### 叙事式示例
"在 2025-10-03 的会话中,我们发现空的 projectDir 导致了……"
**为什么不好:** 太具体,不可复用
### 多语言稀释
example-js.js、example-py.py、example-go.go
**为什么不好:** 质量平庸,维护负担重
### 流程图中的代码
```dot
step1 [label="import fs"];
step2 [label="read file"];
```
**为什么不好:** 无法复制粘贴,难以阅读
### 通用标签
helper1、helper2、step3、pattern4
**为什么不好:** 标签应有语义意义
## 停下:进入下一个技能之前
**编写任何技能后,你必须停下来完成部署流程。**
**不要:**
- 批量创建多个技能而不逐个测试
- 在当前技能验证前就进入下一个
- 因为"批量处理更高效"就跳过测试
**下面的部署清单对每个技能都是强制性的。**
部署未测试的技能 = 部署未测试的代码。这是对质量标准的违反。
## 技能创建清单(TDD 适配版)
**重要:使用 TodoWrite 为下面的每个清单项创建待办。**
**红色阶段 - 编写失败的测试:**
- [ ] 创建压力场景(纪律类技能需 3 个以上组合压力)
- [ ] 在没有技能的情况下运行场景 - 逐字记录基线行为
- [ ] 识别合理化借口中的模式
**绿色阶段 - 编写最小技能:**
- [ ] 名称只使用字母、数字、连字符(无括号/特殊字符)
- [ ] YAML frontmatter 包含必需的 `name` 和 `description` 字段(最多 1024 字符;参见 [spec](https://agentskills.io/specification))
- [ ] 描述以"Use when..."开头并包含具体的触发条件/症状
- [ ] 描述用第三人称
- [ ] 全文包含搜索关键词(错误、症状、工具)
- [ ] 带有核心原则的清晰概述
- [ ] 解决红色阶段识别出的具体基线失败
- [ ] 代码内联或链接到独立文件
- [ ] 一个优秀的示例(非多语言)
- [ ] 用技能运行场景 - 验证智能体现在遵守
**重构阶段 - 堵住漏洞:**
- [ ] 从测试中识别新的合理化借口
- [ ] 添加明确的反驳(纪律类技能)
- [ ] 从所有测试迭代中构建合理化借口表
- [ ] 创建红线列表
- [ ] 重新测试直到无懈可击
**质量检查:**
- [ ] 仅在决策不明显时使用小流程图
- [ ] 快速参考表
- [ ] 常见错误章节
- [ ] 无叙事性故事
- [ ] 支持文件仅用于工具或大量参考
**部署:**
- [ ] 将技能提交到 git 并推送到你的 fork(如果已配置)
- [ ] 考虑通过 PR 贡献回去(如果具有广泛用途)
## 发现工作流
未来的 Claude 如何找到你的技能:
1. **遇到问题**("测试不稳定")
3. **找到技能**(描述匹配)
4. **浏览概述**(这相关吗?)
5. **阅读模式**(快速参考表)
6. **加载示例**(仅在实现时)
**为此流程优化** - 把可搜索的术语放在前面和各处。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |