fb63548c9d
## Codex：项目级又是「装了完全不生效」
官方 skills 文档（developers.openai.com/codex/skills，现 308 跳到官方新文档站）
给出的扫描目录**完整清单**：
$CWD/.agents/skills、$CWD/../.agents/skills、$REPO_ROOT/.agents/skills
$HOME/.agents/skills、/etc/codex/skills、内置 skill
**没有 .codex/skills。** 两次分别追问确认「.codex/skills 是否曾被扫描」，答案都是
从未出现。而我们项目级正是装到 .codex/skills。
全局（~/.agents/skills）一直是对的 —— 原注释也写明了「不是 ~/.codex/skills」，
说明当初查过全局却没顺手核项目级。改为 .agents/skills，并在安装时清理旧位置
（只清我们装的那些，用户自己放在 .codex/skills 下的不动，已实测）。
与 Antigravity 共用 .agents/skills 是 Agent Skills 开放约定，不是冲突。
## 这个改动暴露出一个既有 bug：检测有顺序依赖
改完后测试立刻报「检测 .codex/ -> 得到「Antigravity,Codex CLI」，期望「Codex CLI」」。
根因：自动检测是**边装边判**的。Codex 装到 .agents/skills 会创建 .agents/，
循环走到 Antigravity（detect: '.agents'）时它就被误判为「项目里有这个工具」，
于是多装一份。这个坑在任何「装了 A 会创建 B 的检测标记」的组合上都会犯。
改为先把所有工具的检测结果一次性算完再开始装 —— 检测必须基于**安装前**的项目
状态。实测：只有 .codex 时只装 Codex；同时有 .codex 与 .agents 时两款都装且
.agents/skills 下仍是 20 个（不重复）。
## CodeArts：官方已证实用户级路径，补上 --global
原注释只写「用户在 #20 确认」，没有官方出处。已补华为云官方用户指南出处：
项目级：项目根目录的 ./.codeartsdoer/skills/
个人级：%USERPROFILE%/.codeartsdoer/skills 即 ~/.codeartsdoer/skills
既然已证实，--global 从拒绝名单移出并加落盘断言。实测装 20 个到
~/.codeartsdoer/skills、卸载后 HOME 零残留。仍是 skills-only —— 其 bootstrap
约定未证实，不猜。
## 顺带核实
- Cursor：官方 skills 文档确认 .cursor/skills/<name>/SKILL.md ✅
- OpenCode：官方 skills 文档确认项目级与全局都对 ✅（唯二全对的之一）
- Kimi / Pi：不在 TARGETS 里，走 plugin manifest 与扩展分发；已确认 docs 没有
承诺 --tool kimi/pi，installer 也正确拒绝这两个名字，无虚假承诺
audit 168 pass / 0 warn / 0 fail；verify-release 115 pass / 0 fail。
Superpowers 中文版 — Windsurf 安装指南
在 Windsurf 中使用 superpowers-zh 的完整指南。
自动安装
cd /your/project
npx superpowers-zh
安装脚本会自动检测 .windsurf/ 目录并将 skills 复制到 .windsurf/skills/ 目录。
手动安装
git clone https://github.com/jnMetaCode/superpowers-zh.git
cp -r superpowers-zh/skills /your/project/.windsurf/skills
或全局安装（注意路径 —— 不是 ~/.windsurf/skills）：
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 官方文档明确了两个路径，它们不同构：
| 范围 | 路径 |
|---|---|
| 项目级 | .windsurf/skills/<skill-name>/ |
| 用户级（全局） | ~/.codeium/windsurf/skills/<skill-name>/ |
用户级在 ~/.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 未生效
- 确认
.windsurf/skills/目录存在且包含 skill 文件夹 - 每个 skill 需要包含有效 YAML frontmatter 的
SKILL.md文件 - 重启 Windsurf