441d024cd6
## 我们装错了目录，一直没生效 #45 报告人说「项目级 .hermes/skills/ 里的 20 个 skill 全部返回 404，必须手动 复制到 ~/.hermes/skills/ 才被识别」。查官方文档核实，他是对的： hermes-agent.nousresearch.com/docs/user-guide/features/skills 明确 Hermes 只自动加载 ~/.hermes/skills/（原文 "the primary directory and source of truth"），项目级目录不被自动发现；外部目录必须写进 ~/.hermes/config.yaml 的 skills.external_dirs。 而我们从支持 Hermes 起就只装项目级 .hermes/skills/ —— 那个目录 Hermes 根本 不读。这不是「不好用」，是「装了完全不生效」，比不支持更糟。 ## 改法 - TARGETS 给 Hermes 加 global（~/.hermes/skills），全局成为推荐装法 - 项目级仍保留（skills 可随仓库分发），但装完打印**可直接粘贴**的配置片段： skills: external_dirs: - <项目绝对路径>/.hermes/skills 不替用户改 config.yaml —— 那是他们的文件。文档里也写明「配置里不存在的 路径会被静默跳过」，所以写错不会报错、只会没生效。 - 全局模式**不写 bootstrap**：Hermes 的用户级指令文件约定没有公开文档， 往 $HOME 根目录写 HERMES.md 是猜路径 + 污染主目录。实测确认全局装完 $HOME 根目录 0 个文件、卸载 0 残留。 ## 文档与清单 - docs/README.hermes.md 开头重写，把「必须全局」放在最前面，并注明 v1.7.8 及更早只支持项目级 = 装了不生效，是我们的实现错误 - 简繁 README：全局支持清单加 Hermes Agent，工具表的安装命令改为 --global - verify-release.sh 的 GLOBAL_OK 加 hermes、GLOBAL_NO 移除 ## 验证 - 全局：装 20 skills 到 ~/.hermes/skills、$HOME 根目录 0 文件、卸载 0 残留 - 项目级：正确打印 A/B 两种方案与绝对路径的 config.yaml 片段 - audit.sh 166 pass / 0 warn / 0 fail、verify-release.sh 90 pass / 0 fail 注：#45 的后半部分（7 个 skill 文件里 24 处硬编码 Claude 工具名）本次未动。 那属于行为塑造内容，且 references/hermes-tools.md 已有完整映射表， 应走「强化映射表引用」而非把正文改成某个 harness 专属工具名。
3.5 KiB
Superpowers 中文版 — Hermes Agent 安装指南
在 Hermes Agent 中使用 superpowers-zh 的完整指南。
⚠️ 先看这一条：必须装到全局，否则不生效
Hermes 官方文档明确：Hermes 只自动加载 ~/.hermes/skills/（原文称其为 "the primary directory and source of truth"），项目级目录不会被自动发现。
所以推荐的装法是全局：
npx superpowers-zh --global --tool hermes
装到 ~/.hermes/skills/，装完即生效，用 skills_list 就能看到 20 个 skill。
📌 v1.7.8 及更早版本只支持项目级安装（装到
<项目>/.hermes/skills/）—— 那个目录 Hermes 根本不读，等于装了不生效。这是我们的实现错误，v1.7.9 起修正。见 #45。
如果你确实要项目级安装
项目级的好处是 skills 可以随仓库一起分发。但必须显式登记，否则 Hermes 看不见。
cd /your/project
npx superpowers-zh --tool hermes
安装器会打印出你需要粘贴的配置片段，形如：
skills:
external_dirs:
- /your/project/.hermes/skills
把它加进 ~/.hermes/config.yaml。路径支持 ~ 展开和 ${VAR} 环境变量替换；配置里不存在的路径会被静默跳过，所以写错了不会报错，只会"没生效"。
我们不替你改 config.yaml —— 那是你的配置文件。
项目级安装还会生成 HERMES.md 引导文件（含核心规则和 skills 列表），让 Hermes 在合适时机主动检查 skill。全局安装不写这个文件 —— Hermes 的用户级指令文件约定没有公开文档，我们不猜路径、也不往你的主目录里写东西。
同名冲突
如果同一个 skill 名在 ~/.hermes/skills/ 和某个 external_dirs 目录里都存在，本地（~/.hermes/skills/）的版本优先。
其他 config.yaml 用法
如果希望全局使用 superpowers-zh skills，可以在 ~/.hermes/config.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 未发现
- 确认
.hermes/skills/目录存在且包含 skill 文件夹 - 每个 skill 目录下需要有
SKILL.md文件 - 使用
skills_list查看已发现的技能
HERMES.md 未加载
- 确认文件在项目根目录（与
.hermes/同级） - 文件名可以是
HERMES.md或.hermes.md