技能使用指南

writing-skills（技能撰写）Skill是什么？如何下载？

想写出代理真正遵守的 AI 技能却总被绕过？writing-skills（技能撰写）Skill 把测试驱动开发搬到文档写作：先用子代理跑压力场景观察失败，再写最小技能，最后逐个关闭理性化漏洞。本文详解安装位置与验证方法、RED-GREEN-REFACTOR 完整步骤、同类方案对比、典型应用场景与常见问题，帮你快速上手并沉淀可复用的技能资产。

技能撰写Skillwriting-skills
8 个章节 约 19 分钟阅读 AI 智能生成

技能撰写Skill：用测试驱动开发，把经验沉淀成不会失效的 AI 技能

  • 它是一套「写技能的方法论」：技能撰写Skill（writing-skills）把软件工程里的测试驱动开发（TDD）搬到文档写作上，要求「先看到代理失败，再写技能」，而不是凭感觉写一份说明书。
  • 核心循环是 RED-GREEN-REFACTOR：先用子代理跑压力场景观察基线失败（RED），再写最小技能让代理遵守（GREEN），最后针对新出现的「理性化借口」逐个关闭漏洞（REFACTOR）。
  • 它关心的是「代理会不会真的照做」：技能里专门处理「精神 vs 字面」「太简单不用测」这类自我说服，要求建立理性化对照表与红旗清单。
  • 它同时是一份技能写作规范：涵盖 SKILL.md 结构、frontmatter 限制、命名规则、令牌效率、Claude 搜索优化（CSO）与反模式清单。
  • 适合谁用：想把团队规范、调试经验、工具用法固化成可复用资产的开发者、效能团队与 AI 平台运营者。

1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？

基本信息

项目 内容
中文名 技能撰写Skill
英文名 writing-skills
技能ID 13638
技能类型 元技能（用于创建、编辑、验证其他技能）

它解决什么问题

很多人在给 AI 代理写技能时，会遇到同一类挫败：文档写得洋洋洒洒，代理该犯错还是犯错；规则写得很严厉，代理总能找到「我这次情况特殊」的理由绕过去；改完之后也不知道到底是变好了还是变差了。技能撰写Skill 的判断很直接——如果你没有观察过代理在没有技能时的失败，你就不知道这份技能是否教对了东西。它用 TDD 的方式，把「写文档」变成一次可验证、可迭代的工程过程。

安装前提

  1. 需要一个支持子代理（subagent）的代理环境，例如 Claude Code 或 Codex，因为技能的核心方法依赖「派子代理去跑压力场景」。
  2. 需要先理解测试驱动开发：技能自身明确标注了「必需背景」——使用前应理解 superpowers:test-driven-development 定义的基本 RED-GREEN-REFACTOR 周期，本技能只是把这个周期适配到文档上。
  3. 个人技能需要放到代理专属目录：技能说明中给出的是 Claude Code 的 ~/.claude/skills 与 Codex 的 ~/.codex/skills。

安装思路与步骤

  1. 获取技能包：通过你所使用的技能市场、官方分发渠道或团队内部仓库获取 writing-skills 技能。具体下载入口与命令以官方说明为准。
  2. 放入个人技能目录：将技能文件夹放入对应的 skills 目录。目录采用扁平命名空间，结构为 skills/技能名/SKILL.md，所有技能处于同一个可搜索命名空间中，不再套多层子目录。
  3. 检查文件完整性：确认 SKILL.md 存在（这是必需的主参考文件），如果有重型参考资料或可复用脚本，应作为同目录下的独立文件一并放入。
  4. 重新加载代理会话：多数环境需要重启会话或重新加载技能目录，让代理重新扫描技能列表。具体刷新方式以官方说明为准。
  5. 验证是否生效：新开一次对话，直接说「我要创建一个新技能」或「帮我按 TDD 流程验证这个技能」，观察代理是否会主动引用本技能的方法（例如先设计压力场景、先跑基线）。如果代理没有任何反应，先检查目录名与 SKILL.md 的 name 字段是否符合「仅字母、数字、连字符」的命名要求。

为什么这算「提升开发效率」：技能是一次性投入、长期复用的资产。写对一次，之后每一个新会话、每一个新项目都能直接受益；写错一次，则会在每次会话里反复误导代理。用 TDD 门槛换来的是「一次写对」。

2. 该技能的主要功能和特点

（1）把 TDD 完整映射到文档写作

TDD 概念 在技能创建中的对应物
测试用例 使用子代理的压力场景
生产代码 技能文档 SKILL.md
测试失败（RED） 代理在没有技能时违反规则（基线）
测试通过（GREEN） 代理在有技能时遵守
重构 在保持遵守的前提下关闭漏洞

