# skills

**Repository Path**: chen613528/skills

## Basic Information

- **Project Name**: skills
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-13
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Superpowers 技能使用指南（通用版）

> **文档定位**：本指南随技能包一起分发，介绍技能包内每个技能"是什么、干什么用、什么时候用"。
> **使用方式**：**《一、技能速览》供使用者快速查阅**；《三、技能详解》供深入了解；其余章节主要为 AI 维护本文档而写。
> **适用范围**：任何安装了本技能包的 AI 编程环境（Claude Code、Cursor、Codex、WorkBuddy、Gemini CLI 等）。
> **可移植性**：本文档不含任何特定电脑信息，可在不同机器间直接复用。
> **维护方式**：技能有增删时，按文末《七、如何维护本文档》操作。**交给 AI 完善时，直接引用第七节的规范即可。**

---

## 一、技能速览

> 本表是全文核心查阅入口。技能包当前共 **10** 个技能。**新增/移除技能时，必须同步更新本表行数与上方数量标注。**

| 技能 | 中文名 | 干什么用 | 什么时候用 |
|---|---|---|---|
| brainstorming | 设计构思 | 把想法聊成完整设计，先确认方案再动手 | 提需求、做任何新功能之前 |
| writing-plans | 编写实施计划 | 把设计拆成细粒度任务清单 | 方案确定后、写代码之前 |
| executing-plans | 执行计划 | AI 亲自在本会话逐任务执行计划，台账记录进度与裁决 | 计划写好后（选内联省成本、或无子代理工具时） |
| subagent-driven-development | 子代理驱动开发 | 每个任务派独立子代理执行+审查 | 计划写好后的推荐方式（任务相对独立时） |
| test-driven-development | 测试驱动开发 (TDD) | 先写测试、看失败、再写最小代码通过 | 写任何功能或修 bug 时 |
| systematic-debugging | 系统化调试 | 先找根因再修复，禁止症状式修复 | 遇到 bug、测试失败、异常行为 |
| requesting-code-review | 请求代码审查 | 派审查者复核你的代码改动 | 完成任务、合并分支之前 |
| receiving-code-review | 接收审查反馈 | 理性评估审查意见，先验证再采纳 | 收到代码审查反馈时 |
| agent-browser | 浏览器自动化 | 驱动浏览器：打开网页、点击、填表、截图、抓数据 | 需要操作网页、测试 Web 应用、抓取数据 |
| figma-design-to-code | Figma 设计转代码 | 把 Figma 设计稿按规范流程翻译成代码 | 拿到设计稿要落地成代码、还原设计改版时 |

---

## 二、核心机制：自动触发，不是手动按钮

这些技能**不需要你手动调用**。它们的工作方式是：

1. 你用一句自然语言提出请求（如"帮我做个记账小程序"）
2. AI 根据请求内容自动匹配到某个技能的描述（description）
3. 该技能被自动加载，AI 遵循它内部定义的工作流程来响应你

所以你要做的不是"记住怎么调用"，而是**用正确的话术让 AI 自动进入对应流程**。当 AI 的行为不理想时（例如一言不合就写代码、遇到 bug 乱改），你可以主动点名指定流程。

---

## 三、技能详解

> 每个技能一个小节，**结构必须与下列模板一致**。新增技能时按《七、如何维护本文档》的模板填写。

### 1. brainstorming — 设计构思

**用途**：把模糊的想法通过一问一答逐步变成明确的设计方案。AI 会先了解项目背景，然后**一次问一个问题**，弄清目的、约束、成功标准，再提出 2~3 种方案让你选择，最终呈现完整设计。

**核心规则（HARD-GATE）**：**未经你批准设计，绝不写代码。** 哪怕是一个"简单"的需求也必须先过设计。

**什么时候用**：
- 提出新需求、新功能时（自动触发）
- 需求还不清楚、想先讨论方案时
- 想让 AI 别急着动手写码时

**触发话术**："我想做一个 XX""这个功能应该怎么做？""先别写代码，我们先讨论方案"

**产出**：设计文档（通常保存到 `docs/superpowers/specs/`）

---

### 2. writing-plans — 编写实施计划

