5. 安装与加载

这是什么：技能装在工具约定的目录里，工具启动时扫描这些目录，把找到的技能登记成一张可用清单。

为什么用：装在哪、谁优先、能不能被模型调用，都是工具说了算。同一个技能名在两个位置都有，你以为跑的是 A，其实是 B。

如何用：本章对照四家工具的技能目录，讲清优先级与权限开关，再讲安装渠道、校验命令，以及第三方技能的安全红线。

5.1 四家工具的技能目录

工具	项目级	个人级（全局）
Claude Code	`.claude/skills/<name>/SKILL.md`	`~/.claude/skills/<name>/SKILL.md`
opencode	`.opencode/skills/<name>/SKILL.md`	`~/.config/opencode/skills/<name>/SKILL.md`
opencode（兼容目录）	`.claude/skills/`、`.agents/skills/`	`~/.claude/skills/`、`~/.agents/skills/`
Hermes	——	`~/.hermes/skills/<name>/SKILL.md`
OpenClaw	`<workspace>/skills/<name>/SKILL.md`	`~/.agents/skills/`、`~/.openclaw/skills/`

几点补充：

Claude Code 还认嵌套目录：<subdir>/.claude/skills/。启动时在子目录里跑，会同时加载仓库根目录和各级父目录的 .claude/skills/；启动位置下方的技能则要等 Agent 首次读那个子目录的文件才加载。
opencode 的扫描同样从当前工作目录向上走到 git 仓库根，所以在 packages/frontend/ 里启动也能拿到根目录的技能。
OpenClaw 最多向下扫 6 层找 SKILL.md，所以 skills/research/SKILL.md 这种分组布局也能被发现。

想一份技能多工具通用，最省事的做法是放进项目的 .claude/skills/，opencode 认这个位置，Claude Code 原生认，其它工具按第 5.2 节的额外目录机制接入。

5.2 加载优先级：同名了谁赢

技能名冲突时，各家规则不同：

Claude Code：

企业策略 > 个人级 > 项目级

个人级和项目级都有 deploy 时，/deploy 跑的是个人级那个。另外插件技能统一带命名空间（/my-plugin:review），不和本地技能打架。

OpenClaw（从高到低）：

优先级	来源	路径
1（最高）	工作区技能	`<workspace>/skills`
2	项目 Agent 技能	`<workspace>/.agents/skills`
3	个人 Agent 技能	`~/.agents/skills`
4	托管 / 本地技能	`~/.openclaw/skills`
5	Workshop 技能	`<state-dir>/agents/<agentId>/agent/workshop-skills`
6	内置技能	随安装附带
7（最低）	额外目录	配置里追加的目录 + 插件自带技能

⚠️ Claude Code 有两个保留名：技能文件夹别叫 synced（那是 claude.ai 同步技能的落盘目录）或 anthropic-skills（同步技能的命名空间），叫了会被直接跳过不加载。

排查同名冲突的办法：先全局搜一遍同名目录——

# Linux / macOS
find ~ -type d -name "release" -path "*skills*" 2>/dev/null

# Windows PowerShell
Get-ChildItem -Path $env:USERPROFILE -Recurse -Directory -Filter "release" -ErrorAction SilentlyContinue |
  Where-Object { $_.FullName -match "skills" }

5.3 权限：技能能不能被模型调用

光被发现不等于能被用。opencode 给了最直观的权限模型，在 opencode.json 里配：

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

值	行为
`allow`	立即加载
`deny`	对 Agent 隐藏，根本看不见
`ask`	加载前弹窗要你确认

模式支持通配符，internal-* 能匹配 internal-docs、internal-tools 等一串。也可以按 Agent 单独覆盖：

{
  "agent": {
    "plan": {
      "permission": { "skill": { "internal-*": "allow" } }
    }
  }
}

不想要技能的 Agent 可以整个关掉（此时 <available_skills> 段落会完全消失）：

