野渡
搜索 K

主题

Claude Code 里安装 skills

1,314 字 5 分钟

Claude Code 里安装 skills ​

Summary

Claude Code 目前安装 skills 的主线只有两种：

  1. 裸 skill：放进 ~/.claude/skills/ 或 <repo>/.claude/skills/
  2. 可安装分发：把 skill 做进 plugin，再通过 plugin marketplace 安装

目前没有官方一等公民的 raw skill 安装命令（例如 claude skill install ...）。

一页结论 ​

场景推荐方式原因
个人长期复用~/.claude/skills/最简单，所有项目可复用
团队项目共用<repo>/.claude/skills/可随仓库版本化，clone 即得
组织级分发 / 更新plugin + marketplace有安装、更新、namespace
本地调试 / 临时加载--plugin-dir / --add-dir适合开发态，不适合长期分发

安装方式总览 ​

方式典型位置 / 命令官方支持度适合场景
user-level skill~/.claude/skills/<skill-name>/SKILL.md高个人通用 workflow
project-level skill<repo>/.claude/skills/<skill-name>/SKILL.md高项目专属规则、团队共享流程
plugin 安装/plugin install <plugin>@<marketplace>高跨项目复用、统一 rollout、版本升级
开发态加载claude --plugin-dir <dir>中本地调试 plugin
临时目录注入claude --add-dir <dir>中偏低临时让某个 .claude/skills/ 生效
Note

--add-dir 的本意是扩展文件访问范围，不是通用配置分发机制。.claude/skills/ 只是少数会被额外发现的例外。

有没有官方的 skill install 命令？ ​

结论：没有查到官方提供独立的 raw skill 安装命令。

也就是说，目前没有看到类似：

text
claude skill install ...
claude skills add ...
/skill install ...

当前更接近“安装器”的体验在 plugin 层，而不是裸 skill 层。

user-level vs project-level ​

类型路径作用范围是否随仓库共享适合放什么
user-level~/.claude/skills/<skill-name>/SKILL.md你所有项目否/commit、/review、/debug、个人高频 workflow
project-level<repo>/.claude/skills/<skill-name>/SKILL.md当前项目是项目部署命令、仓库专属 review 流程、特定 CI / 测试 / 发布步骤

优先级 ​

官方文档提到，同名 skill 的优先级是：

text
enterprise > personal > project
Warning

这和很多人的直觉相反：个人级会覆盖项目级，项目级并不是最高优先级。

获取 / 分发方式怎么选 ​

方式是否靠谱结论
clone 项目仓库高如果仓库已带 .claude/skills/，这是完全自然且对齐官方的方式
clone skill 仓库后复制目录高对裸 skill 来说很稳，常见且可靠
直接复制目录高最朴素、也最稳的做法
symlink / 符号链接低可实验，但不建议作为长期主方案
git submodule中偏低不是官方主路径，维护复杂度通常更高
plugin marketplace高适合安装、更新、分发与 namespace 管理

常见坑点 ​

现象 / 问题可能原因应对方式
skill 装了但没自动触发description 写得不清晰；skills 太多导致触发质量下降description 前置关键词，保持短而明确
skill 没出现在 slash 菜单user-invocable: false这不等于没被发现，Claude 仍可能自动调用
skill 从不自动调用disable-model-invocation: true这种情况下通常只能手动调用
plugin 装了但当前会话不生效会话未刷新执行 /reload-plugins
monorepo 里 skill 看起来失效没放在当前工作目录附近使用嵌套 .claude/skills/，让 skill 更贴近子项目
临时目录里的 skill 生效了，但其他配置没生效--add-dir 只对 .claude/skills/ 有例外意义不要把它当完整配置安装体系
同样的 skill 在另一台机器不生效CLI 启动参数禁用了 skills排查 --bare、--disable-slash-commands

发现与加载机制要点 ​

1. commands 和 skills 已经合流 ​

旧的 custom commands 已并入 skills 语义：

  • .claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都可能创建 /deploy
  • 新内容更推荐优先用 skills
  • 若同名，skill 优先于 command

2. 嵌套目录会自动发现 ​

在 monorepo 场景里，Claude Code 会发现当前工作目录附近的：

text
packages/frontend/.claude/skills/

这意味着你可以把 skills 放在更贴近子项目的位置，而不是全堆到仓库根。

3. description 比你想象中更重要 ​

Claude 通常会先基于 skill 的 description 做匹配，再按需加载完整 SKILL.md。

所以：

  • description 太长、太虚，会影响自动匹配
  • skills 太多时，长描述还可能被截断
  • 最好把关键词前置，写成短而明确的说明

实用决策树 ​

你的场景选择
我自己想长期用~/.claude/skills/
团队在一个项目里共用<repo>/.claude/skills/ 并提交到 git
我要给很多项目 / 很多人分发，还要更新plugin + marketplace
monorepo，且某些技能只属于某个子包嵌套 .claude/skills/

推荐与不推荐 ​

推荐 ​

  • 个人技能放 user-level
  • 项目技能放 project-level 并入库
  • 需要安装 / 更新 / 分发时做成 plugin
  • 对裸 skill，优先使用 clone + copy 或直接复制目录

不推荐 ​

  • 把 symlink 当主安装方案
  • 优先用 git submodule 管 skills
  • 长期依赖 --add-dir 做分发
  • 全局堆很多 skill，且 description 写得很长
  • 从不受信任的 marketplace / plugin 安装
Danger

plugin 可能带 hooks、MCP、脚本，风险级别远高于“复制一个 Markdown 文件”。安装来源一定要看信任边界。

最终建议 ​

如果只记住一句话：

Tip

个人用 ~/.claude/skills/，团队项目用 <repo>/.claude/skills/，组织级分发用 plugin marketplace。不要把 symlink / submodule 当主方案，也不要期待现在有独立官方的 skill install 命令。

Sources ​