Jason Pan

安装一个 Skill 的时候，你到底安装了什么？

潘忠显 / 2026-06-03

上一篇文章讲了 Skill 和普通 Python 项目的区别，本文聊聊安装 Skill 的时候到底发生了什么。

比如你要安装企业微信文档的 Skill，为什么需要在命令行中执行两条指令，选项又是什么含义？

npm install -g @wecom/cli
npx skills add WeComTeam/wecom-cli -y -g

又比如你要在 ClaudeCode 中安装官方执行下面的操作，到底又会安装在哪里？

/plugin marketplace add anthropics/skills

安装 Skill，本质上是在把一组“给 Agent 看的说明书 + 可选工具包”放到宿主能发现的位置。

Skill 里有什么

Agent Skill 的定义和规范是有一套推荐标准的，可以在 https://agentskills.io/ 中查看。后边我们单独一篇聊聊怎么写好 Skill 会再细聊。

先看一个 Skill 的目录结构通常不复杂，不同实现里目录名字会有差异，但思路基本类似：

some-skill/
├── SKILL.md    # 必须的：metadata + 指引
├── scripts/    # 可选的：关联脚本，稳定的执行操作
├── assets/     # 可选的：模板、schema、资源等
├── references/ # 可选的：示例、规范说明、常见问题等
└── ...

每个技能都包含一个目录，其中至少包含一个 SKILL.md 文件。此文件必须以 YAML 前置元数据开头，以保存必需的名称和描述字段。它还可以包含其他元数据、Claude 的说明或参考文件、可执行脚本或工具，也可以包含哪些事不能做、哪些边界不能越过的列举。

不少情况下，只有一个 SKILL.md，也可以工作。比如前面文章介绍的 <andrej-karpathy-skills> 只有一个 .md 文档，就在 GitHub 上斩获 16 万星。

这里可以顺便解释一下经常跟 Skill 被同时提起的 CLI（Command Line Interface），其原意是命令行界面。在实际语境里，我们也常把可以在终端里直接运行的命令行工具叫 CLI。它通常接收命令、参数和选项，执行某个确定性任务，然后把结果输出到终端、文件或标准输出里。git、npm、skills 都是典型例子。

Skill 里的 scripts/ 和 CLI 有点像，都是为了执行确定性操作。区别更多在于分发和复用范围：scripts/ 通常跟着某个 Skill 走，通过路径调用；CLI 通常会被安装成一个命令，可以跨项目、跨 Skill 复用。

安装 Skill 真正发生了什么

开头我提到了两种方式，通过 npx skill 和在 ClaudeCode 通过 /plugin 指令安装。

其实两种方式安装和使用方式抽象一下都是一样的几步：

  1. 找到 Skill 来源，比如 GitHub 仓库、本地目录、官方列表、社区列表或插件市场。
  2. 把 Skill 相关文件下载或复制到本地
  3. 放到跟各类 Agent约定的位置，建立可发现性
  4. Agent 在会话启动或运行过程中发现这些 Skill。
  5. 用户请求命中某个 Skill 时，Agent 再读取 SKILL.md，按里面的流程读资源、调脚本或调用其他工具。

跟 npm、npx、skills install 有什么关系

为什么安装 Skill，还会用到 npm、npx 指令？比如安装企业微信文档需要使用下边的指令：

npm install -g @wecom/cli
npx skills add WeComTeam/wecom-cli -y -g

第一步 npm install 其实不是安装 Skill 本身，而是通过 npm 安装了一个全局 CLI。装完以后就能直接敲 wecom-cli 指令了。和 scripts/ 中脚本类似，都是为了执行确定性操作，但它的层级更靠外。-g 选项是工具安装到一个全局的系统目录中，在哪里都可以调用 wecom-cli 指令。

npm 是 Node.js 生态里的包管理器，用来安装、更新、卸载和发布 package。它不只可以管理 JavaScript 代码，也可以分发 Rust、Go、C++ 编译出来的二进制工具。比如上边这个 skill 中大量的 CLI 是通过 Rust 开发的。

第二步 npx skills install 才是真正的安装 Skill，也就是将其复制或者链接到对应目录。-g 选项指定 Skill 的安装到全局范围，如果不带可能会安装在当前项目中。