**用途**：把已确认的设计拆解成"一口一个"的小任务（bite-sized tasks），每个任务精确标明：改哪些文件、函数签名是什么、测试名与断言、怎么验证。计划只写执行者**决定不了**的决策，不预先抄实现代码（代码块只留给签名和测试覆盖不了的算法）——计划明显比设计文档还长，说明写歪了。

**什么时候用**：
- 方案确认之后、写代码之前
- 多步骤、跨多文件的大任务
- 想让 AI 分步执行而不是一次性写一大堆时

**触发话术**："先给我一个实施计划，我确认了再做""按这个设计写一份开发计划"

**产出**：实施计划文档（通常保存到 `docs/superpowers/plans/`）

---

### 3. executing-plans — 执行计划

**用途**：AI 在**当前会话亲自**按计划逐任务执行（不派子代理）：每个任务读取任务简报，按 TDD 顺序工作、核对每步预期输出，用共享台账（ledger）记录进度与裁决，全部完成后做一次全分支终审。成本更低（一份上下文 + 一次终审），且与 subagent-driven-development 共用同一套台账，执行中途可以互相接力。

**核心规则（Rulings, not stalls）**：计划有冲突、歧义、缺陷时**自行裁决并记入台账**继续推进，不反复停下来问人。只有四种情况才停：不可逆/破坏性操作、安全敏感操作、需先征询的共享副作用（合并、推送、发布）、计划烂到每条路都是猜。

**什么时候用**：计划写好后，且你在交接时**选择了内联执行**（省成本），或当前环境没有子代理工具。

**触发话术**："按这个计划开始执行吧""直接在本会话内联执行这个计划"

---

### 4. subagent-driven-development — 子代理驱动开发

**用途**：执行计划的"每任务独立审查"方式。每个任务派发一个**全新子代理**（隔离上下文，不继承你的会话历史），每完成一个任务立即做一次"规格符合性 + 代码质量"审查，最后做全分支整体审查。与 executing-plans 共用同一套台账（ledger），执行中途可以互相接力。

**优势**：任务之间不互相污染上下文、每步有质检、无需你中途介入，迭代更快。

**什么时候用**：计划写好后、任务相对独立、希望每个任务都有独立审查把关时（writing-plans 交接时的推荐方式）。

**触发话术**："用子代理模式执行这个计划，每个任务做完就审查"

**二选一原则**：两者都在当前会话执行、共享台账。要每任务独立审查（更稳、成本高）→ subagent-driven-development；选内联省成本或没有子代理工具 → executing-plans。

---

### 5. test-driven-development — 测试驱动开发 (TDD)

**用途**：严格执行"红-绿-重构"循环：
1. **红**：先写一个会失败的测试
2. **绿**：写最少量的代码让它通过
3. **重构**：在测试保护下优化代码

**核心规则（铁律）**：**没有先失败的测试，就不许写生产代码。** 先写了代码再补测试？删掉重来。

**什么时候用**：写任何新功能、修任何 bug、做重构时（自动触发）。

**触发话术**："用 TDD 的方式做，先写测试""按测试驱动来"

**注意**：原型、一次性脚本、纯配置文件可以例外（与 AI 确认即可）。

---

### 6. systematic-debugging — 系统化调试

**用途**：遇到任何 bug 时强制走四阶段流程：
1. **根因调查**：认真读错误信息、稳定复现、隔离变量
2. **形成假设**：找到真正根因
3. **修复**：针对根因动手
4. **验证**：确认修复有效、无副作用

**核心规则（铁律）**：**没找到根因不许修。** 越紧急越要按流程走，乱改碰运气被认为是最差做法。

**什么时候用**：任何 bug、测试失败、构建失败、性能问题、诡异行为。

**触发话术**："这个报错帮我查一下，先定位根因再修""别急着改，先复现分析"

---

### 7. requesting-code-review — 请求代码审查

**用途**：派一个专门的审查子代理复核你的改动。它只接收**精心构造的上下文**（git commit 范围 + 需求说明），而不是整个会话历史，保证审查客观。反馈按级别处理：Critical（立即修）→ Important（继续前修）→ Minor（记下稍后处理）。

**什么时候用**：
- 每个任务完成之后
- 大功能开发完毕
- 合并到主分支之前
- 卡住了想换个视角看问题

**触发话术**："合并前审查一下我的改动""帮我 review 一下这段代码"

---

