配置与多文件技能

配置与多文件技能 · 4 分钟

摘要文字记录

本视频介绍了使技能更强大的高级技巧：关键的元数据字段、如何编写可靠触发的描述、预先批准技能所需的工具，以及使用渐进式披露在多个文件中组织更大型技能的方法。您将学习如何在保持技能高效的同时，仍然支持复杂的使用场景。

要点总结

在 Claude Code 中，每个 frontmatter 字段都是可选的，只有 description 是推荐的。allowed-tools 和 model 是两个最有用的附加字段
一个好的描述回答两个问题：这个技能做什么？Claude 应该何时使用它？
allowed-tools 在技能激活期间预先批准所列出的工具，这样 Claude 无需询问即可使用它们，并且它不会将 Claude 限制在这些工具范围内
渐进式披露：将 SKILL.md 保持在 500 行以内，并链接到支持文件（参考资料、脚本、资源），Claude 只在需要时才读取这些文件
脚本在执行时不会将其内容加载到上下文中 —— 只有输出会消耗令牌，从而保持上下文的高效

一个基本的技能只需要名称和描述即可运作，但还有几种高级技巧可以让您的技能在 Claude Code 中更加有效。让我们来了解一下关键字段、描述的最佳实践、工具权限，以及如何构建更大型技能的结构。

技能元数据字段

Agent Skills 开放标准定义了 SKILL.md frontmatter 中的核心字段，而 Claude Code 还添加了许多自己的字段，例如 model。在 Claude Code 中，所有字段都是可选的，只有 description 是推荐的。以下四个字段是一个很好的起点（frontmatter 参考文档列出了其余字段）：

name（可选）—— 标识您的技能。默认为目录名称。如果您将技能上传到 Claude.ai 或 Claude API，则此字段为必填项，并限制为小写字母、数字和连字符，最多 64 个字符。
description（推荐）—— 告诉 Claude 何时使用该技能。如果您将技能上传到 Claude.ai 或 Claude API，则此字段为必填项，上限为 1,024 个字符。这是最重要的字段，因为 Claude 用它来进行匹配。
allowed-tools（可选）—— 预先批准所列出的工具，这样在技能激活期间 Claude 无需请求权限即可使用它们。
model（可选）—— 指定该技能要使用的 Claude 模型。

编写有效的描述

在说明中要明确。如果有人告诉您"你的工作是帮助处理文档"，您不会知道具体该做什么 —— Claude 的思考方式也是一样的。

一个好的描述回答两个问题：

这个技能做什么？
Claude 应该何时使用它？

如果您的技能没有在预期时触发，可以尝试添加更多与您实际表达请求方式相匹配的关键词。描述是 Claude 用来判断某个技能是否相关的依据，所以用词很重要。

使用 allowed-tools 预先批准工具

有时一个技能每次运行时都依赖相同的几个工具，而您不想每次调用都手动批准。allowed-tools 字段会预先批准您列出的工具，这样在调用该技能的整个对话轮次中，Claude 无需权限提示即可使用它们。该授权会在您发送下一条消息时清除。

codebase-onboarding 的 SKILL.md 在编辑器中打开，allowed-tools 那一行被高亮显示，如下方代码块所示。

在这个例子中，allowed-tools 字段被设置为 Read, Grep, Glob, Bash。当此技能处于激活状态时，Claude 可以使用这四个工具而无需请求权限。它不会因此失去对其他任何工具的访问权限：如果技能的指令导致 Claude 编辑或写入文件，这仍会经过您正常的权限设置，如同其他工具调用一样。需要注意的一点是：单独列出 Bash 会普遍预先批准 shell 命令，因此请仅对您信任的技能这样做，或者将其限制为特定模式，例如 Bash(git status *)。

yaml

---
name: codebase-onboarding
description: Helps new developers understand the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

如果您完全省略 allowed-tools，则不会有任何内容被预先批准，Claude 将对每个工具使用其正常的权限模型。要反过来在技能激活期间撤销工具权限，可以使用另一个 Claude Code frontmatter 字段 disallowed-tools，它会从 Claude 可使用的工具集中移除您所列出的工具。

渐进式披露

技能与您的对话共享 Claude 的上下文窗口。当 Claude 激活某个技能时，它会将该 SKILL.md 的内容加载到上下文中。但有时您需要该技能所依赖的参考资料、示例或实用脚本。

把所有内容都塞进一个 2,000 行的文件中会带来两个问题：它占用大量上下文窗口空间，而且维护起来也不轻松。

渐进式披露解决了这个问题。将核心指令保留在 SKILL.md 中，并将详细的参考资料放在单独的文件中，Claude 只在需要时才读取这些文件。

该开放标准建议按以下方式组织您的技能目录：

scripts/ —— 可执行代码
references/ —— 附加文档
assets/ —— 图片、模板或其他数据文件

然后在 SKILL.md 中，链接到这些支持文件，并附上关于何时加载它们的清晰说明：

SKILL.md 的第 2 级和第 3 级部分链接到 architecture-guide.md 和 deep-dive-guide.md，仅在被请求时加载。

在这个例子中，Claude 只有在有人询问系统设计时才会读取 architecture-guide.md。如果他们问的是在哪里添加一个组件，它就永远不会加载那个文件。这就像在上下文窗口中拥有一份目录，而不是整份文档。

一个很好的经验法则是：将 SKILL.md 保持在 500 行以内。如果您超过了这个限制，请考虑是否应该将内容拆分到单独的参考文件中。

高效使用脚本

您技能目录中的脚本可以在不将其内容加载到上下文中的情况下运行。脚本会被执行，只有输出会消耗令牌。在您的 SKILL.md 中需要包含的关键指令是告诉 Claude 运行该脚本，而不是读取它。

这对于以下场景特别有用：

环境验证
需要保持一致性的数据转换
那些用经过测试的代码来执行比用生成的代码更可靠的操作

课程反思

想一想您想要构建的一个涉及多个文件的技能。您会如何组织 SKILL.md 与支持性参考文件之间的结构？
对于您团队共享的技能，您会用 allowed-tools 预先批准哪些工具，又希望 Claude 继续就哪些工具进行询问？

下一步

在下一课中，我们将把技能与其他自定义 Claude Code 的方式 —— CLAUDE.md、子代理、钩子和 MCP 服务器 —— 进行比较，以便您可以为每种情况选择合适的工具。