# 拆superpowers：流程件是怎么写出来的 ## 概述 Skills 生态跑了快一年，市场上能数出两千多件货，但真正被开发者反复“抄作业”的模板，其实只有两三种。本期做这一轮该做的事：不追榜单，把社区里口碑最硬的技能合集 **obra/superpowers** 拎上解剖台，提炼它 SKILL.md 里可复用的写法模式；再用官方 brainstorming、社区 skill-factory、darwin-skill 做对照组，回答一个具体问题——**你想写自己的第一件 Skill，该从哪张纸上起笔**。本文的写法分析基于 superpowers 仓库公开文件与官方文档，涉及细节处以仓库现行版本为准。 ## 为什么拿它当标本 2025 年 10 月 Anthropic 把 Agent Skills 做成开放格式后，社区里第一个真正出圈的合集就是 superpowers，作者 Jesse Vincent，仓库在 github.com/obra/superpowers。它的走红不是靠功能猎奇——里面没有一件能画图、能做 PPT，全是“怎么干活”的流程件：怎么调试、怎么写测试、怎么定计划、怎么验收。作者当时以连载方式公开了整套技能的诞生过程，这批文章反过来成了很多人学写 SKILL.md 的教材。 一年过去，官方教程（skill-creator）和各类“造件指南”已经把基础知识扫清了，但“流程件”这个品类怎么写，仍然没有比 superpowers 更好的公开范本。这就是本期选它的理由：**不是它最新，而是它的写法被引用得最久。** ## 评测对比表 评分为本栏目基于仓库文件、公开文档与社区反馈的主观评测（1-5星），权重按固定维度： | Skill | 功能完整度(25%) | 设计质量(25%) | 实战效果(20%) | 上手难度(15%) | 社区活跃度(15%) | 加权总分 | |-------|------|------|------|------|------|------| | superpowers (obra) | ★★★★☆ | ★★★★★ | ★★★★☆ | ★★★☆☆ | ★★★★☆ | **4.20** | | brainstorming (官方) | ★★★☆☆ | ★★★★☆ | ★★★★☆ | ★★★★★ | ★★★★☆ | **3.95** | | skill-creator (官方) | ★★★★☆ | ★★★★☆ | ★★★☆☆ | ★★★★☆ | ★★★★★ | **3.95** | | skill-factory (社区) | ★★★☆☆ | ★★★☆☆ | ★★★☆☆ | ★★★★☆ | ★★★☆☆ | **3.20** | | darwin-skill (社区) | ★★★☆☆ | ★★★☆☆ | ★★★☆☆ | ★★★★☆ | ★★★☆☆ | **3.10** | 两个对照组的来历：brainstorming 是官方出品的交互件，装好后在 Claude Code 里用 `/brainstorming` 唤起，一次只问你一个问题，把模糊想法逐轮逼成设计文档；skill-factory 是社区的批量造件工具，把 Skill 分成人物视角、工作流、领域专家、内容创作、代码规范、工具集成六类模板；darwin-skill 则给已装技能打分，按功能完整度、上手难度、文档质量几个维度出评估，其安装市场页面此前显示安装量在 5,500 次以上。 ## 拆解：superpowers 的七种写法 ### 模式一：先选品类，再动笔 superpowers 全部几十件技能，几乎不做“知识件”（告诉你某个 API 怎么用），全做“流程件”（约束你按什么顺序干活）。这个选择背后有一条冷静的判断：**模型不缺知识，缺纪律。** 知识件写的那些内容，模型本来就答得出七八成，写进 SKILL.md 边际收益很低；而“先写测试再写实现”“改代码前先建 worktree”这类纪律，模型没人盯着就一定会跳步——把它们固化成技能，才是增量。 你自己动手前先过这一问：**我要写的这件事，是“查得到的知识”，还是“照着做才会发生的纪律”？** 前者省下这笔功夫，后者才值得开文件。 ### 模式二：description 是唯一的广告位 SKILL.md 的 frontmatter 只有 name 和 description 两个字段，而模型决定“要不要加载这件技能”，依据只有 description 那一行。superpowers 的每件技能都在这一行里完成三件事：说清做什么、点名触发词、划清不归它管的边界。官方文档对 description 的要求也是同一套：用第三人称写，把用户会真的说出口的短语埋进去。 可抄的句式骨架： ```yaml --- name: systematic-debugging description: 按假设-验证-收敛的流程修复缺陷。Use when debugging, when a fix didn't work, or when the root cause is unclear. --- ``` 注意第二句的写法：不是罗列关键词，而是**预判用户在什么处境下会说哪句话**。触发词设计做得好，技能不用喊就自己上岗；做得差，写一万字正文也是死库存。 ### 模式三：把“停下”写成明文 流程件和普通文档最大的区别，是它敢对模型说“停”。superpowers 的调试件、测试件里大量出现硬性护栏：大意是“如果测试还没写，先停下来写测试，不要继续动手”“一次只改一处，改完立刻验证”。这类句子用大写强调和短祈使句，让模型在惯性冲刺中被勒住。 普通作者写 SKILL.md 最常见的失败，是把正文写成一篇温和的说明文——模型读完点点头，然后照旧抢跑。护栏句式是对症的药： ```markdown ## 红线 - 测试未写，禁止动手实现 - 一次只改一处；改完立即验证，再改下一处 - 找不到根因时，禁止用 try/except 掩盖 ``` ### 模式四：技能之间互相接力 superpowers 不是几十件散货，而是一条流水线：想法模糊时进 brainstorming，出方案后接写计划，执行计划时挂上 TDD，卡住了切调试件，收尾前必须过验收件。前一件的正文会**指名道姓地引导模型去加载下一件**——上一站替下一站导流，整条链靠 description 里的触发词咬合。 这条流水线长这样： ```mermaid flowchart TD A["用户提出模糊想法"] --> B["brainstorming 逐题澄清"] B --> C["writing-plans 方案落成文档"] C --> D["executing-plans 小步执行"] D --> E["test-driven-development 先测后码"] E --> F["systematic-debugging 卡住就切"] F --> G["requesting-code-review 同伴评审"] G --> H["verification-before-completion 验收收尾"] ``` 对单人作者的含义：**你的第一件技能不必是整条链，但设计时就要想好它在哪一站、上下游是谁。** 孤岛技能的召回率和完成质量都会打折。 ### 模式五：完成的定义写进正文 流程件最怕“看起来做完了”。superpowers 的收尾件要求模型在宣布完成前，逐项给出证据：测试跑过没有、输出贴在哪、验收清单核到第几条。大意是“没有证据的完成，按未完成处理”。 这一段是可以直接搬走的： ```markdown ## 完成的定义 - 全部步骤执行完毕，无跳步 - 测试命令及其输出已展示 - 交付物路径明确列出 - 有任何一步没做到，明确报告未完成，不使用含糊措辞 ``` ### 模式六：正文瘦身，重货外挂 superpowers 的单件 SKILL.md 普遍不长，细节靠支撑文件外挂——这是官方格式设计的三层披露：模型平时只看见 name 和 description（几十个 token），触发后才读 SKILL.md 正文，需要时再按正文指引去读 references 目录、跑 scripts 目录。官方 xlsx、pdf 这些重量级件也是同一思路：SKILL.md 只留流程骨架，几百行的操作细节和确定性脚本都沉到支撑文件里。 给你的操作纪律：**SKILL.md 超过两屏，就该往 references 里搬了。** 正文只留“判断”，能写成脚本确定性执行的活，绝不留给模型发挥。 ### 模式七：一件只装一个扳机 本机实录一个现象：这台装了四百余件技能的 Claude Code 环境里，同一功能拆成多件的现象比比皆是——openstoryline 拆成 install 和 use 两件，course-video-maker 一族有四个变体，光 pptx 相关命名的就有五件，gstack 还分了 local 版。四百余件里，以人名命名的人设件超过半数，是生态里被复制最多的模板。 拆牌不是洁癖，是召回工程：**技能粒度越粗，description 越要兼顾多个场景，触发就越含糊；一rm件一个扳机，每个 description 才能写准。** 新手第一件常犯的错，就是把“安装、使用、排错”塞进同一件里，结果三个场景互相稀释，一个都触发不稳。 ## 你的第一件：起笔顺序 综合上面的模式，落笔顺序建议如下—— 1. **选品类**：流程件优先。写下这句话并回答它：“没有这件技能时，模型在这件事上会犯什么具体的错？”答不出具体错误，说明还不需要写。 2. **写 description**：两句话，第一句说做什么，第二句埋触发词和边界，把用户真会说出口的短语放进去。 3. **列步骤**：编号列表，每步一个动词开头，步骤之间不共用宾语。 4. **设红线**：写出三到五条“出现即停”的信号，用短祈使句。 5. **定验收**：完成的标准是什么、要出示什么证据。 6. **压长度**：超过两屏的部分搬去 references，确定性逻辑写成脚本进 scripts。 7. **测触发**：换个新会话，用用户口吻说三句不同的话，看它召不召回。召回不稳，回去改 description。 最小骨架模板： ```markdown --- name: my-first-skill description: 一句话说清做什么。Use when 用户会这样说起这件事… --- # 一句话职责 ## 何时用 / 何时不用 ## 步骤 1. … ## 红线 - … ## 完成的定义 - … ``` ## 安装命令 ```bash # superpowers（安装方式以其仓库 README 为准，走 Claude Code 插件市场） # 仓库：github.com/obra/superpowers # 官方交互件：头脑风暴 npx skills add anthropic/brainstorming -g -y # 官方造件教程件（含脚本模板，位于官方 skills 仓库） # 仓库：github.com/anthropics/skills # 社区造件工厂 npx skills add kylin-feng/skill-factory -g -y # 技能评分器 npx skills add alchaincyf/darwin-skill@darwin-skill -g -y ``` ## 推荐排行榜 - **写第一件，先装这个**：brainstorming——用一次官方交互件，比读十篇教程更快理解“逐题逼问”这个设计 - **进阶必抄**：superpowers——护栏句式、技能接力、验收收尾三个模式全部有现成范文 - **查格式规范**：anthropics/skills 官方仓库与官方文档 - **批量起号**：skill-factory——六类模板适合快速铺量，质量仍需人工校 - **装前体检**：darwin-skill——先评分再安装，过滤死库存 ## 一句话收束 Skills 生态的货越来越多，但写法收敛得比想象中快：**description 定生死，红线管纪律，验收出证据，粒度保召回。** 你要写的那件技能，四件事占全了，就已经超过货架上的大多数存货。 ## 参考来源 1. [anthropics/skills](https://github.com/anthropics/skills) — 官方 Skills 仓库，SKILL.md 格式规范与官方示例件的原始出处 2. [obra/superpowers](https://github.com/obra/superpowers) — 本文主要标本，社区流程件合集，写法细节以仓库现行文件为准 3. [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Anthropic 工程博客对 Skills 设计理念（渐进披露、description 触发）的官方阐述 4. [Claude Code Docs: Skills](https://code.claude.com/docs/en/skills) — 官方文档中关于 frontmatter 字段与触发机制的说明 5. 本机安装实测（2026-10-03，Claude Code 环境）— 四百余件技能的品类构成与命名变体现象为实机清点 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。