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

为什么你需要 Skills？

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

上下文窗口（Context Window）是大语言模型在单次对话中能够处理的最大文本长度，以 token 为单位计量。Token 是模型处理文本的基本单元，一个英文单词通常对应 1-2 个 token，一个中文字符通常对应 1-2 个 token。Claude 的上下文窗口虽然已经扩展到 200K token 级别，但在实际使用中，上下文越长，推理成本越高、响应速度越慢，且模型对中间部分信息的关注度会下降（即"中间遗忘"现象）。因此，精细管理上下文消耗不仅是性能优化，更是确保输出质量的关键策略。

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

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

Skills 的核心机制

语义匹配与自动触发

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

语义匹配示意

语义匹配（Semantic Matching）不同于传统的关键词匹配，它基于文本的语义向量表示来计算相似度。当用户输入请求时，模型会将请求文本和每个 Skill 的描述文本分别编码为高维向量，然后通过余弦相似度等度量方法判断语义接近程度。这意味着即使用户没有使用 Skill 描述中的原始词汇，只要表达的意图相近，就能成功匹配。

这意味着你不需要像 Slash 命令那样手动输入指令。Claude 会识别场景并自动应用。例如，当你说"帮我看看这个 PR"，Claude 就会匹配到描述中包含"代码审查"相关语义的 Skill——虽然"帮我看看"和"代码审查"用词完全不同，但在语义空间中的距离很近。这种机制的优势在于降低了用户的记忆负担，但也要求 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	外部工具集成	提供额外的工具能力

Hooks 采用事件驱动架构（Event-Driven Architecture），在特定生命周期事件发生时自动触发预定义的操作。这一概念在软件工程中有着广泛的应用，从 Git Hooks（pre-commit、post-merge 等）到 React 的生命周期钩子，再到 CI/CD 流水线中的 Webhook。与 Skills 的按需语义匹配不同，Hooks 是确定性触发的——只要事件发生，对应的 Hook 就一定会执行，不存在匹配失败的可能。这使得 Hooks 特别适合那些必须每次都执行的质量保障操作，如代码格式化、lint 检查等。

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 于 2024 年底推出的开放标准协议，旨在为 AI 模型提供与外部数据源和工具交互的统一接口。它采用客户端-服务器架构，AI 应用作为客户端，各种数据源和工具作为服务器，通过标准化的 JSON-RPC 协议通信。MCP 的意义在于解决了 AI 工具集成的碎片化问题——此前每个工具都需要定制化的集成方案，而 MCP 提供了类似 USB 接口的通用标准，使得 Claude 能够访问数据库、API、文件系统等外部资源，极大扩展了其能力边界。

一个典型的配置可能是：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 是 Claude Code 中实现多智能体协作的核心机制。每个 Sub-agent 运行在独立的上下文中，拥有自己的系统提示和工具集，这种隔离设计借鉴了微服务架构的思想——每个 Agent 职责单一、边界清晰，避免了上下文污染。内置的 Explorer（代码探索）、Plan（规划）、Verify（验证）等 Agent 是预定义的专用角色，而自定义 Sub-agent 则允许开发者根据特定工作流创建新的角色。这种架构的权衡在于：隔离带来了安全性和可预测性，但也意味着知识不能自动共享，需要通过显式配置来传递必要的上下文。

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

高级技巧：让 Skills 更高效

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

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

渐进式披露

解决方案是渐进式披露（Progressive Disclosure）：将核心指令放在 skill.md 中，详细参考资料放在独立文件中，Claude 只在需要时才读取。渐进式披露是一种源自人机交互设计领域的经典模式，由 IBM 研究员 John M. Carroll 在 1980 年代提出，其核心思想是先呈现最关键的信息，只在用户需要时才展示更多细节。在 Skills 的场景中，这一理念被巧妙地应用于上下文管理——skill.md 充当"摘要层"，提供 Claude 执行任务所需的核心指令，而详细的参考文档、架构说明等则作为"深度层"按需加载。这种分层架构与软件工程中的懒加载（Lazy Loading）策略异曲同工，都是在资源受限条件下最大化效用的经典方法。

推荐的目录结构：

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

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

脚本执行优于内容加载

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

这一策略的本质是将计算从"上下文内推理"转移到"外部执行"。例如，一个检查项目依赖版本的脚本可能有 200 行代码，如果让 Claude 阅读并理解这些代码，会消耗大量 token 和推理能力；但如果直接执行脚本，Claude 只需要处理几行输出结果（如"Node.js 18.17.0, npm 9.6.7, 所有依赖已安装"），效率提升数十倍。

使用 allowed-tools 限制工具权限

有时你希望某个 Skill 只能读取文件而不能修改。通过 allowed-tools 字段可以实现这一点，限制 Claude 在该 Skill 激活时只能使用指定的工具，适用于安全敏感的工作流。这遵循了安全领域的最小权限原则（Principle of Least Privilege）——每个组件只应获得完成其任务所需的最小权限集合。例如，一个代码审查 Skill 只需要读取文件和查看 git diff 的能力，不应该拥有写入文件或执行 shell 命令的权限，这样即使 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 纳入了版本控制系统（VCS），意味着你可以追踪每个 Skill 的变更历史、进行代码审查、在出现问题时回滚到之前的版本。这与"基础设施即代码（Infrastructure as Code）"的理念一脉相承——将所有配置和知识都以代码形式管理，确保可追溯、可复现、可协作。

对于跨项目的通用 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。

从更宏观的视角来看，Skills 代表了 AI 辅助开发工具从"通用对话"向"领域专精"演进的趋势。正如软件工程中的设计模式将反复出现的解决方案固化为可复用的模板，Skills 将开发者的领域知识和工作流偏好固化为可复用的 AI 行为模式。随着 Skills 生态的成熟，我们可以预见一个由社区驱动的 AI 知识库逐渐形成——每个开发者既是 Skills 的消费者，也是贡献者。