Claude Code Skills完全指南：一次编写，自动匹配的按需知识注入

为什么你需要 Skills？

每次让 Claude 审查 PR 时，你都要重新描述反馈格式；每次提交代码，你都要提醒 Claude 你偏好的 commit message 风格。这种重复劳动不仅浪费时间，还消耗宝贵的上下文窗口。

Claude Code 的 Skills（技能） 功能正是为解决这个问题而生——它是一个 Markdown 文件，让你只需教 Claude 一次，之后它就能在相关场景中自动应用这些知识。

与每次对话都会加载的 Claude.md 不同，Skills 是按需加载的。你的 PR 审查清单不需要在你调试代码时占用上下文窗口，它只在你真正请求审查时才会激活。

Skills 的核心机制

语义匹配与自动触发

Skill 文件包含两个关键部分：名称（name） 和 描述（description）。当你向 Claude 发出请求时，Claude 会将你的请求与所有可用 Skill 的描述进行语义匹配，自动激活最相关的 Skill。

语义匹配示意

这意味着你不需要像 Slash 命令那样手动输入指令。Claude 会识别场景并自动应用。例如，当你说"帮我看看这个 PR"，Claude 就会匹配到描述中包含"代码审查"相关语义的 Skill。

存储位置与优先级规则

Skills 可以存放在不同位置，服务不同范围的需求：

个人 Skills：存放在 ~/.claude/skills/，跟随你的所有项目。适合个人偏好，如 commit message 风格、文档格式等。
项目 Skills：存放在项目根目录的 .claude/skills/ 中。任何克隆仓库的人都会自动获得这些 Skills，适合团队标准。
插件 Skills：通过插件市场分发，适合跨项目、跨团队的通用能力。
企业 Skills：通过管理员部署，优先级最高，用于强制执行安全要求和合规流程。

优先级从高到低为：企业 > 个人 > 项目 > 插件。如果企业级有一个名为 code-review 的 Skill，你个人同名的 Skill 就会被覆盖。解决方案是使用更具描述性的名称，比如 frontend-pr-review 或 security-review。

Skills 与其他自定义方式的区别

Claude Code 提供了多种自定义选项，理解它们的区别至关重要：

自定义方式对比

功能	加载方式	适用场景
Claude.md	每次对话自动加载	项目级始终生效的标准，如"永远不要修改数据库 schema"
Skills	按需匹配加载	特定任务的专业知识，如 PR 审查清单
Sub-agents	独立上下文运行	需要隔离执行的委托任务
Hooks	事件驱动触发	每次保存文件时运行 linter 等自动化操作
MCP	外部工具集成	提供额外的工具能力

一个典型的配置可能是：Claude.md 负责始终生效的项目标准，Skills 负责特定任务的专业知识，Hooks 负责自动化操作。它们各司其职，可以同时使用。

Sub-agents 与 Skills 的继承关系

一个容易被忽略的细节是：Sub-agents 不会自动继承你的 Skills。当你委托任务给 Sub-agent 时，它从一个全新的上下文开始。内置的 Explorer、Plan、Verify 等 Agent 完全无法访问 Skills，只有自定义 Sub-agent 才可以——而且你必须在 agent.md 文件的 skills 字段中显式列出需要加载的 Skills。

需要注意的是，Sub-agent 的 Skills 在启动时就全部加载，而非按需加载，因此只列出与该 Sub-agent 职责始终相关的 Skills。

高级技巧：让 Skills 更高效

渐进式披露控制上下文消耗

Skills 与你的对话共享上下文窗口。如果把所有内容塞进一个 2000 行的文件，不仅占用大量 token，维护起来也很痛苦。

渐进式披露

解决方案是渐进式披露（Progressive Disclosure）：将核心指令放在 skill.md 中，详细参考资料放在独立文件中，Claude 只在需要时才读取。

推荐的目录结构：

skill.md：核心指令（建议控制在 500 行以内）
scripts/：可执行脚本
references/：补充文档
assets/：图片、模板等资源

在 skill.md 中链接到支持文件，例如："如果用户询问系统架构，请阅读 references/architecture.md"。这样就像在上下文窗口中放了一个目录，而不是整本书。

脚本执行优于内容加载

Skill 目录中的脚本可以直接执行，而不需要将其内容加载到上下文中。脚本执行后，只有输出结果消耗 token。这对于环境验证、数据转换等场景非常有用——告诉 Claude 运行脚本，而不是阅读脚本。

使用 allowed-tools 限制工具权限

有时你希望某个 Skill 只能读取文件而不能修改。通过 allowed-tools 字段可以实现这一点，限制 Claude 在该 Skill 激活时只能使用指定的工具，适用于安全敏感的工作流。

常见问题排查

当 Skills 不按预期工作时，问题通常归为以下几类：

Skill 没有触发？ 问题几乎总是出在描述上。Claude 使用语义匹配，你的请求需要与描述的含义有足够的重叠。尝试添加用户实际会说的触发短语，如"帮我分析性能"、"为什么这么慢"、"让它更快"。

Skill 没有加载？ 检查文件结构：skill.md 必须位于以 Skill 名称命名的目录内（不是 skills 根目录），文件名必须是 SKILL.md（SKILL 大写，md 小写）。运行 claude --debug 查看加载错误。

加载了错误的 Skill？ 你的描述可能与其他 Skill 太相似。让每个描述尽可能具体和独特。

运行时失败？ 检查外部依赖是否已安装，脚本是否有执行权限（使用正斜杠路径，即使在 Windows 上）。

此外，可以使用 Agent Skills Verifier 工具进行验证，推荐通过 UV 安装，它能快速定位大部分结构性问题。

分享 Skills 与团队协作

团队分享

最简单的分享方式是将 Skills 提交到仓库的 .claude/skills/ 目录。团队成员克隆仓库后自动获得，推送更新后下次 pull 即可同步。

对于跨项目的通用 Skills，可以打包为插件发布到市场。在插件项目中创建 skills 目录，遵循相同的文件结构即可。

对于企业级部署，管理员可以通过 managed settings 在组织范围内强制推行 Skills，确保安全要求和合规流程的一致性。

实战：创建你的第一个 Skill

以创建一个个人 PR 描述 Skill 为例：

mkdir -p ~/.claude/skills/pr-description

然后创建 SKILL.md 文件，包含：

name：标识你的 Skill
description：告诉 Claude 何时使用（最多 1024 字符，这是最重要的字段）
指令部分：Claude 需要遵循的具体步骤

创建完成后重启 Claude Code（它在启动时扫描 Skills），然后验证是否可用。当你说"为我的改动写一个 PR 描述"时，Claude 会匹配到该 Skill，请求确认后加载完整内容并按照你的模板执行。

每次都是相同的格式，无需重复解释。

总结

Skills 的核心价值在于一次编写，自动匹配。它填补了"始终加载"的 Claude.md 和"手动触发"的 Slash 命令之间的空白，提供了一种优雅的按需知识注入机制。如果你发现自己反复向 Claude 解释同一件事，那就是一个等待被编写的 Skill。