（2）强制「先失败、后编写」的铁律

技能把「无技能没有先失败测试」写成不可协商的原则，并明确列出无例外情形：不为「简单添加」破例、不为「只加一小段」破例、不为「文档更新」破例。先写完再补测试？删掉重来。

（3）区分四类技能并提供对应测试方法

  • 纪律强制型（规则、要求）：用学术问题、压力场景、多重压力组合测试，成功标准是「在最大压力下仍然遵守」。
  • 技术型（操作指南）：用应用场景、变体场景、缺失信息测试，成功标准是「能迁移到新场景」。
  • 模式型（心智模型）：用识别场景、应用场景、反例测试，成功标准是「知道何时该用、何时不该用」。
  • 参考型（文档、API）：用检索场景、应用场景、覆盖缺口测试，成功标准是「找得到并用得对」。

（4）专治「理性化攻击」

技能把代理常见的借口整理成对照表（「太简单了不用测」「我事后测效果一样」「我遵循的是精神不是字面」），并要求把这些借口逐字记录、逐条写进技能的「借口 / 现实」表格与「红旗清单」，让未来的代理在动歪念头时能自我识别。

（5）内置 Claude 搜索优化（CSO）

  • description 必须以「Use when…」开头，聚焦触发条件，并用第三人称书写。
  • 描述「问题」而不是「语言特定症状」，除非技能本身就是技术特定的。
  • 关键词要覆盖错误消息、症状、同义词与实际工具名，方便未来会话检索到。
  • 命名推荐动词优先或动名词形式（如 creating-skills、testing-skills）。

（6）严格的格式与令牌预算

  • frontmatter 只支持 name 和 description 两个字段，总长度不超过 1024 字符；name 只允许字母、数字与连字符。
  • 令牌目标：入门工作流类技能每份低于 150 词；频繁加载的技能总量低于 200 词；其他技能低于 500 词。
  • 优先用「运行 --help 看详情」代替在文档里罗列所有参数；优先交叉引用其他技能代替重复写字。

（7）明确的交叉引用规则

需要依赖其他技能时，用技能名加醒目标记（如 **REQUIRED SUB-SKILL:**、**REQUIRED BACKGROUND:**），而不是写成模糊的路径引用；并且不要用 @ 语法链接文件，因为那会立即强制加载文件，提前消耗大量上下文。

（8）一份完整的反模式清单

叙述式案例（「某次会话我们发现…」）、同一示例用五种语言重复实现、在流程图里写代码、用 step1/helper2 这类无语义标签——这些都被明确列为坏味道。

和普通「写文档」比强在哪：普通文档只保证「写清楚了」，这个技能保证「代理会照做」，并且能证明这一点。

3. 如何使用该技能？

第 1 步：判断这个技能值不值得创建

创建条件：技术对你并不直观、你在项目中会反复参考、模式具有广泛适用性、其他人也能受益。 不创建条件：一次性解决方案、别处已有良好文档的标准实践、项目特定约定（这类应放进项目的 CLAUDE.md）。

第 2 步（RED）：设计压力场景并跑基线

向代理下达类似指令：「我要创建一个关于异步测试等待的技能，请你先设计 3 个压力场景，在不使用任何技能的情况下派子代理执行，并逐字记录它的行为与理由。」

要点：

  • 对纪律型技能，至少要组合 3 种以上压力（时间压力 + 沉没成本 + 疲劳）。
  • 逐字记录代理说出的借口，这些原话后面会变成「借口 / 现实」表格的一行。
  • 这一步的输出是失败模式清单，不是文档。

第 3 步（GREEN）：只写解决这些失败的最小技能

按 SKILL.md 的结构组织内容：概述（1-2 句核心原则）→ 何时使用 → 核心模式（前后对比）→ 快速参考表 → 实现（内联代码或文件链接）→ 常见错误。

frontmatter 示例（描述字段的写法参考，原文保留）：

---
name: condition-based-waiting
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests
---

中文理解：这条描述以「Use when」开头，先写触发症状（竞态条件、依赖时序、时好时坏），再写它做什么（用条件轮询替代任意超时）。注意它描述的是问题而非 setTimeout 这类实现细节。

第 4 步（验证 GREEN）：带技能重跑同一场景

用完全相同的场景、相同的压力，这次让代理加载技能后再执行。观察它是否遵守。如果不遵守，说明技能没有命中真实失败点，回到第 3 步。

第 5 步（REFACTOR）：关闭漏洞

代理找到新的绕行方式时，不要只重复规则，而要明确禁止具体变通：

