文件与配置文件决定了 Skills 的加载行为

结论可以先行：Claude Skills 的所有加载行为——包括何时被发现、何时被激活、加载多少上下文——全都由 Skill 目录里的文件名、文件内容和存放位置决定。放错位置、缺失关键文件、YAML 格式错误、路径引用不当，任何一个看似微小的失误，都会让 Skill 默默无闻，仿佛从未存在过。上一章你亲手跑通的 Hello World Skill，正是遵循了严格的目录约定才得以生效；而如果你曾遇到过“明明写了 Skill 却用不上”的情况，问题几乎一定出在文件与配置上。

本文的写作目标是：用一次深度解剖，让你看清每一个文件“决定什么”以及“违背它会怎样”，并在最后给出可操作的场景化组织方案。以下所有事实均来自 2025 年中期 Claude Skills 的官方文档（编号 P0）、公开的社区实践（编号 P2）以及官方技能创建工具的行为，未确认的推断会显式标注。

1. 现象与背景：文件即行为，放对位置就会生效

截至当前调研资料，Claude Skills 生态处于快速迭代期，但已经沉淀出一个高度稳定的底层设计原则：Skill 就是一个文件夹，行为由文件夹内的文件直接定义。只要将该文件夹放到特定目录，宿主环境（Claude Code、Claude App 或 API 侧）就会自动发现，不需要额外的注册、打包或安装步骤。

这种“文件即行为”的哲学，在 Claude Code 中表现得最直观：将 Skill 文件夹复制到 ~/.claude/skills/ 下，Claude Code 在下次启动或对话中就能识别并使用它。团队如果通过 Git 共享自定义 Skills，只需把文件夹扔进项目的 .claude/skills/ 目录即可，这也是目前社区最主流的协作方式。跨平台一致性同样值得关注——无论是在 Claude App 还是 API 中，Skill 都使用同一套文件结构，因此加载与触发规则不会因为环境切换而改变。

理解了“文件位置决定发现”，接下来就要深入到“文件内容决定加载层次”。Claude Skills 实现了一种三层渐进式加载模型，它由文件内容中的结构天然驱动：

来源：调研素材 1（P2）明确描述了这三层加载机制，与社区实践和官方工具生成的结构吻合。SKILL.md 的元数据部分（通常为 YAML frontmatter）始终驻留上下文，用于 Skill 的发现与描述；正文指令在用户请求触及相关能力时才注入；脚本、模板、数据等资源文件则完全遵循“用时再拿”的原则，不会在对话开始时白占 token。这种设计让一个数十 MB 的专业知识包可以安静地躺在硬盘上，而不必担心拖慢常规对话。

接下来，我们就一层层拆开这些关键文件的具体约束。

2. 核心文件解剖：SKILL.md、.claudeignore 与目录约定

2.1 SKILL.md：技能的“身份证”与“说明书”

SKILL.md 是每个 Skill 目录中必须存在的核心文件，它由两部分组成：

• YAML 头（元数据）：位于文件最开头，由 --- 包裹，包含 Skill 的名称、描述、标签等字段。这些信息大约占用 100 tokens，在 Skill 被发现、但尚未被触发时就已经注入模型上下文。宿主系统正是依据这里的 description 来判断“接下来这个 Skill 是否可能帮得上忙”。
• 正文（指令）：YAML 头之后的 Markdown 内容，用于告诉模型具体需要如何完成任务、调用哪些工具、输出什么格式。这部分内容在 Skill 被判定为相关后才加载，长度一般控制在 5000 tokens 以内，以确保不会撑爆上下文窗口。

一个典型的 SKILL.md 结构如下（该结构由官方 skill-creator 工具通过交互自动生成，开发者也可以手动编写）：

---
name: example-skill
description: 用于处理财务报表生成的专业技能
tags: [finance, report]
---
# 报表生成指令
当用户要求生成财务报表时，使用此 Skill。步骤如下：
1. 先确认报表格式。
2. 调用 `scripts/generate_report.py` 生成数据。
3. 输出为整洁的 Markdown 表格。