### 8. receiving-code-review — 接收审查反馈

**用途**：规定了收到审查意见时的正确反应方式——**技术诚实，不是表演性附和**：
- 先复述确认技术需求，再验证是否属实
- 觉得意见不对，可以用技术理由合理反驳
- 反馈不清晰时，先暂停全部改动，问清楚再动手

**禁止**："您说得太对了！""好主意！"这类敷衍附和。

**什么时候用**：收到任何代码审查反馈、尤其是意见看起来不对或不清楚时。

---

### 9. agent-browser — 浏览器自动化

**用途**：一个独立的浏览器自动化工具（通过 CDP 驱动 Chrome/Chromium）。能打开网页、填表、点击、截图、抓数据、测试 Web 应用，还能操作 Electron 桌面应用（VS Code、Slack 等）和 Slack 自动化。

**什么时候用**：
- 打开某个网页并操作（填表单、点按钮、登录）
- 抓取网页数据
- 测试你自己开发的 Web 应用
- 自动化重复性网页操作

**触发话术**："打开这个网址，帮我填表/截图/抓取数据""测试一下我这个页面"

**前置条件（首次使用前安装）**：`npm i -g agent-browser && agent-browser install`

---


### 10. figma-design-to-code — Figma 设计转代码

**用途**：把 Figma 设计稿按结构化流程翻译成生产级代码（读方向）：提取设计变量（颜色、间距、圆角、字体）→ 生成组件骨架 → 像素级还原校验。写方向（把代码/页面推回 Figma）用 figma-generate-design，本技能不写 Figma。

**核心规则**：调用 get_design_context 工具前必须先加载本技能；未配置 Figma MCP Server 时本技能取不到设计数据。

**什么时候用**：
- 拿到 Figma 设计稿需要落地成代码时（自动触发）
- 设计稿改版后做差异还原时
- 需要从设计稿提取 token/变量体系时

**触发话术**："实现这个 Figma 设计" "把这个 Figma 设计稿转成代码" "按设计稿生成这个页面"

**前置条件**：配置 Figma MCP Server（远程地址 mcp.figma.com/mcp，或本地 figma-developer-mcp 包）+ Figma 账号对目标设计稿的查看权限

**产出**：目标代码库中的页面/组件代码与 design token
## 四、一次完整开发的技能接力

以"做个记账小程序"为例，你只说了一句话，AI 会自动走这条流水线：

```
你说：帮我做个记账小程序，能记收入和支出
  │
  ▼
① brainstorming         AI 先问你：网页端还是小程序？数据存哪？要几个功能？
  │                     你回答问题 → AI 给方案 → 你批准（它才开始写码）
  ▼
② writing-plans         自动把方案拆成任务清单（建项目→数据层→增删改查→统计页→测试）
  │
  ▼
③ subagent-driven       每个任务：先写测试再写实现（TDD 贯穿）→ 每步自查 → 全量审查
   / executing-plans     （执行期间遇到 bug → systematic-debugging 介入）
  │
  ▼
④ requesting-code-review  全部完成、合并前，自动派审查者复核
  │
  ▼
⑤ 交付，你验收
```

你全程只需做三件事：**回答设计问题、批准方案、关键节点点名流程**。

---

## 五、高效使用五原则

1. **小步走**：一次只让 AI 做"一个功能 + 对应测试"，大需求先说"写计划"。
2. **你管"为什么"，它管"怎么做"**：需求里写清目的，实现细节让 AI 提案、你来拍板。
3. **审查是免费质检**：交付前说句"审查一下"，等于多一个人帮你查 bug。
4. **报 bug 给事实**：报错信息、复现步骤、期望 vs 实际，一次给全，调试更快命中根因。
5. **不满意给方向**：说"这个方案太复杂，要更简单的"比"不对"有效得多。

---

## 六、常见问题

**Q: 技能没反应怎么办？**
A: 技能通常在**新会话**中才会被加载扫描。安装/更新技能后，新开一个会话再试。

**Q: 有些技能提示找不到配套技能（如 using-git-worktrees）？**
A: 这套体系还有几个配套技能未安装。可以容忍 AI 跳过该环节，或补装完整套件。

**Q: 所有技能都必须走吗？**
A: 不必。小改动、临时脚本可以不走完整流程；重要功能、代码库改动建议走。

