jnmetacode/superpowers-zh/writing-skills

Claude Code and agent skill by jnmetacode/superpowers-zh

Trust tier 2
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

当创建新技能、编辑现有技能或在部署前验证技能是否有效时使用

Install

npx vskill@latest install jnmetacode/superpowers-zh/writing-skills

SKILL.md

The same SKILL.md was published earlier as jnmetacode/superpowers-zh/writing-skills.

编写技能

概述

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

个人技能存放在你所用运行环境的技能目录中(Claude Code 上是 ~/.claude/skills/)——其他运行环境的路径见 codex-tools.md 或 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 结构

执行此步骤前,必须从磁盘读取 完整指导,按其中的规则执行;上下文压缩后再次读取。

技能发现优化(SDO)

执行此步骤前,必须从磁盘读取 完整指导,按其中的规则执行;上下文压缩后再次读取。

流程图使用

执行此步骤前,必须从磁盘读取 完整指导,按其中的规则执行;上下文压缩后再次读取。

代码示例

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

选择最相关的语言:

  • 测试技术 → 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,除非它很重要"会重新打开谈判 —— 在同一批措辞测试里,给一个胜出的配方追加一条"视情况"从句,就把它从稳定退化成了飘忽。真正的例外要表达成它自己的条件句,挂在可观察的谓词上。
  • 豁免条款不会限定作用域。 "这条长度限制不适用于代码块",照样会压制代码块。如果产出里有一部分必须豁免,就重构结构让规则碰不到它,而不是写豁免。

让技能经受住合理化的考验

执行此步骤前,必须从磁盘读取 完整指导,按其中的规则执行;上下文压缩后再次读取。

技能的红-绿-重构

遵循 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)
  • [ ] 描述以"Use when..."开头并包含具体的触发条件/症状
  • [ ] 描述用第三人称
  • [ ] 全文包含搜索关键词(错误、症状、工具)
  • [ ] 带有核心原则的清晰概述
  • [ ] 解决红色阶段识别出的具体基线失败
  • [ ] 代码内联或链接到独立文件
  • [ ] 一个优秀的示例(非多语言)
  • [ ] 用技能运行场景 - 验证智能体现在遵守

重构阶段 - 堵住漏洞:

  • [ ] 从测试中识别新的合理化借口
  • [ ] 添加明确的反驳(纪律类技能)
  • [ ] 从所有测试迭代中构建合理化借口表
  • [ ] 创建红线列表
  • [ ] 重新测试直到无懈可击

质量检查:

  • [ ] 仅在决策不明显时使用小流程图
  • [ ] 快速参考表
  • [ ] 常见错误章节
  • [ ] 无叙事性故事
  • [ ] 支持文件仅用于工具或大量参考

部署:

  • [ ] 将技能提交到 git 并推送到你的 fork(如果已配置)
  • [ ] 考虑通过 PR 贡献回去(如果具有广泛用途)

发现工作流

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

  1. 遇到问题("测试不稳定")
  2. 找到技能(描述匹配)
  3. 浏览概述(这相关吗?)
  4. 阅读模式(快速参考表)
  5. 加载示例(仅在实现时)

为此流程优化 - 把可搜索的术语放在前面和各处。

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
8,248
Repository forks
770
7-day trend score
45

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/jnmetacode/superpowers-zh/writing-skills/badge)](https://verified-skill.com/skills/jnmetacode/superpowers-zh/writing-skills)

Something wrong with this skill or its page? Tell us.