{
  "agent": {
    "plan": { "tools": { "skill": false } }
  }
}

这个开关的思路值得抄到自己的工具里：技能是「教它怎么做」，但有些技能只适合人手动触发。

5.4 怎么装

渠道	做法	适用场景
直接拷文件夹	把 `my-skill/` 复制到目标技能目录	最通用，任何工具都行
git 仓库	克隆到技能目录，或用工具自带的 git 源	团队共享、要跟版本走
技能市场	用工具自带的安装命令	挑现成的
本地目录	指定路径安装	还没发布的技能

各家市场的命令长这样：

# Hermes
hermes skills browse                       # 浏览全部可用技能
hermes skills search kubernetes            # 按关键词搜
hermes skills inspect openai/skills/k8s    # 安装前先预览
hermes skills install openai/skills/k8s    # 安装（会先跑安全扫描）

# OpenClaw
openclaw skills search "周报"
openclaw skills install @owner/<slug>
openclaw skills verify @owner/<slug>

注意那几个动词：inspect / verify 是安装前的安全闸门，别跳过。

5.5 校验与体检

格式层面的校验用规范的参考库：

skills-ref validate ./my-skill

工具自己的体检命令则能回答「我明明写了，它怎么不认」：

openclaw skills list     # 列出已识别技能
openclaw skills check    # 排查「配置了却加载不了」
hermes skills inspect <slug>   # 看某个技能的具体内容

技能加载不了时，按这个顺序查：

文件名是不是全大写 SKILL.md（写成 skill.md 不会被认）
frontmatter 是不是在第一行，--- 前面不能有空格或空行
有没有 name 和 description
name 是否合法、是否和目录名一致
技能名在所有位置是否唯一
权限是不是被设成了 deny

5.6 安全：第三方技能当成不可信代码

这条是红线：一个技能文件虽然只是 Markdown，但它能指示 Agent 去调哪些工具、跑哪些命令。装一个来路不明的技能，等于把工具权限发出去一份。

装之前至少做三件事：

先读一遍 SKILL.md，看它让 Agent 干什么——尤其是有没有 allowed-tools、有没有让 Agent 跑网络请求
用官方的 inspect / verify / 安全扫描，别跳过
别在有生产权限的环境里装没验证过的技能

另外两条来自官方文档的提醒：

Claude Code 从 claude.ai 同步的技能：你本地改了 ~/.claude/skills/synced/ 里的文件不会回传，下次同步可能被覆盖；要改去 claude.ai 上改
技能正文里的 shell 片段：Claude Code 支持 !`命令` 动态注入——运行时真的执行命令、把输出塞进上下文。这是执行，不是文档，第三方技能里出现这个就要多看两眼

🤝 记忆口诀：技能是说明书，但说明书能让它动手——先读后装，先验后用。

动手改

在项目的 .claude/skills/ 下建一个技能，然后在 opencode 里开个会话，用 skill 工具看看它有没有出现在 <available_skills> 里
故意造一个「加载不了」的例子：把 SKILL.md 改名成 skill.md，或者把 --- 挪到第二行，然后跑 skills-ref validate 和工具自带的 list 命令，看两边分别怎么报错
写一份技能的安全自查清单（至少 5 条），贴到你团队的 AGENTS.md 或贡献指南里

小结

目录对照：Claude Code .claude/skills/、opencode .opencode/skills/（也认 .claude/ .agents/）、Hermes ~/.hermes/skills/、OpenClaw <workspace>/skills/
同名冲突各家用优先级解决，Claude Code 是「企业 > 个人 > 项目」，OpenClaw 有七级表；排查靠全局搜同名目录
权限可以按技能配：allow / deny（隐藏）/ ask（确认）
安装走「拷贝 / git / 市场」，市场的 install 前先 inspect、verify
校验用 skills-ref validate，加载排查用工具自带的 list / check
第三方技能按不可信代码对待：先读、先验、别在生产环境乱装

下一章：综合练习，把这一整套做出来 🐸