写代码在测试之前？删掉，重新开始。 无例外：不要保留为「参考」，不要在写测试时「改造」它，不要看它，删除就是删除。

然后把所有测试中收集到的借口整理成对照表，再加一份红旗清单（「出现以下念头即停止并重来」），最后重新跑测试直到无懈可击。

第 6 步：质量与体积检查

确认没有叙述式案例、流程图只用于非明显的决策点、只有一个优秀示例而不是五种语言的平庸示例。用词数统计检查令牌预算：入门类技能每份低于 150 词，频繁加载类总量低于 200 词。

第 7 步：部署

提交到 git 并推送到你的分支；如果技能具有广泛适用性，可以考虑通过 PR 贡献回上游。

一个必须遵守的纪律：写完一个技能后停下来完成部署流程，不要批量创建多个技能却不逐个测试。「批量更高效」本身就是技能里点名批评的借口之一。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
技能撰写Skill（writing-skills） 过程文档的测试驱动开发方法论 压力场景基线测试、最小技能编写、理性化漏洞关闭、CSO 搜索优化、格式与令牌规范、四类技能测试法 中等偏高：需要支持子代理的环境，且需先理解测试驱动开发 团队规范沉淀、纪律型技能打磨、技能质量审核 优势：产出的技能经过验证，代理真正遵守；不足：流程较长，简单参考型技能显得「重」
手写系统提示词 / 项目约定文件（如 CLAUDE.md） 轻量级上下文约束 直接写规则、约定、偏好 极低：打开文件写几段话即可 项目特定约定、临时行为约束、个人习惯 优势：零成本、即时生效；不足：没有触发条件设计，容易被代理忽略或绕过，也无法复用与分发
官方技能创作最佳实践文档（技能中提及的 anthropic-best-practices.md） 官方指南与模式补充 技能作者的最佳实践、结构建议 低：阅读即可 首次接触技能格式、了解官方约定 优势：权威、覆盖面广；不足：偏指南性质，不强制「先失败后编写」的验证闭环，缺少对抗理性化的具体手法
superpowers:test-driven-development（通用 TDD 技能） 代码层面的测试驱动开发 RED-GREEN-REFACTOR 在代码上的落地 中等：需要理解 TDD 概念 写功能、修缺陷 优势：纪律性强、通用；不足：面向代码，不解决「文档怎么写、代理会不会照做」的问题，本技能正是它的文档版延伸
团队 Wiki / 知识库文档 人类可读的经验沉淀 文档协作、检索、评论 低 团队知识管理、新人上手 优势：人读友好、协作成熟；不足：不是为代理加载设计的，缺少触发描述与令牌预算控制，代理难以按需检索

选择建议：如果你只是想给项目加几条约定，手写项目约定文件足够；如果你要把一套方法固化下来、并且要求代理在压力下也遵守，就该用技能撰写Skill；如果只是想学技能文件格式，先读官方最佳实践即可。

5. 该技能的典型应用场景与实际体验情况

场景一：效能团队把团队编码规范固化成技能

  • 角色与痛点：平台效能团队写了一份「提交前必须自查」的规范文档，但代理在赶进度时总是直接交付，规范形同虚设。
  • 使用方式：先用子代理跑「时间紧张 + 已有半成品」的组合压力场景，记录代理的原始借口（例如「这次改动很小，跳过自查」），再把这些借口逐条写进「借口 / 现实」表和红旗清单。
  • 实际体验：上手难度中等偏上，难点不在写文档，而在设计出真正能压出问题的场景。效果好坏几乎完全取决于基线测试是否诚实——如果基线跑得敷衍，后面写出来的技能也只是漂亮话。注意事项：不要为了让测试「好看」而降低压力强度。

场景二：独立开发者沉淀自己的调试经验

  • 角色与痛点：一位开发者反复在异步测试里被「时好时坏」折磨，每次都要重新摸索一遍，想把这套经验存下来。
  • 使用方式：按技术型技能路径，用应用场景 + 变体场景 + 缺失信息测试来验证；描述字段按 CSO 要求写清触发症状与关键词（如「flaky」「hanging」「race condition」），保证未来的会话能搜到。
  • 实际体验：这类技能流程最短，通常一轮 RED-GREEN 就能收敛。收益体现在长期：以后每次遇到同类问题，代理能直接命中正确方法，而不是从头试错。注意事项：别把技能写成「我某天怎么解决的」这种流水账，那属于技能明确列出的反模式。

