|
[88API Token聚合平台](https://88api.ai/sign-up?aff=MvTX) 🧠 聚合 GPT、Claude、Gemini、Grok、DeepSeek、Kimi、GLM 等语言与编程模型； 🎨 图片模型：GPT-Image、Gemini、Grok 等； 🎬 视频模型：Seedance、Veo、MiniMax H3、Kling、Grok 等； 🎙️ 语音能力：Whisper、TTS 等。从文案、出图、改图，到视频生成与配音 🎁新用户注册送体验额度，可以检测模型能力。站内有人工客服值守！ 👉香港正规企业运营 稳定供应 全绿满血 不降智 提供发票 |
|
感谢 [Cubence](https://cubence.com/signup?code=SCW29JP9) 对本项目的支持。Cubence 是一家致力为客户提供稳定、高效的 API 中转服务商。从 25 年 9 月运营至今，提供了 Claude Code、Codex、Gemini 等多种模型支持。🎁 **Cubence 为本开源项目的用户提供了特别的专属优惠码 `AGENCY`，通过[此链接](https://cubence.com/signup?code=SCW29JP9)注册的用户，首次购买即可享受 9 折优惠！** |
|
感谢 [Sidrune AI](https://sidrune.ai/register?source=github&campaign=superpowers&promo=superpowers&aff=RQHWKAMQLX2S) 赞助本项目！一个入口，接入并管理全球主流 AI 模型。Sidrune AI 面向个人开发者、技术团队与企业，通过统一 API 接入并管理全球主流 AI 模型；通过多线路动态调度提升可用性，模型表现、响应时间与费用透明可查。根据不同模型与线路，API 调用成本较官方或基准价格可降低 **40%—98%**。🎁 **通过[此链接](https://sidrune.ai/register?source=github&campaign=superpowers&promo=superpowers&aff=RQHWKAMQLX2S)注册即可获得 $3 API 额度！** |
|
感谢 [字节火山引擎](https://www.volcengine.com/activity/ai618?utm_source=OWO&utm_medium=devrel-1&utm_campaign=hw&utm_term=superpowers-zh&utm_content=hw) 赞助本项目！火山方舟 Agent/Coding Plan 国模套餐首购 **9.9**，支持 GLM-5.3、Kimi-K3、DeepSeek、MiniMax、Doubao 等，**注册免费领 2500w Token**，统一 API，适配编码与智能体开发。👉 **[立即前往](https://www.volcengine.com/activity/ai618?utm_source=OWO&utm_medium=devrel-1&utm_campaign=hw&utm_term=superpowers-zh&utm_content=hw)** |
|
感谢 [Infistar.cc 无限星河](https://www.infistar.cc/register?aff=PDVTM2VS&ref_source=link) 赞助并为 superpowers-zh 用户提供模型服务支持！无限星河提供高可用模型通道与多节点冗余，一个 API Key 接入 Claude、ChatGPT、Gemini、Kimi、GLM、DeepSeek 等模型，价格低至官方渠道 **1 折**，并适配 Claude Code、Codex、Cursor、Windsurf、Kiro 等 AI 编程工具。🎁 **通过[此链接](https://www.infistar.cc/register?aff=PDVTM2VS&ref_source=link)注册并完成首次调用，即可领取 5 美元等值测试额度！** |
| **没装 superpowers-zh：** ``` 你：给用户模块加个批量导出功能 AI：好的，我来实现...（直接开始写代码） export async function exportUsers() { ... } 你：等等，格式不对，没分页，大数据量会 OOM... ``` | **装了 superpowers-zh：** ``` 你：给用户模块加个批量导出功能 AI：在开始实现之前，我需要了解几个关键问题： 1. 导出格式是 CSV 还是 Excel？ 2. 预计数据量多大？需要异步处理吗？ 3. 有权限要求吗？ → 给出 2-3 个方案，确认后再动手 ``` |
 微信扫码关注 |
微信公众号 **「AI不止语」**（微信搜索 `AI_BuZhiYu`）— 技术问答 · 项目更新 · 实战文章 | 渠道 | 加入方式 | |------|---------| | QQ 2群 | [点击加入](https://qm.qq.com/q/EeNQA9xCxy)（群号 1071280067） | | 微信群 | 关注公众号后回复「群」获取入群方式 | |
]` |
| evidence | 被引用事件的正文保留，包括支撑发现所需的命令和结果 |
| full | 全部保留 |
- `scrub-log.md` —— 用到的每个占位符及其类别（绝不包含原始值）。
## 怎么读
从 `report.md` §1–2 开始，然后是 §7（涉及程度）及其引用的证据行，再看 `transcripts/`
中对应的轮次。`path:line` 引用指向提交者机器上的原始文件；同样的行号以 `[L]` 标记
的形式保留在精简后的会话记录中。
## 脱敏
占位符形如 ``、``、``、``、
``、``、``；家目录路径改写为 `~/…`。在本打包材料内，
同一个占位符始终指代同一个原始值。
## 制作者须知
完成后的打包材料用实际结果替换这些须知。
脱敏之后，只用本打包材料核对每一条实质性的导出发现：把它的引用解析到一个已包含的会话
记录/来源标记，读取被引用的命令/结果或引文，并核实它确实支撑该声明。仅仅路径和行号
存在是不够的。当脱敏级别或必要的保留删去了支撑时，记录具体的局限。
对报告、案例、环境、发现、README 以及任何本地 issue 草稿做对账。针对最终文件（不含日志
本身）刷新 scrub-log 中的计数。删除过时的导出说明；区分打包准备与归档交付。保留一份从
历史锚点到已包含证据的映射。
把独立的隐私审计与证据有用性分开记录：
- 隐私审计：CLEAN，或未解决的遗漏。
- 证据支撑：supported（有支撑）或 limited（有局限），并列出受影响的发现及原因。
检查之后如果内容有变，重做受影响的检查。展示最终日志、文件清单和两项结论，供既有的归档
批准使用。归档经审阅的文件，并核实交付的归档与之一致。把归档交付记录在经审阅的打包材料
之外，而不是在批准后修改其内容。脱敏不是详尽的隐私认证。
---
### README.Aider (`docs/README.aider.md`)
# Superpowers 中文版 — Aider 安装指南
在 [Aider](https://aider.chat) 中使用 superpowers-zh 的完整指南。
## ⚠️ 先看这一条：装完还需要一步才生效
**Aider 不会自动加载 `CONVENTIONS.md`。** [官方文档](https://aider.chat/docs/usage/conventions.html)明确要求显式加载 —— 原文推荐 `aider --read CONVENTIONS.md`，或在配置里写 `read:` 项。
所以装完之后，二选一：
```bash
# 每次启动时带上
aider --read CONVENTIONS.md
```
```yaml
# 或写进 .aider.conf.yml，一劳永逸
read: CONVENTIONS.md
```
**我们不替你改 `.aider.conf.yml`** —— 那是你的配置文件。安装器会在装完时把上面两条打印出来提醒你。
> 📌 v1.7.9 及更早版本的文档写着「Aider 会自动读取 CONVENTIONS.md，无需额外配置」—— **那是错的**，会让你以为装好了其实没生效。这是我们的错误，v1.7.10 起更正。
## 安装
```bash
cd /your/project
npx superpowers-zh --tool aider
```
会做两件事：
1. 把 21 个 skill 复制到 `.aider/skills/`
2. 生成（或追加）`CONVENTIONS.md`，里面是 skill 索引和触发规则，指向 `.aider/skills//SKILL.md`
### 关于自动检测
不带 `--tool` 时安装器会扫描项目里的工具标记。**Aider 不创建 `.aider/` 目录** —— 它在项目根留下的是 `.aider.` 前缀的产物，所以我们认这几个：
- `.aider.conf.yml`
- `.aider.chat.history.md`
- `.aider.tags.cache.v3/`
> 📌 v1.7.9 及更早只认 `.aider/` 这个目录，而 Aider 从不创建它 —— 也就是说**真实的 Aider 项目从来没被自动检测到过**，必须手动 `--tool aider`。同样在 v1.7.10 修正。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
cp -r superpowers-zh/skills /your/project/.aider/skills
```
> 手动复制不会生成 `CONVENTIONS.md`，你需要自己写一份索引并按上面的方式加载它。建议优先用 `npx superpowers-zh --tool aider`。
## 只加载部分 skill
`CONVENTIONS.md` 是一份索引（约 4 KB），由 Aider 常驻上下文，正文按需读取。如果你只想常驻少数几个 skill 的全文，也可以直接点名：
```yaml
read:
- .aider/skills/brainstorming/SKILL.md
- .aider/skills/test-driven-development/SKILL.md
- .aider/skills/systematic-debugging/SKILL.md
```
注意每个 SKILL.md 都会完整进入上下文，装 21 个的全文开销很大 —— 这正是我们默认走索引式 `CONVENTIONS.md` 的原因。
## 故障排查
### Skills 未生效
按顺序查：
1. **`CONVENTIONS.md` 被加载了吗？** 这是最常见的原因。Aider 启动后用 `/read` 看已加载的只读文件里有没有它。没有的话，回到本文开头那一步。
2. `.aider/skills/` 目录是否存在且包含 skill 子目录。
3. 如果用 `.aider.conf.yml` 的 `read:` 配置：确认 Aider 读的是你以为的那份配置。Aider 会依次找 home 目录、git 仓库根、当前目录下的 `.aider.conf.yml`。
### 装完没看到激活提示
说明你用的是旧版本。升级：
```bash
npx superpowers-zh@latest --tool aider
```
## 卸载
```bash
npx superpowers-zh --uninstall
```
会删除 `.aider/skills/` 下装过的 skill，并从 `CONVENTIONS.md` 中精确切除 superpowers-zh 段（保留你自己写的内容）。`.aider.conf.yml` 我们没动过，所以也不会去改 —— 如果你加过 `read: CONVENTIONS.md`，需要自己删。
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- 项目主页：https://github.com/jnMetaCode/superpowers-zh
- Aider 文档：https://aider.chat/docs/
- Aider conventions 文档：https://aider.chat/docs/usage/conventions.html
---
### README.Antigravity (`docs/README.antigravity.md`)
# Superpowers 中文版 — Antigravity 安装指南
在 [Google Antigravity](https://antigravity.google)（Google AI IDE）中使用 superpowers-zh 的完整指南。
## 快速安装
```bash
cd /your/project
npx superpowers-zh
```
安装脚本会自动检测 `.agents/` 目录并将 skills 复制到该目录。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p /your/project/.agents/skills
cp -r superpowers-zh/skills/* /your/project/.agents/skills/
```
## 工作原理
Antigravity 支持多种规则文件格式：
| 文件 | 优先级 | 说明 |
|------|--------|------|
| `GEMINI.md` | 最高 | Antigravity 专属规则 |
| `AGENTS.md` | 中 | 通用规则（Antigravity、Cursor、Claude Code 共享） |
| `.agents/rules.md` | 中 | 项目级规则目录 |
| `CLAUDE.md` | 低 | 也会被自动读取 |
### 推荐配置方式
**方式一**：在项目根目录创建 `GEMINI.md`：
```markdown
# GEMINI.md
使用 .agents/ 目录下的 superpowers skills 来指导工作流程。
优先使用 brainstorming（头脑风暴）开始新任务。
Skills 列表参见 .agents/ 目录。
```
**方式二**：在 `AGENTS.md` 中引用（多工具共享）：
```markdown
# AGENTS.md
本项目使用 superpowers-zh skills 框架。
Skills 位于 .agents/（Antigravity）或 .claude/skills/（Claude Code）目录下。
```
### 工具映射
Antigravity 使用 Gemini 模型，工具名称与 Claude Code 不同：
| Claude Code | Antigravity (Gemini) |
|-------------|---------------------|
| `Read` | `read_file` |
| `Write` | `write_file` |
| `Edit` | `replace` |
| `Bash` | `run_shell_command` |
| `Skill` | `activate_skill` |
Skills 中的 Claude Code 工具名称会被 Antigravity 自动适配。
## 使用
Antigravity 支持 Agent Manager 并行执行多个 agent：
- 与 superpowers-zh 的「派遣并行 Agent」skill 理念一致
- 可以同时调度多个 skill 处理不同任务
## 全局规则
个人级别的全局规则放在：
```
~/.gemini/GEMINI.md
~/.gemini/AGENTS.md
```
## 更新
```bash
cd /your/project
npx superpowers-zh
```
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- Antigravity 文档：https://antigravity.google/docs/rules-workflows
---
### README.Claw (`docs/README.claw.md`)
# Superpowers 中文版 — Claw Code 安装指南
在 [Claw Code](https://github.com/ultraworkers/claw-code) 中使用 superpowers-zh 的完整指南。
> 📌 v1.7.10 及更早版本 **Claw Code 没有任何安装文档** —— 23 款支持工具里唯一一个。v1.7.11 补上。
## 安装
```bash
cd /your/project
npx superpowers-zh --tool claw
```
装两样东西：
| 位置 | 内容 |
|---|---|
| `.claw/skills//SKILL.md` | 21 个 skill 正文 |
| `CLAW.md` | bootstrap：核心规则 + skill 清单 |
> 📌 v1.7.10 及更早**只装 skills、不写 `CLAW.md`**。skills 能被发现，但没有引导就不会在恰当时机自动触发。v1.7.11 起补上。
## 工作原理
两处都有**源码级证据**，不是猜的：
**① Skills 目录**
claw 自己的源码（`rust/crates/plugins/src/lib.rs`）里写着：
> `claw` does not load plugin-managed skills and instead discovers skills from local roots such as `.claw/skills`, `.omc/skills`, `.agents/skills`, `~/.omc/skills`, and `~/.claude/skills/omc-learned`.
所以 `.claw/skills/` 是它的主要发现路径之一，无需配置。
**② 根指令文件**
`USAGE.md` 列出 claw 加载的根指令文件及优先级：
```
CLAUDE.md > CLAW.md > AGENTS.md
```
另外它也读 `.claw/CLAUDE.md`、`.claude/CLAUDE.md`、`.claw/instructions.md`。我们写 `CLAW.md`。
### ⚠️ 已有 CLAUDE.md 时要注意
因为优先级是 **CLAUDE.md > CLAW.md**，如果你的项目里已经有 `CLAUDE.md`（比如装过 Claude Code），它可能压过我们刚写的 `CLAW.md`，导致 skill 不自动触发。
安装器检测到这种情况会主动提示。解法是让 `CLAUDE.md` 也带上引导：
```bash
npx superpowers-zh --tool claude
```
两个文件都带引导就不会互相遮蔽。
### 装过 Antigravity 的项目不用重复装
注意上面源码里那句 —— claw 也扫 **`.agents/skills`**，而那正是我们给 Antigravity 装的目录。如果你已经跑过 `npx superpowers-zh --tool antigravity`，claw 其实已经能读到这些 skill 了，再装一次 `.claw/skills` 会让它加载两份。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p /your/project/.claw/skills
cp -r superpowers-zh/skills/* /your/project/.claw/skills/
```
> 手动复制不会生成 `CLAW.md`，skill 不会自动触发。建议优先用 `npx superpowers-zh --tool claw`。
也可以用 claw 自带的安装命令逐个装：
```bash
claw skills install /path/to/superpowers-zh/skills/brainstorming
```
装完用 `/skills list`（REPL 内）或 `claw skills --output-format json` 确认发现的 skill 名。
## 关于全局安装
`--global` 不支持。claw 的用户级 skill 根是 `~/.omc/skills` 和 `~/.claude/skills/omc-learned` —— 前者不是我们的目录约定，后者是 claw 自己学习产物的专用目录，都不适合通用 `--global` 覆盖。
想让所有项目共享，可以给 Claude Code 装全局（`npx superpowers-zh --global --tool claude`），claw 会读 `~/.claude/` 下的相关约定。
## 卸载
```bash
npx superpowers-zh --uninstall
```
删除 `.claw/skills/` 下装过的 skill，并从 `CLAW.md` 精确切除 superpowers-zh 段（保留你自己写的内容）。实测卸载后零残留。
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- Claw Code 仓库：https://github.com/ultraworkers/claw-code
---
### README.Cline (`docs/README.cline.md`)
# Superpowers 中文版 — Cline 安装指南
在 [Cline](https://cline.bot)（VS Code AI 编程扩展）中使用 superpowers-zh 的完整指南。
## 快速安装
```bash
cd /your/project
npx superpowers-zh --tool cline
```
自动检测：安装脚本发现项目里有 `.clinerules/` 目录时也会自动装 Cline。**如果你还没建过 rules，就用上面的 `--tool cline` 显式指定。**
装完会得到两样东西：
```
.cline/skills/ # 21 个 skill 本体，按需读取
.clinerules/
└── superpowers-zh.md # 一份小索引，常驻 system prompt
```
## 工作原理（和其他工具不一样，值得读一下）
Cline 没有「skills」概念，它加载的是 **Rules**：`.clinerules/` 目录下所有 `.md` / `.txt` 会被**合并进每一轮的 system prompt**。
这跟 skills 的懒加载完全不同 —— 所以**绝不能把 21 个 SKILL.md 直接放进 `.clinerules/`**，那会让每轮对话都背着几万字的常驻开销，Cline 官方也提示规则超过约 300 行后遵守度会下降。
superpowers-zh 的做法：
| 放哪 | 内容 | 何时进 prompt |
|------|------|--------------|
| `.clinerules/superpowers-zh.md` | 核心规则 + 21 个 skill 的名称/触发条件索引表 | 每轮常驻（很小） |
| `.cline/skills//SKILL.md` | skill 完整流程正文 | 仅当任务匹配、Cline 主动读取时 |
索引 rule 里明确告诉 Cline：匹配到触发条件就去读对应的 `SKILL.md`，**不要**把正文抄进 rules。
### 为什么不写 YAML frontmatter
Cline 目前只支持 `paths`（glob 数组）一个条件字段。不写 frontmatter 就是「始终生效」，正是我们要的效果，所以索引 rule 是纯 Markdown。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p /your/project/.cline/skills /your/project/.clinerules
cp -r superpowers-zh/skills/* /your/project/.cline/skills/
```
然后在 `.clinerules/superpowers-zh.md` 里手写一份索引（内容参考 `npx` 装出来的那份）。**推荐直接用 `npx`** —— 索引表是根据 skills 的 frontmatter 自动生成的，手写容易漏。
## 关于全局安装
`--global` 对 Cline **不支持**。Cline 的全局 rules 目录随操作系统变化：
- macOS / Linux：`~/Documents/Cline/Rules`
- Windows：`Documents\Cline\Rules`
- Linux / WSL 有时是 `~/Cline/Rules`
没有一条稳定路径能让通用 `--global` 可靠命中，写错等于「装了不生效」，所以宁可不做。请用项目级安装。想全局用的话，把 `npx` 生成的那份 `superpowers-zh.md` 手动拷进你系统上实际的 Cline 全局 rules 目录即可。
## 使用
装好后新开一个 Cline 会话（rules 在会话开始时加载）。然后正常提需求即可：
- 「给用户模块加个批量导出功能」→ 应当先触发 brainstorming 做需求澄清，而不是直接写代码
- 也可以手动点名：「用 test-driven-development skill 做这个」
## 更新 / 卸载
```bash
npx superpowers-zh --tool cline # 更新（覆盖式，幂等）
npx superpowers-zh --uninstall # 卸载，同时清掉 .clinerules/superpowers-zh.md
```
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- Cline Rules 文档：https://docs.cline.bot/customization/cline-rules
---
### README.Codearts (`docs/README.codearts.md`)
# 华为云码道 CodeArts 使用指南
[华为云码道 CodeArts（CodeArts Doer / Snap）](https://codearts.huaweicloud.com/)是华为云出品的 AI 编程助手，支持 CLI、客户端以及 IntelliJ IDEA / VS Code 插件形态。skills 存放在项目的 `.codeartsdoer/skills/` 目录下。
## 一键安装（推荐）
在你的项目根目录运行：
```bash
npx superpowers-zh
```
自动检测到 `.codeartsdoer/` 时会安装到 CodeArts。检测不到时显式指定：
```bash
npx superpowers-zh --tool codearts
```
安装内容：
- `.codeartsdoer/skills/` — 21 个 skill（每个含 `SKILL.md` 及其 `scripts/` 等附属文件）
## Skill 加载优先级
| 位置 | 说明 |
|------|------|
| `.codeartsdoer/skills/` | 项目级，仅当前项目 |
## ⚠️ 关于自动触发
本适配为 **skills-only**：把 skills 放到 `.codeartsdoer/skills/`，依赖 CodeArts 自身的 skill 发现机制加载。
- 如果 CodeArts 会自动扫描并按需触发 `.codeartsdoer/skills/` 下的 skill，则装完重启即可生效。
- 如果发现**不会自动触发**，可以在对话里**手动点名** skill（例如「用 brainstorming skill 做需求分析」），skill 内容依然可用。
> CodeArts 的 bootstrap / 指令文件约定（类似 `CLAUDE.md` 的自动引导文件）我们尚未验证。如果你是 CodeArts 用户、了解它读取哪个指令文件来自动加载规则，欢迎在 [issue #20](https://github.com/jnMetaCode/superpowers-zh/issues/20) 反馈，我们会补上自动触发的 bootstrap 生成。
## 卸载
```bash
npx superpowers-zh --uninstall
```
移除 `.codeartsdoer/skills/` 下由 superpowers-zh 安装的 skill 目录。
## 反馈
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- 项目主页：https://github.com/jnMetaCode/superpowers-zh
---
### README.Codebuddy (`docs/README.codebuddy.md`)
# CodeBuddy 使用指南
[CodeBuddy](https://www.codebuddy.cn)（腾讯云 AI 编程助手 / AI IDE）加载 superpowers-zh skills 的方式与 Claude Code 类似：项目根目录的 `CODEBUDDY.md` 作为 bootstrap 引导，skills 放在 `.codebuddy/skills/` 下。
## 一键安装（推荐）
在你的项目根目录运行：
```bash
npx superpowers-zh
```
自动检测到 `.codebuddy/` 或 `CODEBUDDY.md` 时会安装到 CodeBuddy。检测不到时显式指定：
```bash
npx superpowers-zh --tool codebuddy
```
安装内容：
- `.codebuddy/skills/` — 21 个 skill（每个含 `SKILL.md`）
- `CODEBUDDY.md` — bootstrap 引导（已存在则在哨兵注释间追加，不覆盖你的内容）
## 全局安装
```bash
npx superpowers-zh --global --tool codebuddy
```
装到 `~/.codebuddy/skills/`，bootstrap 写 `~/.codebuddy/CODEBUDDY.md`，所有项目共享。
> 📌 v1.7.10 及更早写着「用户级路径尚未验证」且没有 `--global`。现已核实：[官方目录结构文档](https://www.codebuddy.cn/docs/cli/codebuddy-dir)确认全局与项目级同构。v1.7.11 起支持。
## Skill 加载优先级
| 位置 | 范围 |
|------|------|
| `.codebuddy/skills/` | 项目级，仅当前项目 |
| `~/.codebuddy/skills/` | 用户级，所有项目共享 |
同名时**项目级 > 用户级 > 插件级**（官方文档口径）。
记忆文件同理：全局在 `~/.codebuddy/CODEBUDDY.md`，项目级放项目根 `CODEBUDDY.md`（官方称项目根与 `.codebuddy/CODEBUDDY.md` 两处等价，我们用项目根）。
## 使用
1. 安装完成后**重启 CodeBuddy**。
2. CodeBuddy 读取 `CODEBUDDY.md` 后，会在任务匹配某个 skill 的触发条件时，读取对应的 `.codebuddy/skills//SKILL.md` 并遵循其流程。
3. 当任务涉及需求分析、TDD、系统化调试、代码审查等场景时，对应 skill 会被引用。
## 卸载
```bash
npx superpowers-zh --uninstall
```
移除 `.codebuddy/skills/` 下的 skills，并按哨兵注释精确切除 `CODEBUDDY.md` 里的 superpowers-zh 段落（不误删你自己的内容）。
## 故障排查
- **skills 没生效**：确认已重启 CodeBuddy；确认 `CODEBUDDY.md` 里存在 `# Superpowers-ZH 中文增强版` 段落。
- **自动检测不到**：用 `npx superpowers-zh --tool codebuddy` 显式指定。
## 反馈
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- 项目主页：https://github.com/jnMetaCode/superpowers-zh
---
### README.Codex (`docs/README.codex.md`)
# Superpowers 中文版 — Codex CLI 安装指南
## ⚠️ v1.7.10 及更早的项目级安装装错了地方
官方文档（developers.openai.com/codex/skills，现 308 跳 learn.chatgpt.com/docs/build-skills）给出的扫描目录**完整清单**是：
```
$CWD/.agents/skills
$CWD/../.agents/skills
$REPO_ROOT/.agents/skills
$HOME/.agents/skills
/etc/codex/skills
```
**没有 `.codex/skills`。** 而 v1.7.10 及更早的 `npx superpowers-zh --tool codex` 正是装到 `.codex/skills` —— Codex 不扫那里，等于装了完全不生效。全局（`~/.agents/skills`）一直是对的，只有项目级错。
v1.7.11 起项目级改装 `.agents/skills`，重装时会自动清掉旧位置里我们装的那些（你自己放在 `.codex/skills` 下的东西不动）：
```bash
cd /your/project
npx superpowers-zh --tool codex
```
> 顺带说明：`.agents/skills` 与 Antigravity 共用，这是 Agent Skills 开放约定，不是冲突。装过其中一个，另一个也能读到。
在 Codex 中使用 superpowers-zh 的完整指南。
## 快速安装
告诉 Codex：
```
Fetch and follow instructions from https://raw.githubusercontent.com/jnMetaCode/superpowers-zh/refs/heads/main/.codex/INSTALL.md
```
## Codex 原生插件安装
Codex CLI 自带插件管理，可以直接把本仓库注册为 marketplace 安装，不需要 Node.js / npm（已在 codex-cli 0.147.0、0.154.0 上实测）：
```bash
codex plugin marketplace add https://github.com/jnMetaCode/superpowers-zh.git
codex plugin add superpowers-zh@superpowers-zh
codex plugin list # 应显示 superpowers-zh@superpowers-zh installed, enabled
```
安装后 21 个 skills 全部可被发现；插件清单声明了空 `hooks`，不会注册仅适用于 Claude Code 的 SessionStart hook。
**更新：**
```bash
codex plugin marketplace upgrade superpowers-zh
codex plugin add superpowers-zh@superpowers-zh
```
**卸载：**
```bash
codex plugin remove superpowers-zh@superpowers-zh
codex plugin marketplace remove superpowers-zh # 可选：连同 marketplace 一起移除
```
## 手动安装
### 前置条件
- OpenAI Codex CLI
- Git
### 步骤
1. 克隆仓库：
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git ~/.codex/superpowers-zh
```
2. 创建 skills 符号链接：
```bash
mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers-zh/skills ~/.agents/skills/superpowers
```
3. 重启 Codex。
4. **子代理 skills（可选）：** `dispatching-parallel-agents` 和 `subagent-driven-development` 需要 Codex 的多代理功能。在 Codex 配置中添加：
```toml
[features]
multi_agent = true
```
### Windows
使用 junction 代替符号链接（无需开发者模式）：
```powershell
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers-zh\skills"
```
## 工作原理
Codex 原生支持 skill 发现——启动时扫描 `~/.agents/skills/` 目录，解析 SKILL.md 的 frontmatter，按需加载 skills。通过一个符号链接即可注册所有 skills：
```
~/.agents/skills/superpowers/ → ~/.codex/superpowers-zh/skills/
```
`using-superpowers` skill 会自动被发现并强制执行 skill 使用纪律——无需额外配置。
## 使用
Skills 自动发现。Codex 在以下情况激活 skills：
- 你提到 skill 名称（如 "use brainstorming"）
- 任务匹配 skill 的描述
- `using-superpowers` skill 指示 Codex 使用某个 skill
## 更新
```bash
cd ~/.codex/superpowers-zh && git pull
```
Skills 通过符号链接即时更新。
## 卸载
```bash
rm ~/.agents/skills/superpowers
```
**Windows (PowerShell):**
```powershell
Remove-Item "$env:USERPROFILE\.agents\skills\superpowers"
```
可选：删除克隆的仓库 `rm -rf ~/.codex/superpowers-zh`
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- 项目主页：https://github.com/jnMetaCode/superpowers-zh
---
### README.Crush (`docs/README.crush.md`)
# Superpowers 中文版 — Crush 安装指南
在 [Crush](https://github.com/charmbracelet/crush)（Charm 出品的终端 AI 编程 agent）中使用 superpowers-zh 的完整指南。
## ⚠️ 先看这一条：你可能已经装好了
Crush 遵循 **Agent Skills 开放标准**，项目级会**自动发现**下面四个目录，无需任何配置：
```
.crush/skills .agents/skills .claude/skills .cursor/skills
```
也就是说 —— **如果你已经为 Claude Code、Cursor、Codex 或 Antigravity 装过 superpowers-zh，Crush 现在就已经能读到那些 skills 了。**
**这种情况下不要再装 `--tool crush`**，否则同一批 skills 会出现两份，Crush 会重复加载。先确认一下：
```bash
ls .claude/skills .cursor/skills .agents/skills .crush/skills 2>/dev/null
```
只要上面任一目录里已有 21 个 skill，你就不用做任何事。
## 快速安装
只有在上述目录都为空时才需要装：
```bash
cd /your/project
npx superpowers-zh --tool crush
```
自动检测：项目里存在 `.crush/`、`crush.json` 或 `.crush.json` 任一时会自动装 Crush。
## 全局安装
Crush 支持通用全局安装：
```bash
npx superpowers-zh --global --tool crush
```
装到 `~/.config/crush/skills/`（Windows：`%LOCALAPPDATA%\crush\skills\`），所有项目共享。
> Crush 的用户级发现路径还包括 `~/.config/agents/skills/`（与 Codex、Copilot CLI 等共用的跨运行时别名）。如果你已经用 `--global --tool codex` 装过，那批 skills 也会被 Crush 看到 —— 同样别重复装。
## 工作原理
Crush 是 skills-only 适配：不需要 bootstrap 或规则文件。每个 skill 是一个含 `SKILL.md` 的目录，`SKILL.md` 的 frontmatter 带 `name` 与 `description`，Crush 据此按需发现并激活。
如果你想把 skills 放在非标准位置，Crush 也支持在配置里显式声明：
```json
{
"options": { "skill-path": ["./other-skills"] }
}
```
或用环境变量 `CRUSH_SKILLS_DIR` 覆盖默认目录。**我们不动你的 `crush.json`** —— 四个自动发现目录已经够用。
## 更新 / 卸载
```bash
npx superpowers-zh --tool crush # 更新（覆盖式，幂等）
npx superpowers-zh --uninstall # 卸载项目级
npx superpowers-zh --global --uninstall # 卸载全局
```
卸载只删我们装进去的 skills，**不会碰你的 `crush.json`**。
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- Crush 仓库：https://github.com/charmbracelet/crush
- Crush skills 文档：https://charmbracelet-crush.mintlify.app/configuration/skills
---
### README.Deepseek Harness (`docs/README.deepseek-harness.md`)
# Superpowers 中文版 — DeepSeek Harness 安装指南
在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）中使用 superpowers-zh 的完整指南。
## 快速安装
```bash
cd /your/project
npx superpowers-zh # 自动检测 .dsh/ 并安装
```
全局安装（所有项目共享）：
```bash
npx superpowers-zh --global --tool dsh
```
## 装到哪、为什么
四条路径全部取自官方仓库文档，不是猜的：
| 内容 | 路径 | 出处 |
|---|---|---|
| skills（项目级） | `.dsh/skills/` | [`docs/subsystems/skills.md`](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/skills.md) 的 Local discovery priority 表，rank 100 |
| skills（全局） | `~/.dsh/skills/` | `dshHome` 默认值 —— shell-env 文档：`dshHome \| $DSH_HOME, then ~/.dsh` |
| 引导文件（项目级） | 项目根 `AGENTS.md` | `instructionFileCandidates` 默认 `['AGENTS.md', 'CLAUDE.md']` |
| 引导文件（全局） | `~/.dsh/AGENTS.md` | 文档：user-global 指令文件为 `$DSH_HOME/AGENTS.md` |
## 已经装过别的工具？可能已经生效了一半
dsh 的技能发现路径里 **rank 200 是 `.agents/skills`** —— 那正是 Antigravity 的项目级目录、也是 Codex CLI 的全局目录（`~/.agents/skills`）。如果你已经为这两款装过，dsh **已经能读到那批技能**，不必重复装（重复装会加载两份）。
同理，dsh 的指令文件候选里包含 `CLAUDE.md`：装过 Claude Code 的项目，引导那一半已经生效。**但 `.claude/skills` 不在 dsh 的技能根列表里**，技能本身仍需按上面的路径安装。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p .dsh/skills
cp -r superpowers-zh/skills/* .dsh/skills/
```
技能名必须是 kebab-case（官方约束：`^[a-z0-9]+(?:-[a-z0-9]+)*$`），本仓 21 个 skill 全部符合。
## 卸载
```bash
npx superpowers-zh --uninstall # 项目级
npx superpowers-zh --global --uninstall # 全局
```
只移除我们装的技能目录与 `AGENTS.md` 里哨兵注释包住的那一段，你自己写的内容不受影响。
## 相关 issue
- [#122](https://github.com/jnMetaCode/superpowers-zh/issues/122) 请求兼容 DeepSeek Harness
---
### README.Deerflow (`docs/README.deerflow.md`)
# Superpowers 中文版 — DeerFlow 安装指南
在 [DeerFlow](https://github.com/bytedance/deer-flow)（字节跳动开源 SuperAgent）中使用 superpowers-zh 的完整指南。
## 快速安装
在你的 **DeerFlow 仓库根目录**下运行：
```bash
cd /your/deer-flow
npx superpowers-zh --tool deerflow
```
skills 会装到 `skills/custom/`。
> 📌 v1.7.10 及更早版本的自动检测标记写的是 `deer_flow/` —— **DeerFlow 2.0 的顶层目录里根本没有它**（实际是 `backend/` `frontend/` `skills/` `docker/` 等）。也就是说真实的 DeerFlow 检出从来没被自动检测到过，必须手动 `--tool deerflow`。v1.7.11 起改认 `skills/public/`（skills 机制本身、随仓库版本控制），`deer_flow/` 保留作 1.x 兼容。
## 工作原理
[DeerFlow 官方文档](https://bytedance-deer-flow.mintlify.app/concepts/skills)明确了两个**固定**目录：
| 目录 | 用途 | 是否进 git |
|---|---|---|
| `skills/public/` | DeerFlow 自带的 skill，社区维护 | 是 |
| `skills/custom/` | 用户自建或安装的 skill | 否，默认被 gitignore |
加载方式是**自动扫描这两个目录**，找每个子目录里的 `SKILL.md`：
```python
for base_dir in ["skills/public", "skills/custom"]:
for skill_dir in os.listdir(base_dir):
...
```
**无需任何配置**，也没有可改路径的配置项 —— 这两个目录名是写死的。所以我们装到 `skills/custom/`，装完即被发现。
### 容器挂载
DeerFlow 的 skill 在沙箱容器里执行，两个目录会挂到容器内的 `/mnt/skills/`：
```
/mnt/skills/
├── public/
└── custom/
```
所以 skill 内部若要引用自己的附属脚本，路径要写容器内的形式，例如 `python /mnt/skills/custom/my-skill/scripts/process.py`。
> superpowers-zh 的 21 个 skill 以 Markdown 指令为主，`brainstorming` 带的 `scripts/` 是给宿主机 harness 用的可视化伴侣服务，在 DeerFlow 的容器沙箱里不适用 —— 这部分能力在 DeerFlow 上不可用，其余 skill 的方法论正常生效。
## 手动安装
```bash
cd /your/deer-flow
mkdir -p skills/custom
cp -r /path/to/superpowers-zh/skills/* skills/custom/
```
装到别处的 DeerFlow 检出时，用绝对路径即可：
```bash
cp -r /path/to/superpowers-zh/skills/* /path/to/deer-flow/skills/custom/
```
> 📌 v1.7.10 及更早的本文档给了一段 `export DEERFLOW_SKILLS_DIR=...` 的写法，容易被读成「DeerFlow 认这个环境变量」。**官方文档里没有这个环境变量**，目录是写死的。已删除。
## 使用
装好后在 DeerFlow 对话中直接描述任务，或点名 skill：
- 「使用头脑风暴来分析这个需求」
- 「用测试驱动开发来实现这个功能」
- 「按系统化调试流程排查这个 bug」
DeerFlow 按 skill frontmatter 里的 `description` 匹配并加载，所以 `description` 写得越具体，被正确选中的概率越高 —— 这也是官方文档强调的一点。
## 卸载
```bash
cd /your/deer-flow
npx superpowers-zh --uninstall
```
只删除我们装进 `skills/custom/` 的那些 skill 目录，`skills/public/` 和你自己的 custom skill 不动。
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- DeerFlow 仓库：https://github.com/bytedance/deer-flow
- DeerFlow Skills 文档：https://bytedance-deer-flow.mintlify.app/concepts/skills
---
### README.Gemini Cli (`docs/README.gemini-cli.md`)
# Superpowers 中文版 — Gemini CLI 安装指南
在 [Gemini CLI](https://github.com/google-gemini/gemini-cli) 中使用 superpowers-zh 的完整指南。
## 自动安装
```bash
cd /your/project
npx superpowers-zh
```
安装脚本会自动检测 `.gemini/` 目录并将 skills 复制到 `.gemini/skills/` 目录。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
cp -r superpowers-zh/skills /your/project/.gemini/skills
```
或作为 Gemini 扩展安装（全局）：
```bash
mkdir -p ~/.gemini/extensions/superpowers-zh/skills
cp -r superpowers-zh/skills/* ~/.gemini/extensions/superpowers-zh/skills/
cp superpowers-zh/gemini-extension.json ~/.gemini/extensions/superpowers-zh/
```
## 通过 GEMINI.md 引用
在项目根目录的 `GEMINI.md` 中引用 skills：
```markdown
# 工作方法论
请参考 .gemini/skills/ 目录中的 SKILL.md 文件。
遇到新功能开发时，先使用 brainstorming skill。
编写代码时，遵循 test-driven-development skill。
```
## Skill 加载优先级
| 位置 | 优先级 | 说明 |
|------|--------|------|
| `.gemini/skills/` | 最高 | 项目级，仅当前项目 |
| `~/.gemini/extensions/*/skills/` | 中 | 扩展级，所有项目共享 |
## 故障排查
### Skills 未生效
1. 确认 `.gemini/skills/` 目录存在且包含 skill 文件夹
2. 每个 skill 需要包含有效 YAML frontmatter 的 `SKILL.md` 文件
3. 重启 Gemini CLI
### 扩展模式未加载
1. 检查 `gemini-extension.json` 是否正确放在扩展目录中
2. 确认扩展目录结构：`~/.gemini/extensions/superpowers-zh/`
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- 项目主页：https://github.com/jnMetaCode/superpowers-zh
- Gemini CLI 文档：https://github.com/google-gemini/gemini-cli
---
### README.Hermes (`docs/README.hermes.md`)
# Superpowers 中文版 — Hermes Agent 安装指南
在 [Hermes Agent](https://github.com/NousResearch/hermes-agent) 中使用 superpowers-zh 的完整指南。
## ⚠️ 先看这一条：必须装到全局，否则不生效
[Hermes 官方文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)明确：Hermes **只自动加载 `~/.hermes/skills/`**（原文称其为 "the primary directory and source of truth"），**项目级目录不会被自动发现**。
所以推荐的装法是全局：
```bash
npx superpowers-zh --global --tool hermes
```
装到 `~/.hermes/skills/`，装完即生效，用 `skills_list` 就能看到 21 个 skill。
> 📌 v1.7.8 及更早版本只支持项目级安装（装到 `<项目>/.hermes/skills/`）—— 那个目录 Hermes 根本不读，等于装了不生效。这是我们的实现错误，v1.7.9 起修正。见 [#45](https://github.com/jnMetaCode/superpowers-zh/issues/45)。
## 如果你确实要项目级安装
项目级的好处是 skills 可以随仓库一起分发。但**必须显式登记**，否则 Hermes 看不见。
```bash
cd /your/project
npx superpowers-zh --tool hermes
```
安装器会打印出你需要粘贴的配置片段，形如：
```yaml
skills:
external_dirs:
- /your/project/.hermes/skills
```
把它加进 `~/.hermes/config.yaml`。路径支持 `~` 展开和 `${VAR}` 环境变量替换；**配置里不存在的路径会被静默跳过**，所以写错了不会报错，只会"没生效"。
**我们不替你改 `config.yaml`** —— 那是你的配置文件。
项目级安装还会生成 `AGENTS.md` 引导文件（含核心规则和 skills 列表），让 Hermes 在合适时机主动检查 skill。全局安装**不写**这个文件 —— Hermes 的用户级指令文件约定没有公开文档，我们不猜路径、也不往你的主目录里写东西。
## 同名冲突
如果同一个 skill 名在 `~/.hermes/skills/` 和某个 `external_dirs` 目录里都存在，**本地（`~/.hermes/skills/`）的版本优先**。
## 其他 config.yaml 用法
如果希望全局使用 superpowers-zh skills，可以在 `~/.hermes/config.yaml` 中配置：
```yaml
skills:
external_dirs:
- /path/to/superpowers-zh/skills
```
## 工具映射
Skills 中引用的 Claude Code 工具名称对应 Hermes Agent 的等价工具：
| Claude Code | Hermes Agent |
|-------------|-------------|
| `Read` | `read_file` |
| `Write` | `write_file` |
| `Edit` | `patch` |
| `Bash` | `terminal` |
| `Grep` / `Glob` | `search_files` |
| `Skill` | `skill_view` |
| `Task`（子智能体） | `delegate_task` |
| `WebSearch` | `web_search` |
| `WebFetch` | `web_extract` |
| `TodoWrite` | `todo` |
完整映射参见 `skills/using-superpowers/references/hermes-tools.md`。
## 使用技能
Hermes Agent 支持三级渐进式加载：
```
# 浏览所有可用技能
skills_list
# 加载某个技能的完整内容
skill_view("brainstorming")
# 查看技能的引用文件
skill_view("using-superpowers", "references/hermes-tools.md")
```
## 故障排查
### Skills 未发现
1. 确认 `.hermes/skills/` 目录存在且包含 skill 文件夹
2. 每个 skill 目录下需要有 `SKILL.md` 文件
3. 使用 `skills_list` 查看已发现的技能
### AGENTS.md 未加载
1. 确认文件在项目根目录（与 `.hermes/` 同级）
2. 文件名必须是 `AGENTS.md`（项目工作流指令的官方位置）
> ⚠️ **v1.7.12 及更早版本写的是 `HERMES.md`** —— 而 [Hermes 官方文档](https://hermes-agent.nousresearch.com/docs/guides/use-soul-with-hermes)里 `HERMES.md` 出现 **0 次**：「project workflow instructions … Those belong in `AGENTS.md`」。旧版本写的那个文件很可能从未被加载。升级后重装即可；旧的 `HERMES.md` 可以手动删除（`--uninstall` 也会清掉我们写进去的那一段）。
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- 项目主页：https://github.com/jnMetaCode/superpowers-zh
- Hermes Agent 文档：https://hermes-agent.nousresearch.com/docs/
---
### README.Kilocode (`docs/README.kilocode.md`)
# Superpowers 中文版 — Kilo Code 安装指南
在 [Kilo Code](https://kilo.ai)（VS Code AI 编程扩展 / CLI）中使用 superpowers-zh 的完整指南。
## 快速安装
```bash
cd /your/project
npx superpowers-zh --tool kilocode
```
自动检测：项目里存在 `.kilocode/`、`.kilo/` 或 `kilo.jsonc` 任一时会自动装 Kilo Code。
装完会得到：
```
.kilocode/skills/ # 21 个 skill 本体，按需读取
.kilocode/rules/
└── superpowers-zh.md # 一份小索引，自动生效
```
## 工作原理
Kilo Code 加载的是 **Rules**（规则会并入 system prompt），不是懒加载的 skills。所以和 Cline 同理：**不能把 21 个 SKILL.md 直接塞进 rules 目录**，否则每轮对话都背着巨大的常驻开销。
superpowers-zh 的做法：
| 放哪 | 内容 | 何时进 prompt |
|------|------|--------------|
| `.kilocode/rules/superpowers-zh.md` | 核心规则 + 21 个 skill 的索引表 | 常驻（很小） |
| `.kilocode/skills//SKILL.md` | skill 完整流程正文 | 仅当任务匹配、Kilo 主动读取时 |
## 为什么用 `.kilocode/rules/` 而不是新版的 `kilo.jsonc`
Kilo Code 从 Roo 衍生的 v5 迁到了基于 OpenCode 的 v7，配置方式变了：
| | 旧（v5 及兼容路径） | 新（v7 推荐） |
|---|---|---|
| 规则目录 | `.kilocode/rules/` | `.kilo/rules/` |
| 是否需要登记 | **不需要，自动生效** | **需要**，要把路径写进 `kilo.jsonc` 的 `instructions` 数组 |
我们选 `.kilocode/rules/`，原因是**不改你的 `kilo.jsonc`**：
1. 官方明确 `.kilocode/rules/` 向后兼容，无需任何配置即生效；
2. `kilo.jsonc` 是带注释的 JSONC，安装脚本要安全合并它很容易把你的配置改坏；
3. 那是你的配置文件，装个 skills 框架不该动它。
### 如果你想迁到 v7 的方式
手动加一行即可（把现有规则文件挪到 `.kilo/rules/` 并登记）：
```jsonc
{
"instructions": [".kilo/rules/superpowers-zh.md"]
}
```
改完 `kilo.jsonc` 后**新开一个会话**才会生效。
> ⚠️ 需要说明的是：`.kilocode/rules/` 的兼容性来自官方文档中「现有规则会继续工作」的表述。若你在 v7 上装完发现索引 rule 没被加载，按上面的方式迁到 `.kilo/rules/` + `kilo.jsonc`，并欢迎来 issue 里反馈，我们会据此调整默认路径。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p /your/project/.kilocode/skills /your/project/.kilocode/rules
cp -r superpowers-zh/skills/* /your/project/.kilocode/skills/
```
索引 rule 建议交给 `npx` 生成 —— 它是按 skills 的 frontmatter 自动拼的，手写容易漏。
## 关于全局安装
`--global` 对 Kilo Code **不支持**：它的全局规则同样要走 `kilo.jsonc` 登记，没有「复制到某个用户级目录就生效」的通用路径。请用项目级安装。
## 更新 / 卸载
```bash
npx superpowers-zh --tool kilocode # 更新（覆盖式，幂等）
npx superpowers-zh --uninstall # 卸载，同时清掉 .kilocode/rules/superpowers-zh.md
```
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- Kilo Code 自定义规则文档：https://kilo.ai/docs/customize/custom-rules
---
### README.Kimi (`docs/README.kimi.md`)
# Superpowers 中文版 · Kimi Code 指南
在 [Kimi Code](https://github.com/MoonshotAI/kimi-code) 上使用 superpowers-zh 的完整说明。
## 安装
superpowers-zh 通过 Kimi Code 的插件清单 `.kimi-plugin/plugin.json` 集成，**直接指向仓库现有的 `skills/` 目录**——不复制 skill、不建 symlink、不装 hook、无任何运行时依赖。
打开插件管理器：
```text
/plugins
```
如果 Kimi 插件市场已收录，进入 `Marketplace` > `Superpowers 中文版` 安装即可。
也可以直接从本仓库安装：
```text
/plugins install https://github.com/jnMetaCode/superpowers-zh
```
如需验证尚未发布的改动，显式指定分支：
```text
/plugins install https://github.com/jnMetaCode/superpowers-zh/tree/main
```
Kimi Code 在**新会话**才会应用插件变更。安装、更新、启用、禁用或重载插件后，用 `/new` 开一个新会话。
## 工作原理
Kimi 插件清单位于 `.kimi-plugin/plugin.json`，做三件事：
1. 把 Kimi Code 指向仓库现有的 `skills/` 目录；
2. 通过 `sessionStart.skill` 在会话开始时加载 `using-superpowers`（这是让 skill 在恰当时机自动触发的关键）；
3. 通过 `skillInstructions` 提供 Kimi 专属的工具映射。
## 工具映射
skill 内容描述的是「动作」而非写死某个运行时的工具名。在 Kimi Code 上它们对应到：
- 「向用户提问」/「问澄清问题」/「给出多选项」→ `AskUserQuestion`
- 「创建待办」/「在待办清单中标记完成」→ `TodoList`
- 「分派子智能体」/「Task tool (general-purpose)」→ `Agent`（用 Kimi 的 subagent 类型，如 `coder`/`explore`/`plan`，**不要**传 `general-purpose`）
- 「调用某个 skill」→ Kimi Code 原生 `Skill` 工具
- 「读文件」/「写文件」/「改文件」→ `Read` / `Write` / `Edit`
- 「跑 shell 命令」→ `Bash`
- 「搜索文件内容」→ `Grep`
- 「按路径/模式找文件」→ `Glob`
- 「抓取 URL」→ `FetchURL`
- 「联网搜索」→ `WebSearch`
完整映射写在清单的 `skillInstructions` 字段里，由 Kimi 在运行时读取。
## 更新
用 Kimi Code 的插件管理器：
```text
/plugins
```
选中 Superpowers 中文版更新，更新后用 `/new` 开新会话。
## 排错
### 插件没加载
1. 跑 `/plugins info superpowers-zh` 看诊断信息；
2. 确认插件已启用；
3. 安装或更新后用 `/new` 开新会话。
### 直接 GitHub 安装装到了旧版本
对于裸仓库 URL，Kimi Code 会装最新的 GitHub release（若存在）。要在下一个 release 前测试未发布的改动，显式指定分支：
```text
/plugins install https://github.com/jnMetaCode/superpowers-zh/tree/main
```
### skill 不触发
1. 用 `/plugins info superpowers-zh` 确认插件已启用；
2. 用 `/new` 开新会话；
3. 试验收提示词：`我们来做个 react todo list`。集成正常的话，会在写任何代码之前先加载 `brainstorming`。
---
### README.Kiro (`docs/README.kiro.md`)
# Superpowers 中文版 — Kiro 安装指南
在 [Kiro](https://kiro.dev)（Amazon AI IDE）中使用 superpowers-zh 的完整指南。
## ⚠️ v1.7.9 及更早版本请重新安装
旧版把 20 个 skill 的**正文**直接装进了 `.kiro/steering/`。而 [Kiro 官方文档](https://kiro.dev/docs/steering/)明确：`.kiro/steering/` 下的文件默认 `inclusion: always`，会被 "loaded into every Kiro interaction automatically"。
实测那个布局是 **47 个 md、335 KB，每一轮对话全量进上下文**。不是不能用，是每轮都在烧 token。
v1.7.10 起改成索引式：**4.4 KB**（76 倍差距）。重装即可，安装器会自动清掉旧布局：
```bash
cd /your/project
npx superpowers-zh@latest --tool kiro
```
会看到：
```
🧹 Kiro: 清理旧布局 20 个 skill 目录 <- .kiro/steering/
✅ Kiro: steering 索引 -> .kiro/steering/superpowers-zh.md
```
**你自己写的 steering 文件不会被动** —— 只清理与我们 skill 同名的那些目录。
## 快速安装
```bash
cd /your/project
npx superpowers-zh --tool kiro
```
装两样东西：
| 位置 | 内容 | 是否每轮常驻 |
|---|---|---|
| `.kiro/steering/superpowers-zh.md` | 索引：核心规则 + 21 个 skill 的触发条件表（约 4.4 KB） | **是**（`inclusion: always`） |
| `.kiro/skills//SKILL.md` | skill 正文 | 否，按需读取 |
## 工作原理
Kiro 用 **Steering** 机制管理 AI 行为规则。关键的三件事：
- **目录**：`.kiro/steering/`（项目级）、`~/.kiro/steering/`（全局）
- **默认行为**：**没写 `inclusion` 的文件默认就是 always** —— 每次交互自动加载
- **frontmatter 键**（这是 Kiro 自己的，别和 Cursor 系搞混）：
| 键 | 含义 |
|---|---|
| `inclusion: always` | 每次交互都加载（**默认值**） |
| `inclusion: fileMatch` + `fileMatchPattern` | 匹配特定文件时加载 |
| `inclusion: manual` | 仅在聊天里用 `#steering-file-name` 引用时加载 |
| `inclusion: auto` | 按 `description` 与请求匹配时自动加载 |
> 📌 v1.7.9 及更早的本文档写着加载模式是 `alwaysApply: true` 和 `globs: "*.ts"` —— **这两个键 Kiro 文档里根本不存在**，是 Cursor / Trae 的约定被误写成了 Kiro 的。已更正。
### 为什么正文不放 steering 里
因为 steering 是常驻开销。这跟我们对 Cline、Kilo Code 的处理是同一个道理：**常驻的位置只放索引，正文按需读取。**
索引里明确告诉 Kiro：任务匹配某个 skill 时，去读 `.kiro/skills//SKILL.md` 并遵循其流程。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p /your/project/.kiro/skills
cp -r superpowers-zh/skills/* /your/project/.kiro/skills/
```
> 手动复制不会生成 `.kiro/steering/superpowers-zh.md` 索引，Kiro 不会知道这些 skill 的存在，你需要自己写一份索引。建议优先用 `npx superpowers-zh --tool kiro`。
>
> **不要**把正文直接拷进 `.kiro/steering/` —— 那正是本次修掉的问题。
## 使用
装好重启 Kiro 后：
- 直接描述任务即可，索引会引导它去匹配 skill：「帮我加一个导出功能」应触发 brainstorming
- 也可以点名：「用 brainstorming 分析这个需求」
- 手动引用索引本身：在聊天里输入 `#superpowers-zh`
## 卸载
```bash
npx superpowers-zh --uninstall
```
会删除 `.kiro/skills/` 下装过的 skill 和 `.kiro/steering/superpowers-zh.md`，并顺带清理旧布局残留。你自己的 steering 文件保留。
## 更新
```bash
npx superpowers-zh@latest --tool kiro
```
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- Kiro Steering 文档：https://kiro.dev/docs/steering/
---
### README.Openclaw (`docs/README.openclaw.md`)
# Superpowers 中文版 — OpenClaw 安装指南
在 [OpenClaw](https://github.com/openclaw/openclaw) 中使用 superpowers-zh 的完整指南。
## 快速安装
```bash
cd /your/project
npx superpowers-zh
```
安装脚本会自动检测 `.openclaw/` 目录并将 skills 复制到 `skills/` 目录。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
cp -r superpowers-zh/skills/* /your/project/skills/
```
或安装到全局（所有项目共享）：
```bash
cp -r superpowers-zh/skills/* ~/.openclaw/skills/
```
## 工作原理
OpenClaw 按以下优先级加载 skills：
| 位置 | 优先级 | 说明 |
|------|--------|------|
| `/skills/` | 最高 | 工作区级，当前项目专用 |
| `~/.openclaw/skills/` | 中 | 用户级，所有项目共享 |
| 内置 skills | 最低 | OpenClaw 自带 |
每个 skill 是一个 `skills/{name}/SKILL.md` 文件，包含 YAML frontmatter 和指令内容。OpenClaw 会自动发现并加载。
### 推荐配置方式
在项目根目录的 `CLAUDE.md` 或 `AGENTS.md` 中引用：
```markdown
# CLAUDE.md
本项目使用 superpowers-zh skills 框架。
优先使用 brainstorming（头脑风暴）开始新任务。
Skills 位于 skills/ 目录下。
```
### 工具映射
OpenClaw 与 Claude Code 使用相同的工具名称，skills 无需额外适配：
| 工具 | OpenClaw | Claude Code |
|------|----------|-------------|
| 读文件 | `Read` | `Read` |
| 写文件 | `Write` | `Write` |
| 编辑 | `Edit` | `Edit` |
| 终端 | `Bash` | `Bash` |
| Skills | `Skill` | `Skill` |
## 使用
安装完成后重启 OpenClaw，所有 skills 会自动生效。AI 会按任务上下文自动调用对应 skill：
- 新任务 / 新功能 → `brainstorming`（头脑风暴）
- 写 commit message → `chinese-commit-conventions`（中文 commit 规范）
- 调试问题 → `systematic-debugging`
- 完成任务后 → `requesting-code-review`（请求代码审查）
无需手动 slash command 触发 —— AI 通过 skill frontmatter 的 `description` 字段自主选择匹配的 skill。如果想强制触发某个 skill，直接在指令里点名："用 brainstorming 帮我想一下 X 怎么做"。
## 全局 Skills
如果你想让所有项目都能使用 superpowers-zh：
```bash
mkdir -p ~/.openclaw/skills
cp -r superpowers-zh/skills/* ~/.openclaw/skills/
```
也可以通过 `~/.openclaw/openclaw.json` 配置额外 skills 目录：
```json
{
"skills": {
"load": {
"extraDirs": ["/path/to/superpowers-zh/skills"]
}
}
}
```
## 更新
```bash
cd /your/project
npx superpowers-zh
```
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- QQ 群：833585047
---
### README.Opencode (`docs/README.opencode.md`)
# Superpowers 中文版 — OpenCode 安装指南
在 [OpenCode.ai](https://opencode.ai) 中使用 superpowers-zh 的完整指南。
## 安装
OpenCode V2 需要 2.0.4 或更高版本。
### OpenCode V1
在 `opencode.json`（全局或项目级）的 `plugin` 数组中添加：
```json
{
"plugin": ["superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git"]
}
```
### OpenCode V2（2.0.4 或更高版本）
使用 V2 插件配置（注意键名是 `plugins`）：
```json
{
"plugins": ["superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git"]
}
```
如果是 V2 的本地安装，配置的应当是包含 `index.js` 的仓库目录。OpenCode 2.0.4 和 2.0.7 会拒绝直接配置成 JavaScript 文件路径。通过自动发现找到的插件符号链接仍然受支持。
重启 OpenCode。V2 使用 `opencode` 命令；`opencode2` 可能作为别名可用。插件会通过 OpenCode 的插件管理器安装，并注册所有 skills。
验证方式：问 "告诉我你有哪些 superpowers"
### 从旧版符号链接安装方式迁移（V1）
如果你之前使用 `git clone` 和符号链接安装过 superpowers，请移除旧的配置：
```bash
# 移除旧的符号链接
rm -f ~/.config/opencode/plugins/superpowers.js
rm -rf ~/.config/opencode/skills/superpowers
# 可选：移除克隆的仓库
rm -rf ~/.config/opencode/superpowers
# 如果你在 opencode.json 中为 superpowers 添加过 skills.paths，请将其移除
```
然后按照上面的安装步骤操作。
## 使用
### 查找 Skills
使用 OpenCode 原生的 `skill` 工具列出所有可用 skills：
```
use skill tool to list skills
```
### 加载 Skill
```
use skill tool to load brainstorming
```
### 个人 Skills
在 `~/.config/opencode/skills/` 中创建你自己的 skills：
```bash
mkdir -p ~/.config/opencode/skills/my-skill
```
创建 `~/.config/opencode/skills/my-skill/SKILL.md`：
```markdown
---
name: my-skill
description: 当 [条件] 时使用 - [功能描述]
---
# 我的 Skill
[你的 skill 内容]
```
### 项目 Skills
在项目的 `.opencode/skills/` 目录中创建项目级 skills。
**V2 的 Skill 优先级：** 项目 skills > 个人 skills > Superpowers skills。在实测的 V1 1.18.31 上，当个人或项目 skill 与自带的 Superpowers skill 同名时，Superpowers 的那个优先；个人和项目 skill 请使用不同的名字。这次迁移没有改变这一行为。
## 更新
OpenCode 通过一个基于 git 的包说明（package spec）安装 Superpowers。有些 OpenCode 和 Bun 版本会把解析出的 git 依赖锁定在 lockfile 或缓存里，所以重启不一定能拿到 Superpowers 的最新提交。如果更新没有生效，清掉 OpenCode 的包缓存，或重新安装插件。
要固定到特定版本，在包说明后面加上标签或提交（V1 的 `plugin` 键和 V2 的 `plugins` 键写法相同）：
```json
{
"plugin": ["superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git#v1.7.14"]
}
```
在 V2 上，要固定到包含 V2 插件的版本（v1.7.13 之后的版本）；v1.7.13 及更早的发布只能在 V1 上加载。
## 工作原理
插件做两件事，按 OpenCode 的版本使用各自的 API：
1. **注册 skills 目录**，让 OpenCode 无需符号链接或手动配置就能发现所有 superpowers skills。
- **V1：** 通过 `config` hook，注入到 `config.skills.paths`
- **V2：** 通过 `setup()` 函数，使用 `ctx.skill.transform()`（V2 原生 API，已确认运行时生效）
2. **注入引导上下文**，附带按版本区分的工具映射：V1 会话拿到下面的 V1 工具名，V2 会话拿到 V2 工具名。
- **V1：** 通过 `experimental.chat.messages.transform` hook
- **V2：** 通过 `ctx.session.hook("context")`——V2 中的对应机制（已确认运行时生效）
控制者会话会在临时的模型上下文里收到 using-superpowers 引导内容。被委派出去的子会话仍能使用原生 skills，但不会收到控制者的引导内容。没有父会话的手动 fork 保持控制者行为。当 V2 原生压缩保留了较早的用户消息时（默认的 `compaction.keep.tokens` 预算），引导内容会放进检查点之前保留下来的第一条用户消息里，和未压缩的会话一样。当压缩移除了所有用户消息时，插件会在检查点之后追加一条临时的引导消息。无论哪种情况，保存的历史都不会改变。
如果会话查询失败，插件会在这次请求里保留引导内容，并在下一次请求时重试。查询失败不会被缓存成控制者判定。
### 工具映射
Skill 用动作来表述，而不是点名某一个运行时的工具。引导内容会把这些动作映射到你所用的 OpenCode 版本实际提供的工具上。
**V1（`opencode` 1.x）：**
- 「创建一条待办」/「在待办列表里标记完成」→ `todowrite`
- `Subagent (general-purpose):` 模板 → OpenCode 的 `task` 工具，传 `subagent_type: "general"`（探索代码库时用 `"explore"`）
- 「调用一个 skill」→ OpenCode 的原生 `skill` 工具
- 「读取文件」→ `read`
- 「创建文件」/「编辑文件」/「删除文件」→ `apply_patch`
- 「运行 shell 命令」→ `bash`
- 「搜索文件内容」/「按文件名查找」→ `grep`、`glob`
- 「抓取 URL」→ `webfetch`
**V2（`opencode` 2.0.4 或更高版本；`opencode2` 可能作为别名可用）：**
- 「创建一条待办」→ V2 没有任何形式的待办工具；映射会让模型改为在一个 markdown 文件（或运行环境自带的计划功能）里跟踪计划
- `Subagent (general-purpose):` 模板 → OpenCode 的 `subagent` 工具，传 `agent: "general"`（或 `"explore"`）；传 `sessionID` 可以继续之前的子智能体
- 「调用一个 skill」→ OpenCode 的原生 `skill` 工具
- 「读取文件」→ `read`
- 「创建、编辑或删除文件」→ 有 `patch` 时用 `patch` 并传 `patchText`；否则用 `write` 创建或覆盖文件、`edit` 做定点修改、`shell` 删除文件
- 「运行 shell 命令」→ `shell`（`command`、`workdir`、`timeout`、`background`）
- 「搜索文件内容」/「按文件名查找」→ `grep`、`glob`
- 「抓取 URL」→ `webfetch`
- 「搜索网络」→ `websearch`
简单说，V2 把 `task` 改名为 `subagent`（智能体名称从 `subagent_type` 挪到了 `agent`，继续会话改为带 `sessionID` 重新调用），`apply_patch` 改名为 `patch`，`bash` 改名为 `shell`，并且完全去掉了待办工具。可用的写入类工具取决于所选模型：`patch` 只对选定的 GPT 模型 ID 可用，其他模型使用 `write` 和 `edit`。
（V1 清单已对照安装好的 OpenCode 1.18.x CLI 的工具清单核实；V2 清单已对照 OpenCode 2.0.4 和 2.0.7 的宿主契约核实。以上核实由上游 obra/superpowers 完成。）
## 故障排查
### 插件未加载
**V1：** 检查 OpenCode 日志：
```
opencode run --print-logs "hello" 2>&1 | grep -i superpowers
```
**V2：** 插件在后台服务进程里加载，它的日志只有加上 `--standalone` 时 `--print-logs` 才会显示：
```
opencode run --standalone --print-logs "hello" 2>&1 | grep -i superpowers
```
或者查看 `~/.local/share/opencode/log/opencode.log`，过滤 `role=server`。
同时确认 `opencode.json` 中的插件路径正确，并且运行的是较新版本的 OpenCode。
### Windows 安装问题
部分 Windows 版 OpenCode 对基于 git 的插件说明存在上游安装器问题，包括 `git+https` URL 的缓存路径问题，以及 Bun 找不到 `git.exe`（即使它在普通终端里能用）。如果 OpenCode 装不上插件，可以试试用系统的 npm 安装，再让 OpenCode 指向本地包：
```powershell
npm install superpowers@git+https://github.com/jnMetaCode/superpowers-zh.git --prefix "$HOME\.config\opencode"
```
然后按你的 OpenCode 版本，在 `opencode.json` 里使用已安装包的绝对路径。OpenCode 不展开 `~`；`~/...` 这样的条目会被当成包名，而不是本地目录。
**V1：**
```json
{
"plugin": ["C:\\Users\\\\.config\\opencode\\node_modules\\superpowers"]
}
```
**V2（2.0.4 或更高版本）：**
```json
{
"plugins": ["C:\\Users\\\\.config\\opencode\\node_modules\\superpowers"]
}
```
### Skills 未找到
1. 使用 OpenCode 的 `skill` 工具列出可用 skills
2. 检查插件是否正确加载（见上）
3. 每个 skill 需要包含有效 YAML frontmatter 的 `SKILL.md` 文件
### 引导内容没有出现
- **V1：** 检查 OpenCode 版本是否支持 `experimental.chat.messages.transform` hook。修改配置后重启 OpenCode。
- **V2：** 插件使用 `ctx.session.hook("context")` 注入引导内容。用 `opencode api get /api/plugin` 确认插件已加载。修改配置后用 `opencode service restart` 重启。`opencode2` 命令可能作为别名可用。
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- 项目主页：https://github.com/jnMetaCode/superpowers-zh
- OpenCode V2 文档：https://opencode.ai/v2/docs/
- OpenCode V1 文档：https://opencode.ai/docs/
---
### README.Pi (`docs/README.pi.md`)
# Superpowers 中文版 · Pi 指南
在 [Pi](https://github.com/earendil-works/pi)（oh-my-pi）上使用 superpowers-zh 的完整说明。
## 安装
superpowers-zh 通过 Pi 的扩展机制集成，**直接指向仓库现有的 `skills/` 目录**——不复制 skill、不建 symlink、无额外运行时依赖。
集成由 `package.json` 里的 `pi` 字段声明：
```json
"pi": {
"skills": ["./skills"],
"extensions": ["./.pi/extensions/superpowers.ts"]
}
```
并带 `pi-package` keyword，便于 Pi 发现这是一个 Pi 包。
按 Pi 的包安装方式安装 `superpowers-zh`（参考 Pi 文档的包管理命令），Pi 会读取上述 `pi` 配置，挂载 `skills/` 并加载 `.pi/extensions/superpowers.ts` 扩展。
## 工作原理
`.pi/extensions/superpowers.ts` 注册了 Pi 的生命周期钩子：
1. **`resources_discover`** — 把仓库的 `skills/` 目录贡献给 Pi 的技能系统；
2. **`session_start` / `session_compact`** — 标记需要重新注入 bootstrap；
3. **`context`** — 在会话上下文中注入 `using-superpowers` 的内容（去除 frontmatter）+ Pi 工具映射，作为「You have superpowers」bootstrap，让 skill 在恰当时机被遵循；
4. **`agent_end`** — 一轮结束后停止重复注入。
注入带有唯一标记，已存在时不会重复注入；并且会插入到 compaction summary 之后，避免被压缩流程吞掉。
## 工具映射
Pi 有原生技能系统，但**不暴露** `Skill` 工具。skill 内容描述「动作」，在 Pi 上对应到小写工具：
- 「调用某个 skill」→ Pi 原生技能：用 `read` 加载对应 `SKILL.md`，或由人类显式 `/skill:name`
- 「读/写/改文件」→ `read` / `write` / `edit`
- 「跑 shell 命令」→ `bash`
- 「搜索文件内容」→ `grep`，「按名找文件」→ `find`，「列目录」→ `ls`
- 「分派子智能体」→ 若装了 `pi-subagents` 的 `subagent` 工具则用之；没有则在本会话内完成或说明能力缺失，**不要**臆造 `Task` 调用
- 「待办清单」→ 若装了 todo/task 工具则用之；否则用 plan 文件或仓库内 `TODO.md` 跟踪；旧的 `TodoWrite` 引用按此处理
完整映射见 [`skills/using-superpowers/references/pi-tools.md`](../skills/using-superpowers/references/pi-tools.md)，扩展也会把同样的映射注入会话。
## 验证
```bash
bash tests/pi/run-tests.sh
```
该测试动态加载扩展并校验：声明了 `pi` 包配置、注册了正确的生命周期钩子（且无 pre-compaction 注入）、`resources_discover` 贡献了 `skills/` 目录、`session_start` 注入了「You have superpowers」+「Pi tool mapping」、pi-tools 参考文档存在。
> 注：扩展是 TypeScript（仅 `import type`，运行时无类型依赖）。Node 22.6–23.5 需 `--experimental-strip-types`（run-tests.sh 已带），23.6+ 默认支持。
---
### README.Qoder (`docs/README.qoder.md`)
# Superpowers 中文版 — Qoder 安装指南
在 [Qoder](https://qoder.com)（阿里推出的 AI IDE）中使用 superpowers-zh 的完整指南。
## 自动安装
```bash
cd /your/project
npx superpowers-zh
```
安装脚本会自动检测 `.qoder/` 目录并：
1. 把 21 个 skills 复制到 `.qoder/skills//SKILL.md`
2. 生成一个**始终生效**的 bootstrap rule `.qoder/rules/superpowers-zh.md`（`trigger: always_on`），让 Qoder 每个会话都加载核心规则与 skill 索引
如果项目目录里还没有 `.qoder/`，可以显式指定：
```bash
npx superpowers-zh --tool qoder
```
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
cp -r superpowers-zh/skills /your/project/.qoder/skills
```
或全局安装（对所有项目生效）：
```bash
cp -r superpowers-zh/skills ~/.qoder/skills
```
## Skill 加载优先级
| 位置 | 优先级 | 说明 |
|------|--------|------|
| `.qoder/skills/` | 最高 | 项目级，仅当前项目 |
| `~/.qoder/skills/` | 中 | 用户级，所有项目共享 |
> 同名 skill 项目级覆盖用户级。
## 使用
1. 安装完成后**重启 Qoder**
2. 在对话框输入 `/` 即可看到已加载的 skills 列表
3. bootstrap rule（`.qoder/rules/superpowers-zh.md`）会被 Qoder 识别为"始终生效"，每个会话自动加载核心规则
4. Qoder 还会根据 skill 的 `description` 自动判断何时调用；也可输入 `/` 手动触发
> Qoder Rules schema（`trigger: always_on` / `model_decision` / `manual`）来自社区实际样本，官方文档（docs.qoder.com/zh/user-guide/rules）目前只公开 UI 配置流程未公开 frontmatter schema。如果 Qoder 后续改了 schema，rule 文件可能需要打开 Qoder Settings → Rules 重新选择类型。
## 工具映射说明
skills 中引用的 Claude Code 工具名称（`Read` / `Write` / `Edit` / `Bash` / `Grep` / `Glob` / `WebFetch` / `WebSearch` 等）在 Qoder 中**同名对应**，无需额外映射。
少数差异：
| Claude Code | Qoder 等价 |
|-------------|-----------|
| `EnterPlanMode` / `ExitPlanMode` | `EnterSpecMode` / `ExitSpecMode` |
| `Task`（子 agent） | `Task`（支持 `explore-agent` / `plan-agent` / `qoder-guide` 等 agent 类型）|
| `TodoWrite` | `TodoWrite` |
> Skill 是工作方法论，不是工具实现 —— 即使工具名略有差异，模型也会自动选用最近似的 Qoder 工具完成。无需为 Qoder 重写 skill。
## 故障排查
### 装好了但 `/` 看不到 skills
1. 确认 `.qoder/skills//SKILL.md` 文件存在
2. 确认 `SKILL.md` 文件的 frontmatter 完整（`name` + `description`，`description` 不超过 1024 字符）
3. **必须重启 Qoder** —— 新装的 skill 不会热加载
### skill 不被自动调用
Qoder 按 description 文本匹配用户意图来决定何时调用 skill。如果某个 skill 自动调用不可靠，可在对话中显式输入 `/` 手动触发。
中国原创的 4 个 `chinese-*` skill 本身就是**手动触发**设计（避免污染上游 skill 的自动调度），需要显式 `/chinese-code-review` / `/chinese-commit-conventions` 等。
## 卸载
```bash
cd /your/project
npx superpowers-zh --uninstall
```
会移除 `.qoder/skills/` 目录下所有 superpowers-zh 装的 skill 文件夹（保留你自己写的）。
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- 项目主页：https://github.com/jnMetaCode/superpowers-zh
- Qoder 官方文档：https://docs.qoder.com/zh/extensions/skills
---
### README.Qwen (`docs/README.qwen.md`)
# Superpowers 中文版 — Qwen Code 安装指南
在 [Qwen Code](https://github.com/QwenLM/qwen-code) 中使用 superpowers-zh 的完整指南。
## ⚠️ 先说清楚是哪个产品
**Qwen Code 是 [`QwenLM/qwen-code`](https://github.com/QwenLM/qwen-code) 这个命令行工具**（Gemini CLI 的 fork），跑在终端里。
它**不是**通义灵码 —— 通义灵码是阿里的 IDE 插件，是另一个产品，配置路径完全不同。
> 📌 v1.7.10 及更早版本的本文档把两者写混了（标题写「Qwen Code (通义灵码)」、链接指向 `tongyi.aliyun.com`）。照着那份文档去配通义灵码是配不通的。这是我们的错误，v1.7.11 起更正。
## 安装
```bash
cd /your/project
npx superpowers-zh --tool qwen
```
全局（所有项目共享）：
```bash
npx superpowers-zh --global --tool qwen
```
装两样东西：
| 位置 | 内容 |
|---|---|
| `.qwen/skills//SKILL.md`（全局为 `~/.qwen/skills/`） | 21 个 skill 正文 |
| `QWEN.md`（全局为 `~/.qwen/QWEN.md`） | bootstrap：核心规则 + skill 清单，引导 AI 在恰当时机去读对应 SKILL.md |
> 📌 v1.7.10 及更早**只装 skills、不写 bootstrap**。skills 能被 Qwen Code 发现，但没有引导就不会在恰当时机自动触发 —— 文件在磁盘上，实际很少被调用。v1.7.11 起补上。
## 工作原理
Qwen Code 两套机制我们都用上了，各自的出处：
**① Skills —— 自动发现，无需配置**
[官方 Skills 文档](https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/)：Qwen Code 从 `~/.qwen/skills/`（个人）和 `.qwen/skills/`（项目）自动发现 skill，每个 skill 是一个含 `SKILL.md` 的子目录，走 Agent Skills 开放标准（与 Claude Code、Gemini CLI 同一套）。
**② QWEN.md —— 分层记忆，自动拼接**
Qwen Code 的分层记忆系统默认上下文文件就是 `QWEN.md`，从当前目录逐层向上到项目根、以及全局 `~/.qwen/` 都会被扫描并拼接进上下文。文件名可用 `contextFileName` 设置改，默认 `QWEN.md`。
所以 bootstrap 写在 `QWEN.md` 里，每次会话自动加载；skill 正文留在 `.qwen/skills/` 按需读取，不占常驻开销。
### 已有 QWEN.md 怎么办
**追加，不覆盖。** 我们把内容包在哨兵注释之间，你自己写的部分原样保留；卸载时只切除我们那一段。已实测：装完再卸，你的 `QWEN.md` 逐字节恢复原状。
## Skill 加载优先级
| 位置 | 范围 |
|------|------|
| `.qwen/skills/` | 项目级，仅当前项目 |
| `~/.qwen/skills/` | 用户级，所有项目共享 |
同名时项目级优先。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p /your/project/.qwen/skills
cp -r superpowers-zh/skills/* /your/project/.qwen/skills/
```
> 手动复制不会生成 `QWEN.md` bootstrap，skill 会被发现但不会自动触发。建议优先用 `npx superpowers-zh --tool qwen`。
## 使用
装好重启 Qwen Code：
- 直接描述任务，bootstrap 会引导它匹配 skill：「帮我加一个导出功能」应先触发 brainstorming 做需求分析，而不是直接写代码
- 也可以点名：「用 brainstorming 分析这个需求」
- 用 `/memory show` 可以查看当前拼接进上下文的内容，确认 bootstrap 是否被加载
## 卸载
```bash
npx superpowers-zh --uninstall # 项目级
npx superpowers-zh --global --uninstall # 全局
```
会删除装过的 skill 目录，并从 `QWEN.md` 中精确切除 superpowers-zh 段（保留你自己写的内容）。实测全局卸载后 `~/` 下零残留。
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- Qwen Code 仓库：https://github.com/QwenLM/qwen-code
- Qwen Code Skills 文档：https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/
- Qwen Code 记忆文档：https://qwenlm.github.io/qwen-code-docs/en/users/features/memory/
---
### README.Reasonix (`docs/README.reasonix.md`)
# Superpowers 中文版 — Reasonix 安装指南
在 [Reasonix](https://reasonix.io/)（[esengine/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)，DeepSeek 原生终端 coding agent）中使用 superpowers-zh 的完整指南。
## 快速安装
```bash
cd /your/project
npx superpowers-zh # 自动检测 .reasonix/ 或 reasonix.toml
npx superpowers-zh --global --tool reasonix # 全局
```
## 装到哪、为什么
路径全部取自官方文档，不是猜的：
| 内容 | 路径 | 出处 |
|---|---|---|
| skills（项目级） | `.reasonix/skills/` | [`docs/CONFIG_PATHS.zh-CN.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/CONFIG_PATHS.zh-CN.md)：项目本地 settings / skills / commands 位于项目 `.reasonix/` 目录 |
| skills（全局，macOS/Linux） | `~/.reasonix/skills/` | 同上：「全局 skills = `/skills/`」，Reasonix home 在 macOS/Linux 为 `~/.reasonix` |
| skills（全局，**Windows**） | `%APPDATA%\reasonix\skills\` | 同上的 Reasonix home 表：**Windows 为 `%APPDATA%\reasonix`**，与 Unix 不同构 |
| 引导（项目级） | 项目根 `REASONIX.md` | [`docs/GUIDE.zh-CN.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/GUIDE.zh-CN.md)：常驻指令来自分层加载的 `REASONIX.md` / `AGENTS.md` / `CLAUDE.md` |
Windows 与 Unix 的全局路径**不同构**，安装器按平台自动选择（与 Crush 同一机制）。
## 全局安装不写引导文件，这是故意的
官方文档说常驻指令「用户全局文件先加载，再加载 workspace」，但**没有写明那个用户全局文件的确切路径**（`CONFIG_PATHS` 的目录内容表里没有它）。按本仓一贯口径：不确认就不写。
所以 `--global` 只装 skills、不写引导 —— 技能能被发现，但不会自动触发。**想要自动触发，请用项目级安装**（会写 `REASONIX.md`）。
若你查到 Reasonix 用户全局指令文件的确切路径，欢迎开 issue，我们会补上。
## 已经装过别的工具？
Reasonix 的技能配置里有 `excluded_paths = ["~/.agents/skills"]` 这样的示例，说明它会扫 `.agents/skills` 这类**约定来源**。如果你已经为 Codex CLI（全局 `~/.agents/skills`）或 Antigravity（项目 `.agents/skills`）装过，那批技能可能已经能被 Reasonix 读到 —— 重复安装会加载两份。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p .reasonix/skills
cp -r superpowers-zh/skills/* .reasonix/skills/
```
## 卸载
```bash
npx superpowers-zh --uninstall # 项目级（含 REASONIX.md 里我们写的那段）
npx superpowers-zh --global --uninstall # 全局
```
只移除我们装的技能目录与哨兵注释包住的引导段落，你自己写的内容不受影响。
## 相关 issue
- [#42](https://github.com/jnMetaCode/superpowers-zh/issues/42) 建议支持 Reasonix
---
### README.Trae Cn (`docs/README.trae-cn.md`)
# Superpowers 中文版 — TRAE CN（国内版）安装指南
TRAE 分**国际版**（[trae.ai](https://www.trae.ai)）与**国内版 TRAE CN**（[trae.cn](https://www.trae.cn)）。两版的**项目级**技能目录相同，**全局**目录不同 —— 这份文档讲的是差异部分。
## 一句话
| 想要什么 | 命令 | 装到哪 |
|---|---|---|
| 项目级（两版通用） | `npx superpowers-zh --tool trae` | `.trae/skills/` |
| 全局（**仅国内版**） | `npx superpowers-zh --global --tool traecn` | `~/.trae-cn/skills/` |
## 为什么全局要单独一条命令
[TRAE CN 官方文档「技能所在目录」](https://docs.trae.cn/ide/skills) 写明：
> 全局技能：macOS/Linux `~/.trae-cn/skills`，Windows `%userprofile%/.trae-cn/skills`
>
> 项目技能：项目所在路径下的 `.trae/skills/` 目录
注意全局目录是 **`.trae-cn`**，不是 `.trae` —— 差这一个后缀，装进去 TRAE 就永远不会扫到。
而[国际版文档](https://docs.trae.ai/ide/skills)**没有给出全局技能的磁盘路径**。按本项目一贯口径：**没有一手出处就不猜路径**，所以国际版不提供全局安装，请用项目级。
（`%userprofile%` 就是用户主目录，所以 Windows 与 macOS/Linux 在「主目录下的 `.trae-cn/skills`」这一点上是同构的，安装器不需要为它单独处理平台差异。）
## 项目级为什么两版共用一条命令
两版的项目级路径都是 `.trae/skills/`，所以 `--tool trae` 一条覆盖两版。
如果你对 `TRAE CN` 用项目级安装，安装器会**明确拒绝**并告诉你该用哪条命令，而不是装到一个可能不生效的地方：
```
❌ TRAE CN 不支持项目级安装。
TRAE CN 的项目级技能目录与国际版 TRAE 相同（.trae/skills/），
已经由 Trae 这一条覆盖，请直接用：
npx superpowers-zh --tool trae
本条目只用于 TRAE CN 独有的**全局**目录（~/.trae-cn/skills）。
```
## 自动触发
- **项目级**安装会同时写 `.trae/rules/superpowers-zh.md`，skill 因此能自动触发。
- **全局**安装只放 skill 文件，不写规则文件 —— TRAE CN 文档没有给出全局规则文件的确切路径，不确认就不写。所以全局装完需要在对话里显式点名 skill，或者改用项目级安装。
## 卸载
```bash
npx superpowers-zh --global --uninstall --tool traecn # 清 ~/.trae-cn/skills
npx superpowers-zh --uninstall --tool trae # 清 .trae/skills + .trae/rules
```
## 别名
`traecn`、`trae-cn`、`trae-china` 三个都指向同一个目标。
## 来源
- [TRAE CN 技能文档 · docs.trae.cn/ide/skills](https://docs.trae.cn/ide/skills) —— 全局与项目级路径（核对日期 2026-09-08）
- [TRAE 国际版技能文档 · docs.trae.ai/ide/skills](https://docs.trae.ai/ide/skills) —— 只给出 `.trae/skills/`，无全局路径
相关 issue：[#35 建议支持 Trae CN](https://github.com/jnMetaCode/superpowers-zh/issues/35)
---
### README.Trae (`docs/README.trae.md`)
# Superpowers 中文版 — Trae 安装指南
在 [Trae](https://www.trae.ai)（字节跳动 AI IDE）中使用 superpowers-zh 的完整指南。
## 快速安装
```bash
cd /your/project
npx superpowers-zh
```
安装脚本会自动检测 `.trae/` 目录，将各 skill 完整复制到 `.trae/skills/`（含 `SKILL.md` 及其 `scripts/` 等附属文件），并在 `.trae/rules/superpowers-zh.md` 生成一份 bootstrap 规则用于自动触发。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p /your/project/.trae/skills
cp -r superpowers-zh/skills/* /your/project/.trae/skills/
```
> 手动复制只会放好 skill 文件，不会生成 `.trae/rules/` 下的 bootstrap 自动触发规则。建议优先用上面的 `npx superpowers-zh`，否则需要在对话里手动点名 skill 才会激活。
## 工作原理
Trae 使用 `.rules` 机制管理 AI 行为：
- **目录**：`.trae/rules/`
- **格式**：Markdown + metadata（description、globs、alwaysApply、priority）
- **规则类型**：
- **项目规则**（Project Rules）— 仅作用于当前项目
- **个人规则**（Personal Rules）— 用户级别，可被项目规则覆盖
- **优先级**：1-4，数值越高优先级越高
### Skills 适配
安装器把各 skill 放在 `.trae/skills//`，并在 `.trae/rules/superpowers-zh.md` 写入一份 bootstrap 规则。Trae 初始化时加载 `.trae/rules/` 下的规则，bootstrap 规则会引导 AI 在任务匹配时读取对应的 `.trae/skills//SKILL.md` 并遵循其流程。
### 推荐配置
安装完成后，在 Trae 的 Builder Mode 或 Chat 中提到 skill 名称即可激活：
```
使用头脑风暴 skill 来分析这个需求
```
## 中文支持
Trae 原生支持中文，与 superpowers-zh 完美配合：
- 所有 skills 均为中文
- 中文代码审查、中文 Git 工作流等国内特色 skills 开箱即用
- 支持 MCP 协议扩展
## 更新
```bash
cd /your/project
npx superpowers-zh
```
## 卸载 / 误装清理
如果不小心在主目录（`~`）误跑了 `npx superpowers-zh`，会把 skills 和 `.trae/rules/superpowers-zh.md` 写到你的 home。v1.2.1 起会主动拒绝，但老版本可能已经污染过。清理：
```bash
cd ~ # 或具体的项目目录
npx superpowers-zh@latest --uninstall
```
会删除 `.trae/skills/` 下装过的 skill、`.trae/rules/superpowers-zh.md`，并清理 `CLAUDE.md` 等文件里的 superpowers-zh 段（保留你自己写的内容）。
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- Trae 文档：https://docs.trae.ai/ide/rules
---
### README.Vscode (`docs/README.vscode.md`)
# Superpowers 中文版 — VS Code (Copilot) 安装指南
在 VS Code + GitHub Copilot 中使用 superpowers-zh 的完整指南。
## 前置条件
- VS Code（最新版本）
- GitHub Copilot 扩展（免费版或付费版均可）
## 快速安装
```bash
cd /your/project
npx superpowers-zh
```
安装脚本会自动检测 `.github/` 目录并将 skills 复制到该目录。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p /your/project/.github/superpowers
cp -r superpowers-zh/skills/* /your/project/.github/superpowers/
```
## ⚠️ v1.7.10 及更早版本请重新安装
旧版把 20 个 skill 拷进 `.github/superpowers/`，然后**什么引导都不写** —— 而 [VS Code 官方文档](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)明确 Copilot 只自动读这几处：
- `.github/copilot-instructions.md`、`AGENTS.md`、`CLAUDE.md`（始终生效）
- `.github/instructions/*.instructions.md`（按 frontmatter 的 `applyTo` 匹配）
**`.github/superpowers/` 不在其中，Copilot 一个字都不会读。** 旧文档还写着「建议你自己创建 `copilot-instructions.md` 引用它们」—— 等于我们知道需要引导，却让用户自己动手。
v1.7.11 起自动生成 `.github/instructions/superpowers-zh.instructions.md`（约 4.5 KB 索引，`applyTo: "**"` 对所有请求生效）。重装即可：
```bash
cd /your/project
npx superpowers-zh --tool vscode
```
## 工作原理
装两样东西：
| 位置 | 内容 | Copilot 是否自动读 |
|---|---|---|
| `.github/instructions/superpowers-zh.instructions.md` | 索引：核心规则 + 21 个 skill 的触发条件表 | **是**（`applyTo: "**"`） |
| `.github/superpowers//SKILL.md` | skill 正文 | 否，由索引引导按需读取 |
**为什么不直接改 `.github/copilot-instructions.md`：** 那是你的文件。我们用自己的 `.instructions.md`，两者互不干扰，卸载时也能精确删掉而不碰你的内容。
**为什么正文不放进索引：** `applyTo: "**"` 的文件对每个请求都生效，正文塞进去就是每轮常驻开销。索引 4.5 KB，正文按需读。
### frontmatter 说明
```yaml
---
applyTo: "**" # 对所有文件/请求生效；省略此字段则只能在对话里手动挂载
name: Superpowers-ZH
description: superpowers-zh 技能框架的索引与触发规则
---
```
`applyTo` 是关键 —— 官方文档原文：省略它，「instructions 不会自动应用，但你仍可手动加进某次聊天请求」。也就是说不写就等于白写。
### 使用 .instructions.md 文件（推荐）
VS Code 还支持更细粒度的 `.instructions.md` 文件：
```
.github/
copilot-instructions.md # 全局指令
.instructions/
typescript.instructions.md # TypeScript 文件专用
testing.instructions.md # 测试相关
```
## 使用
在 VS Code 中：
- **Copilot Chat**（`Ctrl+Shift+I`）：直接引用 skill 名称
- **内联补全**：自动遵循 copilot-instructions.md 中的规则
- **`/init`**：在 Chat 中输入，自动生成项目配置
## 局限性
VS Code Copilot 不像 Claude Code 那样支持 `Skill` 工具或子 Agent 派遣。以下 skills 需要手动参考而非自动执行：
- 派遣并行 Agent（需要 Agent 框架支持）
- 子 Agent 驱动开发（需要 Agent 框架支持）
- Git Worktree 使用（需要终端操作）
其他方法论类 skills（头脑风暴、TDD、调试、代码审查等）完全兼容。
## 更新
```bash
cd /your/project
npx superpowers-zh
```
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- VS Code Copilot 文档：https://code.visualstudio.com/docs/copilot/customization/custom-instructions
---
### README.Windsurf (`docs/README.windsurf.md`)
# Superpowers 中文版 — Windsurf 安装指南
在 [Windsurf](https://windsurf.com) 中使用 superpowers-zh 的完整指南。
## 自动安装
```bash
cd /your/project
npx superpowers-zh
```
安装脚本会自动检测 `.windsurf/` 目录并将 skills 复制到 `.windsurf/skills/` 目录。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
cp -r superpowers-zh/skills /your/project/.windsurf/skills
```
或全局安装（注意路径 —— **不是** `~/.windsurf/skills`）：
```bash
npx superpowers-zh --global --tool windsurf
# 等价于手动：cp -r superpowers-zh/skills/* ~/.codeium/windsurf/skills/
```
> 📌 **v1.7.10 及更早的 `--global` 装到了 `~/.windsurf/skills`，Windsurf 不读那里，等于装了不生效。** 这是我们的实现错误，v1.7.11 起修正为官方路径 `~/.codeium/windsurf/skills/`。之前全局装过的请重装，并可手动删掉遗留的 `~/.windsurf/skills`。
## 工作原理
[Windsurf 官方文档](https://docs.windsurf.com/windsurf/cascade/skills)明确了两个路径，**它们不同构**：
| 范围 | 路径 |
|---|---|
| 项目级 | `.windsurf/skills//` |
| 用户级（全局） | `~/.codeium/windsurf/skills//` |
用户级在 `~/.codeium/` 下而不是 `~/.windsurf/` 下 —— 这点反直觉，是我们之前搞错的地方。
自动发现，无需配置。Cascade 采用渐进式披露：默认只把 skill 的 name 和 description 交给模型，决定调用时才加载 SKILL.md 全文，所以装 20 个不会造成常驻开销。
### 跨工具发现
官方还写明 Windsurf 会扫 `.agents/skills/` 与 `~/.agents/skills/`；若开启了读取 Claude Code 配置，`.claude/skills/` 与 `~/.claude/skills/` 也会被扫描。
也就是说：**如果你已经为 Antigravity（`.agents/skills`）或 Claude Code 装过，Windsurf 其实已经能读到**，不必重复装 —— 否则会加载两份。
## Skill 加载优先级
| 位置 | 优先级 | 说明 |
|------|--------|------|
| `.windsurf/skills/` | 最高 | 项目级，仅当前项目 |
| `~/.windsurf/skills/` | 中 | 用户级，所有项目共享 |
## 使用
安装完成后重启 Windsurf，skills 会自动生效。
也可以在 `.windsurfrules` 文件中引用 skills 目录：
```
请参考 .windsurf/skills/ 目录中的 SKILL.md 文件作为工作方法论。
```
## 故障排查
### Skills 未生效
1. 确认 `.windsurf/skills/` 目录存在且包含 skill 文件夹
2. 每个 skill 需要包含有效 YAML frontmatter 的 `SKILL.md` 文件
3. 重启 Windsurf
## 获取帮助
- 提交 Issue：https://github.com/jnMetaCode/superpowers-zh/issues
- 项目主页：https://github.com/jnMetaCode/superpowers-zh
- Windsurf 文档：https://docs.windsurf.com/windsurf/cascade/memories
---
### README.Zcode (`docs/README.zcode.md`)
# Superpowers 中文版 — ZCode 安装指南
在 [ZCode](https://zcode.z.ai/)（智谱的 Agentic Development Environment）中使用 superpowers-zh 的完整指南。
## ⚠️ 只支持全局安装，这是证据决定的
```bash
npx superpowers-zh --global --tool zcode
```
装到 `~/.zcode/skills/`，所有工作区共享。
**项目级安装会被明确拒绝，不是漏做。** ZCode [官方技能文档](https://zcode.z.ai/docs/skill)（中英文版一致）只给出一个磁盘路径：
> ZCode Agent 的用户级技能目录：`~/.zcode/skills//SKILL.md`
而项目级在文档里是**应用内的 UI 导入动作**（设置 → 技能 → 导入，可选「链接到来源目录」或「复制成 ZCode 内部副本」，导入目标可选「全局」或「当前项目」），**从不暴露项目级磁盘路径**。
社区在 [#120](https://github.com/jnMetaCode/superpowers-zh/issues/120) 提供的补丁写的是 `.zcode/skills` + `.zcode/AGENTS.md` —— 那是让 AI 按目录结构猜的，官方文档里查无此路径。按本仓一贯口径：**不确认能生效就不写**，猜一个路径装进去只会变成「装了不生效」。
如果你确认了 ZCode 的项目级磁盘路径（最好带官方文档链接），欢迎开 issue，我们会补上。
## 装完怎么用
ZCode 里技能通过 `$skill-name` 调用：在输入框输入 `$`，选择需要的技能。也可以在 **设置 → 技能** 里查看列表、按名称搜索、用开关启用/停用。
装完后建议先确认：设置 → 技能 里能看到这 21 个 skill，且处于启用状态。
## 手动安装
```bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
mkdir -p ~/.zcode/skills
cp -r superpowers-zh/skills/* ~/.zcode/skills/
```
目录结构必须是**单层**：`~/.zcode/skills/<技能名>/SKILL.md`。官方文档明确提到「嵌套在分组目录下的技能不会被 Agent 识别」。
## 卸载
```bash
npx superpowers-zh --global --uninstall
```
只移除我们装的那 21 个技能目录，你自建的技能不受影响（已在 verify-release 里有断言守着）。
## 关于 AGENTS.md
ZCode 支持 `AGENTS.md` 作为六类扩展之一（技能、命令、MCP、Hooks、插件、AGENTS.md），但其**位置与作用域官方文档页没有直接写明**（文档指向内置的 `$zcode-configuration-guide` 技能查询）。因此本工具目前是 **skills-only**：不写 bootstrap 文件，不猜路径。
这意味着技能不会「自动触发」，需要你用 `$skill-name` 显式调用。若你查到 AGENTS.md 的确切位置与作用域，欢迎开 issue。
## 相关 issue
- [#95](https://github.com/jnMetaCode/superpowers-zh/issues/95) 建议支持 Zcode
- [#120](https://github.com/jnMetaCode/superpowers-zh/issues/120) feat: 添加 ZCode 支持
---
### Assets RECORDING GUIDE (`docs/assets/RECORDING-GUIDE.md`)
# GIF 录制指南
## 方式一：macOS 录屏（推荐，最真实）
### 准备
1. 终端字体调到 18pt+，背景用深色
2. 准备一个测试项目目录 `~/demo-project`
3. 确保 superpowers-zh 已安装
### 录制步骤
1. **Cmd+Shift+5** 打开录屏，选择录制区域（只录终端窗口）
2. 执行以下操作：
```bash
# 第一步：安装（3秒）
cd ~/demo-project
npx superpowers-zh
# 第二步：给 AI 提需求（等 AI 回复）
claude "给用户模块加一个批量导出功能"
```
3. 等 AI 输出中文的头脑风暴内容（澄清问题 + 方案），录到这里就可以停了
4. 停止录屏
### 转 GIF
```bash
# mov 转 gif（用 ffmpeg）
ffmpeg -i recording.mov -vf "fps=10,scale=700:-1:flags=lanczos" -c:v gif docs/assets/demo.gif
# 如果太大（>2MB），降低 fps 或尺寸
ffmpeg -i recording.mov -vf "fps=8,scale=600:-1:flags=lanczos" -c:v gif docs/assets/demo.gif
```
## 方式二：VHS 脚本（模拟输入，输出需要手动编排）
```bash
cd /Users/yx/work/wenzhang/superpowers-zh
vhs docs/assets/demo.tape
```
注意：VHS 只模拟键盘输入，AI 输出需要在 tape 文件中用 Type 模拟。
## 最终效果要求
- 时长：15-20 秒
- 文件大小：< 2MB
- 关键帧：能看到 AI 用中文输出设计方案/澄清问题
---
--- METRICS ---
- Files Extracted: 31
- Estimated Token Budget: ~23561 tokens
- Canonical Reference: https://codewiki.google/github.com/jnMetaCode/superpowers-zh