**Q: 文档与技能包不一致怎么办？**
A: 按《七、如何维护本文档》的流程更新文档——先核对《一、技能速览》，再同步详解与数量标注。

---

## 七、如何维护本文档

> 本章是给 **AI 维护者** 的操作手册。**新增技能、移除技能、修订描述**时，都必须按以下流程执行，保证文档长期保持一致、可移植。
> 使用者的查阅入口是《一、技能速览》——维护时的**第一优先级**是保证该表永远准确。

### 7.1 新增一个技能（核心场景）

**输入**：新增技能的目录（内含 `SKILL.md` 及可能的 `references/`、`scripts/` 等）。

**操作步骤**（按顺序执行）：

1. **通读 `SKILL.md`**：提取该技能的用途、核心规则、使用时机、触发方式、前置条件。有 `references/` 时，只读与"使用时机/前置条件"相关的部分即可，不必通读全部。
2. **判断技能类型**：
   - **流程类**（如 brainstorming、TDD）→ 写入详解小节，并考虑是否更新《四、技能接力》流程图
   - **工具类**（如 agent-browser）→ 写入详解小节，重点写"前置条件"，不强行塞进流程图
3. **按模板撰写详解小节**（模板见 7.2），追加到《三、技能详解》末尾，序号顺延。
4. **更新《一、技能速览》表**：追加一行（四列字段风格与现有行一致），并把表上方"当前共 N 个"数量改为最新值。
5. **运行自检清单**（见 7.4），全部通过才算完成。

### 7.2 单技能详解模板（必须照抄此结构）

```markdown
### <序号>. <skill 英文名> — <中文名>

**用途**：<2~3 句，说明该技能解决什么问题、怎么工作>

**核心规则（如有）**：<铁律 / HARD-GATE / 禁止事项；没有则删除此行>

**什么时候用**：
- <场景 1>
- <场景 2>

**触发话术**："<示例话术 1>""<示例话术 2>"

**前置条件（如有）**：<安装命令、API Key、环境要求等；没有则删除此行>

**产出（如有）**：<该技能会生成什么文件/结果；没有则删除此行>
```

### 7.3 填写规范与禁止事项

**必须遵守：**
- 标题格式固定：`### <序号>. <英文名> — <中文名>`，序号连续递增
- 字段顺序固定：用途 → 核心规则 → 什么时候用 → 触发话术 → 前置条件 → 产出
- 每个技能详解小节之间用 `---` 分隔
- 触发话术用中文双引号 `"..."` 包裹，多条话术之间用空格分隔
- 与技能包内容保持一致：描述以 `SKILL.md` 为准，不臆造能力

**严格禁止（可移植性红线）：**
- ❌ 禁止出现本机绝对路径（如 `C:\Users\...`、`/Users/...`、`/home/...`）——一律用相对路径或通用占位
- ❌ 禁止出现用户名、电脑名、个人环境变量值（如真实 API Key）
- ❌ 禁止出现会话性/时间性描述（"刚才""上一轮""昨天装的"等）
- ❌ 禁止粘贴大段 `SKILL.md` 原文——只提炼要点
- ❌ 禁止使用 AI 味修辞（"赋能""助力""一站式"等夸张词），用平实技术语言

### 7.4 自检清单（修改完成后逐项打勾）

- [ ] 全文搜索无本机路径（`C:\`、`/Users/`、`/home/`）、无用户名
- [ ] 《一、技能速览》表行数 = 技能数量，且"当前共 N 个"标注与实际一致
- [ ] 《三、技能详解》小节数 = 技能数量，序号连续
- [ ] 每个详解小节字段顺序与 7.2 模板一致
- [ ] 新增流程类技能时，已评估是否需要更新《四、技能接力》图
- [ ] 无 AI 味修辞，语言平实

### 7.5 移除 / 修订技能

- **移除**：从《一、技能速览》删除对应行 → 删除《三、技能详解》对应小节 → 重排后续序号 → 更新数量标注 → 跑自检清单。
- **修订**：只改对应小节与速览表对应行，保持结构与序号不变；修订后跑自检清单中与内容相关的条目。

---

*技能包来源：开源项目 [obra/superpowers](https://github.com/obra/superpowers)（软件工程工作流技能包），本文档为配套的通用使用指南。*