npx 更像是“临时运行一个 npm 包里的命令”。比如 npx skills install ...，它会先找到 skills 这个包，没有就临时下载，然后执行里面暴露的 CLI。它适合偶尔运行某个工具，或者不想提前全局安装 CLI 的场景。

安装完之后可以通过 skills ls -g 查看安装了哪些工具：

skills

skills 指令虽然是通过 npm 分发的，但这里 npm 只是在帮你拿到并运行 skills 这个安装器。skills 后面安装的技能内容，是符合 Agent Skill 约定的一组文件，而跟 Node.js 不再有半点关系。

Skills 安装去了哪

前面提到 skills install 如果不带 -g 会将其安装在项目级目录，带会安装到用户级目录。

前面图中通过 skills ls -g 的结果，其实有展示了对应 Skill 的目录和可供使用的Agent。以其中一个为例：

session-tester-script ~/.codebuddy/skills/session-tester-script
    Agents: CodeBuddy, Cursor

上边 session-tester-script 这个可以被两个 Agents 使用：CodeBuddy, Cursor，为了给多个 Agent 使用，其是会被复制到多个位置的。

当同一个 skill 同时出现在多个 Agent 的加载目录里，skills ls -g 会把它合并成一条记录。列表里显示的路径只是其中一个实际目录，通常是扫描时先遇到的路径。比如该 Skill 实际出现在多个 Agent 的目录里：

~/.codebuddy/skills/session-tester-script/
~/.cursor/skills/session-tester-script/

另外还有 ~/.agents/skills 目录是个 Claude Code 使用的。

自己开发 Skill 的维护

不管是自己开发的 Skill 还是 外部安装的，都需要放到这些目录里，才能被 Agent 发现和使用。

但是如果是自己长期维护的 Skill，不建议直接把 ~/.agents/skills/、~/.claude/skills/ 这类加载目录当成源码目录来改。

直接在里面改，短期能用，但后面会遇到几个问题：不好做版本管理，容易被重新安装或更新覆盖，不方便分享给别人。

更稳的方式是把自己的 Skill 放在一个单独 repo 里维护：

my-agent-skills/
├── writing-style/
│   ├── SKILL.md
│   └── ...
├── wecom-doc/
└── mp-weixin/

日常编辑这个 repo，把它当成真正的源码。需要给 Agent 使用时，再通过安装器复制或链接到对应的加载目录。

比如下边这个 mp-weixin-skill 就是我个人开发的 Skill，以链接的方式进行了安装。

custom-skills

这样直接解决了前面提到的三个潜在风险：

  1. 源码在自己的 repo 里，方便 git 管理和回滚
  2. 安装目录只是运行时结果，可以随时重装
  3. 分享给别人时，直接给 GitHub 仓库和安装命令

加载目录负责让 Agent 发现能力，源码仓库负责让人维护能力，两者应该区分开来。

Plugin 和 Skill 的区别

Agent Skills 有通用规范，可以被理解成一种跨 Agent 的能力描述方式。不同宿主只要支持这个规范，就有机会复用同一个 Skill。

而在使用 ClaudeCode 的时候，可以在其中使用下边的插件指令：

# 把 anthropics/skills 这个仓库注册成一个 plugin marketplace 来源
/plugin marketplace add anthropics/skills

# 从 anthropic-agent-skills 安装 document-skills 这个 plugin
/plugin install document-skills@anthropic-agent-skills

这里 Plugin，它可以把多个能力打在一起，包括：Skills、MCP connectors、MCP servers等等。它解决的是：**怎么把一组能力作为一个可安装、可更新、可分享的整体交给 Claude Code / Claude 使用。**可以参考 Plugins 文档 https://claude.com/docs/plugins/overview 。

Plugin 这种打包机制和约束，对 Claude Code 和 Claude 适用，别的 Agent 不一定适用。

小结

本文先带大家理解了什么是 Skill、常见的安装方式，以及安装过程中到底发生了什么、最终安装到了哪里。随后解释了 npm、npx、skills 等工具在安装过程中的作用，并辨析了 Plugin 和 Skill 的区别。在理解这些基础上，进一步说明了开发个人 Skill 时应该如何维护。