Code Claude 的 Agent Skills 如何使用？一份详细教程指南

在 Claude Code 的工具生态中，Agent Skills（智能体技能）是一项核心功能，它允许用户通过编写特定的 Markdown 文件来扩展 Claude 的能力边界。

Agent Skills 本质上是一组结构化的指令（Prompt 提示词），用于教导 Claude 如何处理特定任务，例如按照团队标准进行代码审查、生成特定格式的提交信息或查询复杂的数据库架构。与通用的系统提示词不同，Agent Skills 具有高度的针对性，并且只有在 Claude 认为当前任务与该 Skills 匹配时才会自动激活。

Agent Skills 的核心概念与存储位置

理解 Agent Skills 的运作方式需要先明确它的物理形式。每一个 Skill 都对应一个独立的目录，而该目录下必须包含一个名为 SKILL.md 的文件。

这个 Markdown 文件包含了 Skills 的元数据和具体指令。Claude 会在启动时扫描特定的目录来发现这些 Skills。根据使用场景的不同，Skills 的存储路径决定了它的生效范围和共享方式。

如果不同位置存在同名的 Skills，Claude 会按照优先级进行覆盖。企业级的 Skills 优先级最高，其次是个人 Skills，接着是项目本地 Skills，最后是插件自带的 Skills。这种层级结构确保了开发者既可以拥有个性化的工作流，也能遵循团队或公司统一的编码规范。

区分 Agent Skills 与其他自定义功能

Claude Code 提供了多种方式来定制 AI 的行为，在开始创建 Skills 之前，有必要理清 Agent Skills 与 Slash commands（斜杠命令）、CLAUDE.md 以及 Subagents（子智能体）之间的区别。Agent Skills 的最大特点是模型调用（Model-invoked），这意味着用户不需要显式输入命令，Claude 会根据对话内容自动判断是否需要启用某个 Skills。

Agent Skills 适合存放那些需要逻辑推理和特定指引的知识，比如如何解释复杂的遗留代码。而 CLAUDE.md 更适合存放硬性的项目规则，例如必须使用严格的 TypeScript 模式。如果目标是连接外部数据源，则应考虑使用 MCP (Model Context Protocol) 服务，Agent Skills 的作用则是告诉 Claude 如何利用这些工具。

创建并加载第一个个人 Skills

为了掌握 Agent Skills 的使用，可以从创建一个简单的个人 Skills 开始。这个示例 Skills 将教导 Claude 在解释代码时必须包含类比和 ASCII 架构图。首先需要在本地系统中创建对应的 Skills 目录。

mkdir -p ~/.claude/skills/explaining-code

也可以在本地项目中创建：

mkdir -p .claude/skills/explaining-code

或者手动创建。

在创建好目录后，必须在其中编写 SKILL.md 文件。该文件由两部分组成：顶部是由三个连字符包裹的 YAML 元数据块，以及下方的内容区。元数据块中的 name 必须与文件夹名称一致，而 description 则是该 Skills 的核心，Claude 依靠这段描述来决定何时激活 Skills。

---
name: explaining-code
description: 用类比和可视化图示来解释代码的工作原理。适用于讲解代码如何运行、介绍代码库结构，或当用户询问“这段代码是怎么工作的？”时使用。
---

当解释代码时，请始终包含以下内容：

1. 从类比开始：将代码逻辑比作日常生活中的事物。
2. 绘制图表：使用 ASCII 艺术图展示流程、结构或关系。
3. 逐步讲解：按步骤说明代码内部发生了什么。
4. 强调易错点：指出常见的误解或潜在的错误。

保持解释语气自然。对于复杂的概念，可以尝试使用多个类比。

完成文件编写后，需要重新启动 Claude Code 以便系统识别新添加的 Skills。为了确认 Skills 已被正确加载，可以向 Claude 询问当前可用的 Skills 列表。

有什么 Skills 可以选？

如果配置正确，返回的列表中会显示 explaining-code 及其对应的描述。

此时打开项目中的任何代码文件并提问“这里的代码是怎么工作的？”，Claude 就会检测到意图与 Skills 描述匹配，随后会请求使用该 Skills，并最终输出带有类比和架构图的解释。

深入理解 Skills 的元数据配置

在 SKILL.md 的 YAML 元数据中，除了 name 和 description 之外，还有其他可选字段用于精细化控制 Skills 的行为。这些配置决定了 Skills 运行时的权限和使用的模型。

元数据中的 description 必须写得具体且包含关键词。如果描述过于笼统，例如只写“帮助处理文档”，Claude 往往无法准确触发 Skills。一个优秀的描述应该包含具体的能力（如“提取 PDF 文本和表格”）以及触发场景（如“当用户提到 PDF、表单或文档提取时”）。

Skills 的自动化激活流程

Agent Skills 的运作遵循发现、激活和执行三个阶段。在 Claude Code 启动阶段，系统仅加载每个 Skills 的名称和描述，这一设计是为了保证启动速度，同时让 Claude 具备识别场景的能力。