约束要点：

• YAML 头格式必须严格正确，缩进和缺失的括号都会导致整个 Skill 静默失败（Skill 可能不会出现在可用列表中）。
• description 字段是触发判断的核心，抽象或模糊的描述会让 Skill 难以被自动匹配。
• 正文中的资源引用必须使用相对于 Skill 根目录的路径（例如 scripts/generate_report.py），绝对路径可能因环境不同而无法解析。

从当前调研资料看，官方没有强制规定 YAML 头中哪些字段必填、哪些可选，但 name 和 description 被社区普遍视为最低要求。如果你使用 skill-creator 工具，它会引导你填写这些内容并自动生成合规的 SKILL.md。

2.2 .claudeignore：控制 Skill 可见性的开关

当你在一个父目录下管理多个 Skill 文件夹时，.claudeignore 文件可以决定其中哪些 Skill 被宿主环境看见、哪些被隐藏。它类似于 .gitignore，语法也完全一致：逐行列出要忽略的文件夹名或模式。

例如，在项目的 skills/ 目录旁创建 .claudeignore 文件，内容为：

experimental-skill/
deprecated-*

这样，experimental-skill 文件夹以及所有以 deprecated- 开头的 Skill 目录都不会被 Claude Code 加载。这个设计允许团队在同一个仓库中维护一个较大的 Skill 库，而在不同环境（开发、测试、生产）中通过不同的 .claudeignore 配置来控制谁能被调用，避免了物理删除或复杂开关。

关键纠正（基于此前调研反馈）：.claudeignore 并非放在单个 Skill 目录内部，而是需要放在包含多个 Skill 文件夹的父目录旁边。它可以作用于整个父目录下的 Skill 集合。

2.3 资源文件与路径解析

Skill 目录中除了 SKILL.md，最常见的子目录是 scripts/ 和 resource/，分别存放可执行脚本（如 Python、Shell）和静态资源（如模板、配置文件、图片）。这些资源的加载完全由 SKILL.md 正文中的引用触发，属于资源层，按需加载。

路径解析的硬规则：

• 所有资源路径必须使用相对于 Skill 根目录的方式引用。例如，Skill 放在 sales-report-skill/，其内部的脚本在 sales-report-skill/scripts/gen.py，则在指令中应写 scripts/gen.py，而非 ./SKILL.md 所在位置的绝对路径。
• 对于脚本文件，执行时需要确认宿主环境（如 Claude Code）对该文件的执行权限。如果 Skill 是通过 Git 分享的，你可能需要在部署后手动 chmod +x。
• 资源文件不会被自动预加载，因此即便它们体量庞大，也不会进入静态上下文。但如果指令中引用了不存在的文件，或者在执行时路径解析失败，就会导致 Skill 运行时错误，且失败信息可能不会很直观（常见表现是 Skill 看似正常，但执行步骤被跳过）。

下表对照几种常见错误与症状，可以在排查时快速定位：

3. 运行时配置文件的真实角色——澄清与建议

不少开发者在实际项目中会有一个自然需求：我希望在不同环境（比如开发时用高创造性的参数，生产时用保守的参数）使用不同的模型配置。因此，很容易联想到在 Skill 目录内放置一个 config.yaml 来实现环境区分。本节标题也因此被设为“config.yaml 与运行时参数覆盖”。

然而，截至当前调研的所有官方与社区资料，尚未发现 Claude Skills 规范中定义了 Skill 级别的 config.yaml 文件。也就是说，你自行在 Skill 目录里放置的 config.yaml 很可能不会被任何宿主程序读取，更谈不上覆盖运行参数。Claude Skills 的设计理念是将“如何做”（指令）封装在 Skill 中，而“用什么参数做”（模型温度、max_tokens 等）则交由外部调用方控制，例如在 Claude API 请求中设置，或在 Claude Code 的全局配置中调整。

因此，如果你需要实现环境区分，我给出的可操作建议是：

