如何激活 Claude Code Skills

Claude Code 会自行激活 Skills，没有所谓的“启用”命令：会话开始时，它会读取所有能找到的 Skill 的 name 和 description frontmatter，并在任务匹配时载入完整指令。这个设计让上下文保持精简——也正是为什么放错位置或描述含糊的 Skill 永远不会被激活。

Claude Code 在哪里寻找 Skills

一个 Skill 就是一个文件夹，它的指令保存在 SKILL.md 文件中。Claude Code 会从三个位置发现这些文件夹：

• 个人 Skills：~/.claude/skills/<skill-name>/SKILL.md——对你的用户在所有项目中可用。
• 项目 Skills：仓库内的 .claude/skills/<skill-name>/SKILL.md——随代码做版本管理，与团队共享。
• 插件 Skills：通过 /plugin 命令从插件市场安装——按插件而不是按文件夹管理。

如果文件夹放在其他任何位置——下载目录、随意嵌套的子目录、深了一层的路径——无论 Skill 写得多好，Claude Code 都看不到它。

一份合法的 SKILL.md 长什么样

激活从文件顶部的 YAML frontmatter 开始。描述要具体，并写清适用场景：Claude 读取的触发条件就是这一句话。

---
name: release-notes
description: 根据git历史和最近的PR标题起草更新日志。当用户要求撰写或更新发布说明时使用。
---

# Release notes

1. 收集上一个tag以来的PR标题。
2. 按新增、变更、修复分组。
3. 每条变更一行，使用用户视角的表述。

有两个细节最关键。第一，description 应说明“什么时候用”，而不只是“里面有什么”。第二，辅助脚本和模板要放在同一个文件夹里——Skill 可以通过相对路径引用自己的文件。

在会话中激活 Skill

1. 把 Skill 文件夹放进 ~/.claude/skills（个人）或项目的 .claude/skills（随仓库共享）。
2. 启动一个新的 Claude Code 会话。Skill 在会话启动时被发现，已经运行的会话不会看到刚添加的文件夹。
3. 询问 Claude 它能做什么——例如 这个项目里有哪些可用的 skills？——确认你的 Skill 出现在列表中。
4. 开始一个与描述匹配的真实任务。任务对得上时，Claude 会载入完整的 Skill 指令并遵循执行。

Skill 死活不激活时

• 位置错误：文件夹多嵌套了一层，SKILL.md 不在 Claude 预期的位置。
• frontmatter 无效：缺少 name、description 为空，或起始 --- 之前有多余字符。
• 会话过期：会话在 Skill 添加之前就已启动，重启会话即可。
• 描述不清：Skill 能被发现但从不被选中，因为 description 与你表述任务的方式不匹配。
• 重复 Skills：两个描述重叠的 Skill 相互竞争同一任务，删除或重命名较弱的那一个。

跨项目、跨 Agent 的激活管理

手动激活对一个项目、一个 Agent 来说没问题。但当你为多个项目、多个工具维护 Skills 时就会失控：Claude Code、Codex、Gemini CLI 各有自己的目录，同样的复制粘贴流程反复上演，各处的安装副本逐渐失同步。

SkillSlot 是一款本地优先的 macOS 应用：它把你的 Skills 收进同一个 Vault，并以 Loadout（可复用组合）的形式、通过一次明确操作部署到 Claude Code 和其他 Agent。你不必再纠结“正确的文件夹有没有到达正确的项目”——选 Loadout、选目标、部署，就这三步。