当用户的请求在语义上与某个 Skills 的 description 匹配时，Claude 会触发激活流程。在控制台中，用户会看到一个确认提示，询问是否允许加载该 Skills。只有在用户确认后，SKILL.md 的完整指令内容才会被读入到当前的对话上下文中。这种“按需加载”的机制有效地节省了上下文窗口（Context Window）的资源，避免了不相关的指令干扰 Claude 的判断。

在执行阶段，Claude 会严格遵循 Skills 文件中的指令。如果 Skills 中引用了外部文件或脚本，Claude 也会根据需要读取或运行这些资源。

利用渐进式披露优化复杂 Skills

对于复杂的任务，如果将所有文档、代码示例和逻辑都写在 SKILL.md 中，会迅速消耗大量的上下文 Token，导致对话性能下降。此时应当采用渐进式披露（Progressive Disclosure）的设计模式。这种模式建议将核心指令保留在 SKILL.md 中，而将详细的参考资料分散到同目录下的其他 Markdown 文件里。

在这种结构下，SKILL.md 起到了导航枢纽的作用。通过在主文件中添加链接，Claude 可以在需要时才去读取特定的参考文件。

## 附加资源

- 关于完整的 API 细节，请参阅 [reference.md](reference.md)
- 关于详细的使用示例，请参阅 [examples.md](examples.md)

这种多文件结构的优势在于，Claude 只有在处理具体任务并发现主文件中的链接时，才会去加载 reference.md。此外，如果某些逻辑可以通过编写脚本来实现，建议将脚本放入 scripts/ 子目录中。

my-skill/
├── SKILL.md          # 核心指令与导航
├── reference.md      # 详细文档
└── scripts/
    └── validator.py  # 辅助校验脚本

在 SKILL.md 中，可以告知 Claude 直接运行脚本而不是读取脚本源码。脚本运行的结果会返回给对话，而脚本自身的源代码不会占用上下文空间。这对于处理复杂的校验逻辑或数据处理任务非常高效。

限制工具访问以增强安全性

在某些安全敏感或特定任务场景下，用户可能希望限制 Claude 在使用某个 Skills 时的权限。通过 allowed-tools 字段，可以定义一个白名单，明确 Claude 在该 Skills 激活状态下可以直接使用的工具。

---
name: safe-reader
description: Read files without making changes.
allowed-tools: Read, Grep, Glob
---

在上述配置中，当 safe-reader Skills 处于活动状态时，Claude 只能执行读取、搜索和通配符匹配操作。如果 Claude 尝试调用白名单以外的工具（如写入文件或执行 Bash 命令），它必须重新向用户请求授权。这种限制机制非常适合创建只读型的分析 Skills，确保 AI 在处理任务时不会意外修改核心代码。

Skills 在 Subagents 子智能体中的应用

Claude Code 支持创建 Subagents（子智能体） 来处理独立任务。需要注意的是 Subagents 默认不会继承主对话中的 Skills。如果希望某个自定义 Subagents 拥有特定的 Skills，必须在其配置文件中显式声明。

自定义 Subagents 通常定义在 .claude/agents/ 目录下。在其 AGENT.md 文件的元数据中，可以添加 skills 字段来指定预加载的 Skills 列表。

# .claude/agents/code-reviewer/AGENT.md
---
name: code-reviewer
description: Review code for quality and best practices
skills: pr-review, security-check
---

在这个例子中，每当 code-reviewer 子智能体（Subagents）启动时，pr-review 和 security-check 两个 Skills 会自动加载到它的上下文中。这种方式确保了专业化的 Subagents 能够拥有处理特定任务所需的专业指令。

常见问题与调试技巧

在使用 Agent Skills 的过程中，最常见的问题是 Skills 未能按预期触发。这通常是因为 description 字段描述不够清晰，或者关键词未能覆盖用户的提问方式。此时可以尝试重新表述描述内容，使其更贴近自然语言的提问方式。

如果怀疑 Skills 文件本身存在配置错误，可以使用调试模式启动 Claude Code。

claude --debug

在调试模式下，系统会输出 Skills 加载过程中的详细日志，包括 YAML 语法解析错误或路径权限问题。此外，所有的脚本文件必须具备可执行权限，否则 Claude 在尝试调用时会报错。

chmod +x ~/.claude/skills/my-skill/scripts/*.py

如果是通过插件市场安装的 Skills 没有出现，通常是缓存问题导致。可以通过清理插件缓存目录并重新安装插件来解决，这会强制 Claude Code 重新注册该插件下的所有 Skills。

rm -rf ~/.claude/plugins/cache

清理缓存后，再次启动并运行插件安装命令，即可恢复 Skills 的正常加载与识别。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、API 调试、API 设计、API 测试、API Mock、自动化测试等功能于一体的 API 管理工具，Apifox 可以说是开发者提升效率的必备工具之一。

 
如果你正在开发项目需要进行接口调试，不妨试试 Apifox。注册过程非常简单，你可以直接在这里注册使用。

注册成功后可以先看看官方提供的示例项目，这些案例都是经过精心设计的，能帮助你快速了解 Apifox 的主要功能。

 
使用 Apifox 的一大优势是它完全兼容 Postman 和 Swagger 数据格式，如果你之前使用过这些工具，数据导入会非常方便。而且它的界面设计非常友好，即使是第一次接触的新手也能很快上手，快去试试吧！