场景三：AI 平台运营审核第三方技能

  • 角色与痛点：平台要上架一批外部提交的技能，质量参差不齐，很多只有一段说明，没有任何验证依据。
  • 使用方式：把技能里的检查清单当审核表用——frontmatter 是否只有两个字段且不超过 1024 字符、name 是否只含字母数字连字符、描述是否第三人称且以「Use when」开头、是否有令牌预算控制、是否存在多语言稀释等反模式。
  • 实际体验：清单化之后审核速度明显提升，因为判断标准从「感觉写得不错」变成了「是否满足 N 条硬性条件」。注意事项：清单是底线不是上限，通过格式检查不代表内容一定有效，仍建议抽样做压力测试。

场景四：已有纪律型技能频繁被绕过，需要返工

  • 角色与痛点：某个规则类技能上线后，代理总能找到「我遵循的是精神而非字面」这类说辞。
  • 使用方式：进入 REFACTOR 阶段，在技能开头加上「违反规则的字面就是违反规则的精神」这条基础原则，一次性切断整类辩解；再把每次新发现的借口补进表格并重新测试。
  • 实际体验：这是投入产出比最高的一步。技能里明确指出，省略测试看似省时间，实际会在生产环境中花更多时间调试坏技能；而十几分钟的测试能省下数小时。注意事项：修复要「关闭漏洞」而不是「重复强调」，重复规则不会让代理更听话。

6. 该技能能为用户带来的价值

把「写文档」变成可验证的工程动作

以前判断一份技能好不好，只能靠读；现在有了基线测试与重测，好坏变成了可观察的事实。这直接减少了「文档写了一堆、代理该错还错」的无效投入。

显著降低技能的返工率

技能明确了一条经验：部署未测试的技能，等同于部署未测试的代码。把验证前置到编写阶段，避免的是上线后反复打补丁的隐性成本。

降低团队的经验流失

技能本质上是一份「经过验证的可复用资产」。团队里某个人踩过的坑、总结出的方法，一旦通过 TDD 流程固化成技能，就能被后续每一个会话、每一位成员直接调用，而不是留在某个人的记忆里。

控制长期的上下文成本

令牌预算规则（入门工作流每份低于 150 词、频繁加载类低于 200 词、其他低于 500 词）看起来是小事，实际上决定了技能能不能长期留在上下文里。写得越精简，能同时装载的技能就越多，代理的选择判断也越清晰。

提升技能被检索到的概率

通过「Use when…」开头的第三人称描述、关键词覆盖与动名词命名，技能在未来的会话里更容易被匹配到。写得再好的技能，如果检索不到，等于不存在。

长期价值：形成可治理的技能库

当创建、编辑、验证都遵循同一套 RED-GREEN-REFACTOR 周期，技能库就从「一堆散落的文档」变成「一套有质量标准、有审核依据、可迭代的资产」。

7. 常见问题 FAQ

Q1：这个技能怎么安装？有没有一键命令？

技能本身没有给出具体的安装命令。通用做法是：先确认你的代理环境支持子代理（如 Claude Code 或 Codex），把技能文件夹放进个人技能目录——Claude Code 为 ~/.claude/skills，Codex 为 ~/.codex/skills，目录结构为 技能名/SKILL.md，然后重启会话让代理重新扫描。具体的下载入口、命令与刷新方式以官方说明为准。

Q2：这个技能收费吗？

技能详情内容中没有涉及任何定价信息，因此无法给出确定答案。请以你所使用的技能市场或官方渠道的说明为准。

Q3：我不熟悉测试驱动开发，能直接用吗？

可以尝试，但效果会打折。技能本身把 superpowers:test-driven-development 列为「必需背景」，因为 RED-GREEN-REFACTOR 的节奏、什么叫「观察失败」、什么叫「最小实现」，都由那套方法定义。建议先花点时间理解 TDD 的基本循环，再回来使用本技能。

Q4：我就想写一个简单的参考型技能，能不能跳过测试？

技能给出的答案是明确的不能。它专门列了一张「跳过测试的常见理性化」对照表，覆盖了「技能明显清晰」「它仅是参考」「测试过度」「我确信它好」等说法，并给出统一回应：所有这些都意味着——在部署前测试，无例外。参考型技能同样有检索场景与覆盖缺口需要验证。

Q5：它和直接写 CLAUDE.md、或者和通用 TDD 技能有什么区别？

写项目约定文件是「一次性约束」，没有触发条件设计，也不可分发；通用 TDD 技能作用于代码，不解决文档如何被代理正确加载与遵守的问题。技能撰写Skill 是两者的补集：它把 TDD 的纪律搬到过程文档上，产出的是带触发描述、经过压力验证、可被检索和复用的技能资产。