• 不要在 Skill 目录内创建并依赖一个自行想象的 config.yaml，以免与未来官方规范冲突，或对团队造成误导。
• 改为将环境相关的参数放在外层的调用脚本、环境变量、CI 配置中。例如，开发脚本可以通过 --temperature 0.9 调用 Claude Code，而生产脚本使用 --temperature 0.2——参数传递在技能目录之外完成。
• 如果团队确实希望将参数与技能绑定，可以考虑在 Skill 的 resource/ 目录下放置一个说明文件（如 env_params_guide.md），让指令在运行时根据环境变量 ENV 选择不同策略，但这属于指令逻辑层面的调整，而非文件的直接覆盖。

这一节看似在“否定”一个常见期待，但其价值正在于防止你踩进一个社区中已经出现过的坑：曾经有开发者模仿其他插件体系，在 Skill 里塞了 config.yaml，结果一段时间后官方规范更新导致行为不兼容，团队不得不逐一迁移。

4. 场景化推荐：这样组织文件，加载行为尽在掌控

理论分析之后，我们回到日常工作的三个典型场景，看看如何应用上述规则，确保 Skill 被稳定、可预期地加载。

场景一：单机开发，快速验证

• 将所有 Skill 目录放在 ~/.claude/skills/ 下。
• 每个 Skill 目录至少包含一个语法正确的 SKILL.md，description 清晰且独特。
• 资源路径一律相对路径，脚本在本地先手动执行一遍确保可用。

场景二：团队协作，仓库内维护

• 在项目根目录创建 .claude/skills/，每个成员的本地环境指向该目录。
• 通过 .claudeignore 控制哪些 Skill 对当前分支可见（例如，在 feature 分支忽略未完成的 Skill）。
• 在项目的 CI 流程中增加一步 skill validate（可使用 skill-creator 的校验命令），确保新提交的 Skill 目录结构合规。

场景三：跨环境部署（开发/预发/生产）

• Skill 目录结构完全复用，不在 Skill 内部放置环境相关配置。
• 在外部部署脚本中通过 --model、--temperature 等参数注入环境差异。
• 如果 Skill 需要访问特定环境的资源（例如生产数据库模板），可以用环境变量在指令层做分支，但模板文件本身仍放在 resource/ 下，路径固定。

三个场景的共同底线可以总结成一张清单，供你在每次创建或修改 Skill 时自检：

• [ ] SKILL.md 存在，且 YAML 头格式正确，至少包含 name 和 description。
• [ ] description 描述具体、可区分，不会被其他 Skill 的关键词误触发。
• [ ] 所有脚本、模板等资源皆存在于 Skill 目录内，且引用使用相对路径。
• [ ] 如果父目录下有 .claudeignore，检查其内容符合预期。
• [ ] 没有在 Skill 目录内放置不被官方规范支持的“运行时配置文件”。
• [ ] 在多环境部署时，通过外部参数注入而非 Skill 内部文件来区分策略。

5. 小结：文件的边界就是能力的边界

Claude Skills 的设计很克制：它没有抽象出一套复杂的插件注册机制，没有要求你编写 JSON schema 来描述接口，而是直接让文件目录说话。这种克制的代价是，你必须深入理解每一个文件的职责，否则技能就会沉默。但收益同样巨大——一旦你掌握了本章分析的这些规则，你对 Skill 的控制力将达到像素级别：你能精确决定哪些东西进入上下文、哪些永远按兵不动，也能让团队共享的 Skill 库在不同的环境里随“意”现身。

现在你已经知道“文件与配置文件如何决定加载行为”，但决定加载后的“表现好坏”，则取决于 SKILL.md 里面写的指令是否真的能让 AI 理解。指令是用自然语言写的，它需要一种特殊的约束性表达技巧。这就引出了下一章—— 《SKILL.md 的编写是一门受控的自然语言艺术》。在那里，我们将学习如何用精确又不失弹性的语言，让模型在执行你的 Skill 时像老兵服从命令一样——走对每一步，交出你想要的成果。