如何安装 Claude Skill？文件到底应该放在哪里
三种安装 Agent Skill 的方法、各个 Agent 实际读取的目录、如何确认已经加载，以及 Agent 忽略 Skill 时应该怎么排查。
最简单的方法
让 AI 帮你做
把下面这句话发给你正在使用的 AI Agent：
请帮我安全地安装一个 Agent Skill。先问我使用哪个 AI Agent，以及 Skill 文件夹或下载链接在哪里；然后把它放进正确目录，检查 SKILL.md 是否直接位于 Skill 文件夹中，并告诉我如何确认已经加载。覆盖任何文件前先征求我的同意。
安装 Skill，其实就是把整个 Skill 文件夹放到 Agent 会读取的位置，然后开启一个新会话。Claude Code 读取 ~/.claude/skills，多数其他 Agent 读取 ~/.agents/skills。下面列出完整目录、三种安装方法，以及如何确认安装是否成功。
先看结论
- Claude Code →
~/.claude/skills - Codex、Cursor、Gemini CLI、OpenCode、Kimi Code →
~/.agents/skills - Antigravity →
~/.gemini/config/skills - 安装后要开启一个新会话。Agent 通常在会话开始时扫描 Skill。
- 如果 Agent 没有使用它，先检查目录，再检查是否真的开了新会话。
开始前需要准备什么
你需要三样东西：
- 一个支持读取 Skill 的 Agent，例如 Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Kimi Code CLI 或 Antigravity。
- Skill 文件夹，可以来自下载包，也可以来自代码仓库。
- 只有使用命令行安装时才需要：macOS 或 Windows，以及 Node.js 22 或更高版本。
Skill 应该放在哪里
目录放错后通常不会出现明确报错，Agent 只会完全看不到这个 Skill。请按下面的路径安装：
| Agent | Skill 目录 |
|---|---|
| Claude Code | ~/.claude/skills |
| Codex | ~/.agents/skills |
| Cursor | ~/.agents/skills |
| Gemini CLI | ~/.agents/skills |
| OpenCode | ~/.agents/skills |
| Kimi Code CLI | ~/.agents/skills |
| Antigravity | ~/.gemini/config/skills |
~/.agents/skills 是多个 Agent 共同采用的目录约定。因此，同一份 Skill 放在这里，往往可以同时给几个工具使用。
如果你的 Agent 不在表格里，请查看它自己的文档，不要猜目录。路径错误时，Agent 通常不会提示你。
方法一：直接复制文件夹
这个方法适用于任何来源的 Skill，也不需要提前安装工具。
-
下载并解压 Skill。最终应该得到一个包含
SKILL.md的文件夹。 -
把整个文件夹移到上表对应的目录。如果目录还不存在，可以先创建：
mkdir -p ~/.claude/skills mv ~/Downloads/story-first-deck ~/.claude/skills/ -
开启一个新会话。只发送一条新消息还不够。
安装后的结构应该像这样：
~/.claude/skills/
└── story-first-deck/
├── SKILL.md
├── references/
└── scripts/
最常见的问题是多套了一层同名文件夹。如果路径变成 ~/.claude/skills/story-first-deck/story-first-deck/SKILL.md，Agent 就可能找不到它。SKILL.md 应该直接位于 Skill 文件夹中。
方法二：用 Skillry CLI 一条命令安装
如果 Skill 来自 Skillry，Skillry CLI（Skillry 命令行工具）会自动下载、解压，并放进对应 Agent 的目录。
先登录一次：
npx --yes skillry-cli@latest login
浏览器会自动打开授权页面。授权完成后，可以确认登录状态：
npx --yes skillry-cli@latest status
然后安装。默认目标是 ~/.agents/skills：
npx --yes skillry-cli@latest install story-first-deck
如果要安装给 Claude Code，请指定 Agent：
npx --yes skillry-cli@latest install story-first-deck --agent claude-code
--agent 支持 shared、codex、cursor、gemini-cli、opencode、claude-code、kimi-code 和 antigravity。如果你的 Agent 不在列表里，可以自行指定目录：
npx --yes skillry-cli@latest install story-first-deck --target ~/some/other/skills
有两条规则需要注意：不要同时使用 --agent 和 --target；覆盖现有版本时加上 --force，旧版本会自动保留备份。
CLI 会把访问令牌保存在 macOS 钥匙串或 Windows 凭据管理器里，不会写入 .env 或 JSON 文件。正常安装过程也不会要求你创建或粘贴 API key（API 密钥）。
方法三：让 Agent 帮你安装
Skillry 上的每个 Skill 页面都提供一份机器可读的安装说明，地址是 /skills/<slug>/install.md。把这个地址交给 Agent，让它按说明安装即可。Agent 会读取页面、选择适合自己的目录、执行安装，并告诉你文件最终放在哪里。
如果你已经在 Agent 会话里，不想切换到终端，这是最快的方法。
如何确认已经加载
可以按下面的顺序检查：
- 直接问。 问 Agent：“你现在有哪些可用的 Skill？”列表里应该出现对应名称。
- 实际使用。 复制 Skill 页面里的演示提示词。如果已经加载，Agent 通常会说明正在使用这个 Skill。
- 查看文件。 运行
ls ~/.claude/skills，确认文件夹存在，而且SKILL.md直接位于其中。
Agent 没有使用 Skill 怎么办
| 你看到的情况 | 通常原因 | 处理方法 |
|---|---|---|
| Agent 完全没有提到这个 Skill | 目录错误，或安装后没有开启新会话 | 对照上表检查目录，然后新开会话 |
SKILL.md 多嵌套了一层 | 压缩包里还有一个外层文件夹 | 把内层 Skill 文件夹上移一级 |
| Agent 知道它存在，却没有使用 | 你的请求没有匹配 Skill 的 description（用途描述） | 先原样使用 Skill 页面上的演示提示词 |
| 提示缺少模型或工具 | Skill 依赖外部服务 | 查看 Skill 页面的 Dependencies（依赖）和 Outside costs（外部费用） |
| Agent 变慢，回答也更模糊 | 安装了太多 Skill | 删除不常用的 Skill |
| 安装过程要求粘贴 API key | 立即停止 | 正常的 Skillry 安装流程不会要求你粘贴密钥 |
删除 Skill 时，移除对应文件夹并开启新会话。更新 Skill 时，替换文件夹后同样要开启新会话。
安全提醒
安装前，应把每个 Skill 包都当作尚未核验的代码。先阅读 SKILL.md，并检查 scripts/ 中的所有内容，因为这些脚本可能会在你的电脑上运行。
Skillry 的安装流程不会要求你粘贴 API key、令牌或密码。授权会在浏览器中完成，访问令牌不会直接展示给你。有些 Skill 在实际运行时可能需要已声明的外部服务凭据；请使用 Agent 或对应服务提供的密钥管理方式保存，不要把凭据写进 SKILL.md，也不要发在聊天消息里。
常见问题
Skill 到底应该放在电脑的哪个位置？
取决于你使用的 Agent，请对照上面的目录表。Skillry 上每个 Skill 自带的 install.md 也会列出支持的 Agent 和准确目录。它会随产品更新，通常比博客里的固定路径更可靠。
安装后需要重启吗？ 需要开启一个新会话，让 Agent 重新扫描 Skill 目录。
可以只安装到某个项目里吗？ 一些 Agent 同时支持用户级和项目级 Skill 目录。如果 Skill 只服务于一个代码库或客户项目，项目级目录通常更合适。
免费和付费 Skill 的安装方式不同吗？ 安装步骤相同。两者都需要登录后下载，区别只在于账户是否拥有下载权限。
一个文件夹可以同时给两个 Agent 使用吗？
可以。多个 Agent 都会读取 ~/.agents/skills。保留一份主要副本，可以避免不同位置的版本逐渐不一致。
Windows 支持命令行安装吗？ 支持。目录结构相同，只是根路径位于你的 Windows 用户目录下。
接下来
想知道 Claude Skill 能不能在 Cursor 或 Codex 中使用？继续看哪些内容可以通用，哪些不能。