43edf34b2c
## Windsurf --global 一直装在 Windsurf 不读的地方
官方文档（docs.windsurf.com/windsurf/cascade/skills）写明两个路径**不同构**：
项目级：.windsurf/skills/<skill-name>/
用户级：~/.codeium/windsurf/skills/<skill-name>/ ← 在 .codeium 下
我们的 --global 装到 ~/.windsurf/skills —— Windsurf 不读那里。又一个 Hermes 同款
「装了完全不生效」。项目级路径是对的，只有全局错。
Cursor 一并核实：cursor.com/docs/skills 确认 .cursor/skills/<name>/SKILL.md
启动时自动发现，无需配置 —— 我们装的是对的。
## 测试为什么没抓到：只验退出码，不验落盘位置
verify-release 的 C 段对全局白名单只断言「退出码为 0」。装到错目录退出码照样是 0。
**「跑通了」不等于「装对了」。** 新增 GLOBAL_DIR 断言：10 款全局工具逐个断言
skill 真的落在官方读的那个目录，外加一条自检（GLOBAL_DIR 必须覆盖 GLOBAL_OK 全部，
以后加全局工具不能漏断言）。
双向验证：把 Windsurf 全局路径改回旧值，立刻报
「--global windsurf: .codeium/windsurf/skills 里是 0 个 skill，期望 20」。
## 两个我自己写出来的静默失效
**① `grep -P` 不可移植。** 新加的「变量后紧跟多字节字符」检查第一版用了 grep -P，
在交互 shell 里（ugrep）看着能用，进了脚本跑的是 /usr/bin/grep（BSD grep，不支持
-P），配上 2>/dev/null 就成了永远匹配不到的死检查 —— 正是我这两天一直在修的那类
bug，自己又造了一个。改用 LC_ALL=C + ERE：C locale 下多字节按单字节处理，>0x7F
的字节落在 [^ -~] 之外，BSD/GNU 都支持。
**② 同一个全角括号坑又踩一次。** `期望 $EXPECT_SKILLS（…）` 里全角括号被吞进变量
名，set -u 下脚本半途崩掉。这已经是本仓第二次（第一次是死链检查的 $code）。所以
把它固化成 audit 1e，注释行排除，双向验证过。
## 一次操作事故（记下来）
用 /tmp 备份做变异测试时，把 verify-release.sh 的未提交改动整段覆盖没了，
git diff 才发现。变异测试应该用 git 保护现场，不该用 /tmp 拷贝。
## 其它
- 外链验活跳过分支补 ok，否则 PASS 总数随网络漂移、发版记录对不上（实测连跑两次
稳定 111）
- docs/README.windsurf.md 重写：两个路径不同构、渐进式披露（默认只给模型 name +
description，不造成常驻开销）、跨工具发现（也扫 .agents/skills 与 .claude/skills，
装过 Antigravity 或 CC 的不必重复装）
audit 168 pass / 0 warn / 0 fail；verify-release 111 pass / 0 fail。
2.8 KiB
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