# 怎样在 Claude Code、Codex 和其他智能体里安装 Agent Skills > 把技能的文件夹放到智能体会去找的地方，文件夹里要有 SKILL.md。Claude Code 从 `~/.claude/skills/` 读个人技能，从 `.claude/skills/` 读某个项目的技能，Codex 读 `.agents/skills`。想把技能分享到一个仓库之外，就打包成插件。安装之前，先把技能里的每个文件都读一遍。 Mindket 编辑部 · 发布于 2026-11-04 · 更新于 2026-11-05 · https://mindket.com/cn/learn/agent-skills/install-agent-skills ## 要点 - 技能就是带 `SKILL.md` 的文件夹，所以安装技能，就是把这个文件夹放到智能体会扫描的位置。 - Claude Code 从 `~/.claude/skills/` 读你所有项目共用的技能，从 `.claude/skills/` 读某个仓库的技能，后者提交之后会随仓库传给别人。 - Codex、Cursor、Gemini CLI 和 VS Code 都会读 `.agents/skills/`，其中几个还会读 `.claude/skills/`。 - 插件可以把技能分享到一个仓库之外，而项目范围的插件，每个协作者仍然要各自安装一次。 - 安装之前，先读技能里的每个文件，因为技能可能带着脚本。 ## 开始之前 你需要一个要安装的技能文件夹：第 1 到 3 课里的 `reviewing-api-changes` 技能，或者任何你下载来的技能。主要步骤用 Claude Code 来做。其他智能体是可选的。在讲到插件之前，一个终端加一个文本编辑器就够了。 > 这里的每个路径和命令，都来自来源列表里的页面，每条来源都标明了阅读日期。本课不是实测。 ## 五步把技能装进 Claude Code Claude Code 为手动安装的技能提供两个位置。个人技能放在 `~/.claude/skills/reviewing-api-changes/SKILL.md`，在这台机器上的所有项目里都会加载。项目技能放在 `.claude/skills/reviewing-api-changes/SKILL.md`，只在这个仓库的会话里加载，提交之后会随仓库一起传给别人。[Claude Code 的技能文档](https://code.claude.com/docs/en/skills)把这两处都列了出来。 ````bash # Personal: every project on this machine mkdir -p ~/.claude/skills cp -r reviewing-api-changes ~/.claude/skills/ # Project: this repository, committed for your team mkdir -p .claude/skills cp -r reviewing-api-changes .claude/skills/ git add .claude/skills/reviewing-api-changes ```` 1. 复制之前先打开技能。读 `SKILL.md`，再读文件夹里的每个脚本和参考文件。Anthropic 建议检查所有随附文件，留意意料之外的网络调用，或与技能用途不符的文件访问。 2. 检查文件夹。`SKILL.md` 必须直接放在文件夹里，文件夹名应当和 frontmatter 里的 `name` 一致，规范就是这样要求的。 3. 想在所有项目里用，就把文件夹复制到 `~/.claude/skills/`。只想在一个仓库里用，就复制到 `.claude/skills/`。Claude Code 会监视这两个文件夹，所以不用重启。 4. 问一句 `What skills are available?`，看技能在不在列表里。再问一件和它的描述相符的事，或者直接用 `/reviewing-api-changes` 运行它。 5. 项目技能要提交这个文件夹，克隆仓库的人就都有了。想把技能交给仓库之外的人，就像下面插件那一节讲的那样，把它打包成插件。 ## 各个智能体去哪里找技能 格式是共用的，所以同一个文件夹可以在好几个智能体里使用，不同的只是它们扫描的位置。下面的时间线列出 Codex 和 Cursor 何时开始支持这个格式，矩阵列出五个文件夹，以及哪些智能体在文档里点了名。“未列出”的意思是该智能体的文档页没有提到这个文件夹，并不等于它会失败。 Cursor 另外还读 `.cursor/skills/` 和 `~/.cursor/skills/`，Gemini CLI 读 `.gemini/skills/` 和 `~/.gemini/skills/`。VS Code 里的 Copilot 会话用 `.github/skills/` 和 `~/.copilot/skills/`，它的 Local 聊天会话还会读 `.claude` 和 `.agents` 文件夹。 - Codex：运行 `$skill-installer` 加上精选技能的名字，比如 `$skill-installer linear`，或者把文件夹直接放进 `.agents/skills`。Codex 会从你启动它的目录一路向上扫描到仓库根目录，所以放在根目录的技能，对每个子文件夹都有效。安装器的细节，Mindket 的 Codex 技能那篇文章讲得更全。 - OpenClaw 有自己的技能注册库和 `openclaw` 命令，Mindket 的 OpenClaw 技能那篇文章有介绍。 - Cursor 只能通过插件来获取 GitHub 仓库里的技能，仓库里要有 `.cursor-plugin/marketplace.json`。在 Agent 聊天里输入 `/`，就可以按名字运行技能。Cursor 规则是另一项功能：Agent 在对话开始时读取的已保存指令。 - Gemini CLI 用 `gemini skills install https://github.com/user/repo.git` 从 git 地址安装。加上 `--scope workspace`，技能只在当前项目里生效，加上 `--path` 可以指定仓库里的某个子目录。 - 这条命令上的 `--consent` 参数会跳过 Gemini CLI 的交互式安全确认，所以在你读完技能之前别加它。 - VS Code：选中 Local 后，在聊天里输入 `/skills`，就会打开 Configure Skills 菜单。 **技能格式的普及时间线** 1. **2025年10月16日** Skills 来到 Claude。Anthropic 在 claude.ai、Claude Code 和 API 里推出 Skills。 2. **2025年12月19日** Codex 支持技能。OpenAI 宣布 Codex 正式支持技能。 3. **2026年1月23日** Cursor 加入 Agent Skills。Cursor 让它的智能体能用上 Agent Skills。 4. **2026年10月22日** 标准交给基金会。Anthropic 把 Agent Skills 的名称和标志、GitHub 组织和 agentskills.io 域名捐给 Agentic AI Foundation。到这时，已有 70 多个智能体平台集成了 Agent Skills。 来源：[Alex Albert on X: introducing Skills, 16 October 2025](https://x.com/alexalbert__/status/1978877498411880550) (2026-11-05 查阅)；[OpenAI Developers on X: Codex supports skills, 19 December 2025](https://x.com/OpenAIDevs/status/2002099762536010235) (2026-11-05 查阅)；[Cursor on X: Agent Skills in Cursor, 23 January 2026](https://x.com/cursor_ai/status/2014753596223770841) (2026-11-05 查阅)；[Anthropic: Donating Agent Skills to the Agentic AI Foundation](https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation) (2026-11-05 查阅) **各个智能体在文档里点名的文件夹** | | Claude Code | Codex | Cursor | Gemini CLI | VS Code（Local 聊天） | | --- | --- | --- | --- | --- | --- | | 项目里的 .claude/skills/ | ✓ 是 | 未列出 | ✓ 是 | 未列出 | ✓ 是 | | 项目里的 .agents/skills/ | 未列出 | ✓ 是 | ✓ 是 | ✓ 是 | ✓ 是 | | 项目里的 .github/skills/ | 未列出 | 未列出 | 未列出 | 未列出 | ✓ 是 | | 你个人的 ~/.claude/skills/ | ✓ 是 | 未列出 | ✓ 是 | 未列出 | ✓ 是 | | 你个人的 ~/.agents/skills/ | 未列出 | ✓ 是 | ✓ 是 | ✓ 是 | ✓ 是 | 来源：[Claude Code docs: Skills](https://code.claude.com/docs/en/skills) (2026-11-05 查阅)；[OpenAI: Build skills (Codex)](https://learn.chatgpt.com/docs/build-skills) (2026-11-04 查阅)；[Cursor docs: Agent Skills](https://cursor.com/docs/context/skills) (2026-11-04 查阅)；[Gemini CLI docs: Agent Skills](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md) (2026-11-04 查阅)；[VS Code docs: Agent Skills](https://code.visualstudio.com/docs/copilot/customization/agent-skills) (2026-11-04 查阅) ## 用插件分享技能 插件是一个文件夹，里面有技能、子智能体、钩子和 MCP 服务器，再加一份放在 `.claude-plugin/plugin.json` 的清单文件，Claude Code 把它当作一个整体来加载。这就是分享的途径：队友可以安装它，多个项目可以共用同一份，你还可以把它发布到插件市场。清单里只有 `name` 是必填的。每个技能放在插件根目录下的 `skills/review/SKILL.md`。放进 `.claude-plugin/` 里面的技能不会加载，[插件指南](https://code.claude.com/docs/en/plugins/create)专门提醒了这一点。 插件里的技能带着插件的名字，所以 `/my-plugin:review` 和独立的 `/review` 可以同时存在。要把一个项目的技能改成插件，就把 `.claude/skills` 复制到一个新文件夹里，放在 `.claude-plugin/plugin.json` 旁边。然后运行 `claude plugin validate ./my-plugin`，它会检查清单和每个技能文件的 frontmatter，通过时以 `0` 退出。再用 `claude --plugin-dir ./my-plugin` 试一试这个插件。 把插件交给别人有三种办法：给对方文件夹或它的压缩包，把它列进你自己的插件市场，或者提交到 [Anthropic 的目录](https://claude.ai/directory/manage)。安装范围决定谁能用到它。Mindket 的 Claude Code 插件那篇文章对插件市场讲得更深。 Anthropic 的[技能仓库](https://github.com/anthropics/skills)演示了插件市场这条路：把仓库添加一次，再按名字安装其中的一个技能包。它的 README 把这些技能称为演示，并要求你在依赖它们之前，先在自己的环境里测试。 > **从哪里获取技能** > > 只使用来源可信的技能：你自己创建的，或者从 Anthropic 获得的。 > > Anthropic, 安全注意事项, [Agent Skills 概览，Claude Platform 文档](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) (2026-11-04 查阅) ````text /plugin marketplace add anthropics/skills /plugin install example-skills@anthropic-agent-skills # In a terminal, once per collaborator, after a project-scope entry is committed claude plugin install @ --scope project ```` - 插件市场可以来自 GitHub 的 `owner/repo`（加上 `#ref` 可以固定分支或标签）、git 地址、本地路径，或者托管的 `marketplace.json`。添加一次，之后按名字安装。 - Anthropic 官方插件市场和从 claude.ai 添加的插件市场默认开启自动更新，其他插件市场，包括社区插件市场，默认关闭。来自第三方插件市场的插件，会一直停在安装时的版本，直到你运行 `claude plugin update my-plugin@my-marketplace`，或者在 Marketplaces 标签页里打开自动更新。 | 范围 | 谁能用到插件 | 记录在哪里 | | --- | --- | --- | | 用户 | 你自己，这台机器上的每个项目 | `~/.claude/settings.json` | | 项目 | 在这个仓库里工作的每个人，各自运行一次安装之后 | `.claude/settings.json`，你来提交 | | 本地 | 只有你自己，只在这个仓库里 | `.claude/settings.local.json` | ## Boris Cherny 谈插件市场，以及 Codex 和 Cursor 怎样支持技能 Claude Code 的作者、Anthropic 的 Boris Cherny，2026 年 2 月在一串技巧帖里[把插件排在第 3 条](https://x.com/bcherny/status/2021699862522364149)。一个插件一次就能装上技能、MCP 服务器、子智能体、钩子和语言服务器。他建议从 Anthropic 官方插件市场安装，或者给公司建一个自己的插件市场，再把 `settings.json` 提交进代码库，让整个团队都自动添加这个插件市场，不过插件本身仍要每个队友各装一次。上面的范围表格写明了那是哪个设置文件。 你装好的文件夹能用到别的智能体里，是因为它们也采用了这个格式。2025 年 12 月，[OpenAI Developers 发帖说](https://x.com/OpenAIDevs/status/2002099762536010235) Codex 正式支持技能，可以用 `$` 加技能名直接调用，也可以让 Codex 按你的提示自己挑。2026 年 1 月，[Cursor 宣布](https://x.com/cursor_ai/status/2014753596223770841) Agent Skills 已经能在 Cursor 里用。复制技能之前，先在矩阵里挑一个你用的每个智能体都会读的文件夹，比如 Codex 和 Cursor 都读的 `.agents/skills/`。 > 从 Anthropic 官方插件市场安装插件，或者给你的公司建一个自己的插件市场。 > > Boris Cherny, Claude Code 的作者，Anthropic，引文为译文, [X](https://x.com/bcherny/status/2021699862522364149) (2026-11-05 查阅) [![Boris Cherny（@bcherny）2026 年 2 月 11 日在 X 上的技巧帖第 3 条：安装插件、MCP 和技能。插件可以安装 LSP、MCP、技能、子智能体和自定义钩子。从 Anthropic 官方插件市场安装插件，或者给你的公司建一个自己的插件市场。](https://mindket.com/blog/shots/x-bcherny-install-plugins.webp?v=2063e2b0ba23)](https://x.com/bcherny/status/2021699862522364149) Boris Cherny 在 X 上，2026 年 2 月 11 日 > X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 5 日，时间为 UTC。X 用“Show more”截断了帖子后面的内容。点击截图可到 X 上打开原帖。 ## 常见错误 - 把整个仓库复制进技能文件夹。每个技能都要有自己的文件夹，`SKILL.md` 直接放在里面，比如 `~/.claude/skills/reviewing-api-changes/SKILL.md`。 - 文件夹叫一个名字，`name` 字段写另一个名字。规范要求这两者一致。 - 提交了项目范围的插件条目，就以为团队已经有了这个插件。这个条目只是启用它，每个协作者仍然要各自运行一次安装。 - 把 Claude Code 的技能原样上传到 claude.ai。上传只接受 `name`、`description`、`license`、`compatibility`、`metadata` 和 `allowed-tools`，其他任何 frontmatter 键都会让上传失败。 - 把热门仓库当成安全的仓库。Anthropic 特别点出，会抓取外部网址的技能风险尤其大，因为抓回来的文字里可能带着指令。而且即使是值得信任的技能，只要它依赖的外部内容随时间变了，也可能被攻破。 ## 自己试一试 把 `reviewing-api-changes` 技能，或者你手上任何一个技能，安装两次。先放进一个临时仓库的 `.claude/skills/` 里，问一句 `What skills are available?`。再复制到 `~/.claude/skills/`，再问一次。最后把项目里的那份包成插件，用 `--plugin-dir` 加载，留意它的命令变成了 `/my-plugin:reviewing-api-changes`。 做完之后，把临时仓库和个人目录里的那份副本删掉，别让这次测试留下东西。 - 两个位置的技能都出现在列表里了吗？按名字调用时，运行的是哪一份？ - 插件里的那份副本，是不是出现在插件的名字下面？ - 复制之前，你有没有把技能里的每个文件都打开看过？ ## 下一课：Claude Code 进阶 Agent Skills 这门课到这里就结束了。你现在会写、会测、会安装技能，自然的下一步，是去调好运行它的智能体。[Claude Code 进阶课](https://mindket.com/cn/learn/claude-code-advanced/claude-code-settings)先讲设置文件，再讲无头运行、CI 和 Agent SDK。 技能告诉智能体怎样做一件事。后面的 MCP 课程讲的是给它工具和数据、让它把这件事做成的那些服务器。 ## 自测一下 1. 在 Claude Code 里，哪个路径放的是对你所有项目都生效的个人技能？ A. `.claude/skills/reviewing-api-changes/SKILL.md` B. `~/.claude/skills/reviewing-api-changes/SKILL.md` C. `~/.agents/skills/reviewing-api-changes/SKILL.md` 答案：B。 个人技能放在 `~/.claude/skills/`，这台机器上的所有项目都会加载，而 `.claude/skills/` 只属于一个仓库。 2. 你把下载来的整个仓库复制进了 `~/.claude/skills/`，但没有任何技能加载。最可能的错误是什么？ A. 个人技能必须放进某个项目文件夹 B. 文件夹名不能和 `name` 字段一致 C. Claude Code 只加载已经提交的技能 D. 每个技能都要有自己的文件夹，`SKILL.md` 直接放在里面 答案：D。 一个技能就是一个文件夹，`SKILL.md` 直接放在里面，比如 `~/.claude/skills/reviewing-api-changes/SKILL.md`。 3. 你把项目级插件的条目提交到了 `.claude/settings.json`，每个协作者还需要做什么？ A. 各自运行一次插件安装 B. 什么都不用做，插件已经装好了 C. 把插件复制到 `~/.claude/skills/` 答案：A。 提交的条目只是启用这个插件，每个协作者仍然要自己运行一次安装。 4. 把下载来的技能复制进技能文件夹之前，你该先做什么？ A. 看看它的仓库有多少人点了星 B. 对它运行 `claude plugin validate`，通过就放心 C. 读 `SKILL.md` 以及里面每个脚本和参考文件 答案：C。 Anthropic 建议检查所有随附文件，看有没有意外的网络调用，或者与技能用途不符的文件访问。 ## 常见问题 ### 新装的技能在 Claude Code 里没有出现，怎么办？ 如果会话开始时，最上层的技能文件夹还不存在，就运行 `/reload-skills`，因为 Claude Code 还没有监视它。除此之外，加上 `--debug` 运行，可以看到 frontmatter 的解析错误。格式错误的 YAML 仍然会加载技能正文，但元数据是空的，所以 Claude 没法按描述去匹配。 ### 两个技能同名时会怎样？ 在 Claude Code 里，企业级优先于个人级，个人级优先于项目级，所以个人的 `deploy` 会代替项目里的那个运行。插件里的技能和独立的技能会同时加载，因为插件的名字是它命令的前缀。Codex 不会合并同名技能，两个都可能出现在它的选择列表里。Gemini CLI 用优先级更高的位置，工作区高于用户级。 ### 同一份技能，能只留一份给好几个智能体用吗？ Codex 扫描自己的位置时会跟随符号链接指向的技能文件夹，所以 `.agents/skills/` 里放一个符号链接，就能指向你存放在别处的技能。Cursor 为了兼容 Codex，还会读 `.codex/skills/` 和 `~/.codex/skills/`。 ### 怎么删除一个技能？ 在 Claude Code 里，删掉文件夹，会话就会拾取这个改动。插件用 `claude plugin uninstall my-plugin@my-marketplace` 移除，用 `--scope` 指明范围。Gemini CLI 有 `/skills disable` 加技能名。Codex 用一条把 `enabled` 设为 `false` 的 `[[skills.config]]` 条目来关闭技能，之后需要重启。 ### 智能体在安装技能之前，会给我看什么？ 在 Claude Code 的会话里，`/plugin install` 会先打开插件的详情，列出它将添加的命令、子智能体、技能、钩子和 MCP 服务器，供你选择范围。Gemini CLI 安装时会要求确认，除非你加了 `--consent`，激活技能时，它还会显示技能的名称、用途和目录。 ### claude.ai 或者 API 能用上我在 Claude Code 里的技能吗？ 不能。Anthropic 说，自定义技能不会在各个平台之间同步：上传到 claude.ai 的技能，要在 API 上重新上传一次。Claude Code 的技能和这两者都是分开的。claude.ai 接受压缩包，每次只给一个用户，而 API 的技能是在整个工作区里共享的。 ## 资料来源 - [Claude Code docs: Skills](https://code.claude.com/docs/en/skills) (2026-11-05 查阅) - [Claude Code docs: Install and manage plugins](https://code.claude.com/docs/en/discover-plugins) (2026-11-05 查阅) - [Claude Code docs: Create a plugin](https://code.claude.com/docs/en/plugins/create) (2026-11-05 查阅) - [Claude Platform docs: Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) (2026-11-04 查阅) - [Anthropic skills repository](https://github.com/anthropics/skills) (2026-11-04 查阅) - [Agent Skills specification](https://agentskills.io/specification) (2026-11-04 查阅) - [OpenAI: Build skills (Codex)](https://learn.chatgpt.com/docs/build-skills) (2026-11-04 查阅) - [Cursor docs: Agent Skills](https://cursor.com/docs/context/skills) (2026-11-04 查阅) - [Gemini CLI docs: Agent Skills](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md) (2026-11-04 查阅) - [VS Code docs: Agent Skills](https://code.visualstudio.com/docs/copilot/customization/agent-skills) (2026-11-04 查阅) - [Boris Cherny on X: tip 3, install plugins, MCPs and skills, 11 February 2026](https://x.com/bcherny/status/2021699862522364149) (2026-11-05 查阅) - [Alex Albert on X: introducing Skills, 16 October 2025](https://x.com/alexalbert__/status/1978877498411880550) (2026-11-05 查阅) - [OpenAI Developers on X: Codex supports skills, 19 December 2025](https://x.com/OpenAIDevs/status/2002099762536010235) (2026-11-05 查阅) - [Cursor on X: Agent Skills in Cursor, 23 January 2026](https://x.com/cursor_ai/status/2014753596223770841) (2026-11-05 查阅) - [Anthropic: Donating Agent Skills to the Agentic AI Foundation](https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation) (2026-11-05 查阅) [浏览技能](https://mindket.com/cn/skills)