Skill 的结构

一句话理解：一个 Skill 就是一个文件夹。SKILL.md 说明“何时用、怎么做”，scripts/、references/、assets/ 里的东西等真正用到时再去拿。

很多人第一次写 Skill，会把所有内容都堆进一个 SKILL.md：检查规则、历史案例、字段字典、报告模板，一写就是上千行。结果是 Skill 一旦触发就吃掉大量上下文，Agent 反而找不到重点。Skill 的结构设计，本质上是在回答：哪些内容每次都要读，哪些内容只在特定情况下才读，哪些操作根本不该让模型“读”，而应该直接运行。

目录结构

Agent Skills 规范只强制要求一个 SKILL.md，其他目录都是约定俗成的推荐：

三类附属目录的分工：

目录	放什么	Agent 怎么用	对上下文的影响
scripts/	解析、计算、校验等确定性操作	运行它	通常只有输出进入上下文
references/	规则细则、字段字典、领域资料	需要时读取	读到哪个文件，哪个文件才占 Token
assets/	报告模板、配置模板、Schema、示例数据	复制、套用或按需读取	同上

除此之外，规范允许放任何其他文件。命名要能看出内容，比如 references/ticket-categories.md 就比 docs/file1.md 好得多，因为 Agent 是像浏览文件系统一样找东西的。

SKILL.md：元数据加指令

SKILL.md 由两部分组成：开头用 --- 包起来的 YAML 元数据，以及后面的 Markdown 正文。Agent Skills 规范定义的元数据字段如下：

字段	是否必需	约束与用途
name	必需	1–64 个字符；只能用小写字母、数字和连字符；不能以连字符开头或结尾，不能出现连续连字符；必须与所在文件夹同名
description	必需	1–1024 个字符；说明 Skill 做什么、什么时候用，是 Agent 决定是否触发的主要依据
license	可选	许可证名称，或指向随附许可证文件
compatibility	可选	最多 500 个字符；说明环境要求，比如需要联网、需要某个命令行工具。大多数 Skill 不需要
metadata	可选	字符串键值对，存放规范之外的附加信息，比如作者、版本
allowed-tools	可选（实验性）	用空格分隔的预先批准工具列表，各产品支持程度不同

Anthropic 的实现还额外要求：name 不能包含 “anthropic”“claude” 这两个保留词，name 和 description 里都不能出现 XML 标签。

正文没有格式限制，推荐写：分步指令、输入输出示例、常见的边界情况。规范建议正文控制在 500 行以内，约 5000 Token 以内；更长的内容拆到附属文件里。

下面是一个结构完整的例子：

---
name: seo-audit
description: 对网页做站内 SEO 诊断：检查标题、meta description、H1、canonical、robots 与图片 alt，并按团队模板输出问题清单和修复建议。当用户要求检查页面 SEO、排查页面为什么没有收录或排名，或在上线前审查落地页时使用，即使用户没有明确说“SEO”。
license: Proprietary
metadata:
  owner: growth-team
  version: "1.2"
---

# SEO 站内诊断

## 工作流程

1. 对每个页面运行 `scripts/check_page.py <文件路径或 URL>`，拿到结构化结果。
2. 按 `references/rules.md` 的团队口径逐项判定：通过 / 警告 / 错误。
3. 遇到 canonical 指向其他域名、或多个页面互相指向时，先读 `references/canonical-cases.md`。
4. 按 `assets/report-template.md` 输出报告，每个问题都要附上脚本输出中的证据。

## 注意事项

- 装饰性图片的 `alt=""` 是合法写法，不算缺失。
- 脚本返回 error 字段时，在报告里标记“未能检查”，不要猜测结果。

注意几处细节：

• description 同时写了“做什么”和“什么时候用”，还覆盖了用户没说“SEO”这个词的情况。
• 正文只写流程和最容易出错的坑，详细规则放在 references/rules.md。
• 每个附属文件都写清楚了在什么情况下读取，而不是笼统一句“详见 references 目录”。

把这个例子画成图，可以看到元数据负责“被找到”，正文负责按时机把附属文件串起来：

各产品在标准之上加了什么

规范定义的是跨产品通用的核心。各个 Agent 产品会在此基础上增加自己的字段，Claude Code 的扩展尤其多，常用的几项：

Claude Code 字段	作用
disable-model-invocation	设为 true 后，Claude 不会自动加载该 Skill，只能由用户用 /skill-name 调用。适合发布、提交这类有副作用的流程
user-invocable	设为 false 后，该 Skill 从 / 菜单隐藏，只供 Claude 自动使用
when_to_use	补充触发场景，会拼接在 description 后面
allowed-tools	调用该 Skill 的那一轮里免确认使用的工具；用户发出下一条消息后授权即失效
context 与 agent	context: fork 让 Skill 在独立的子 Agent 上下文中运行，agent 指定子 Agent 类型
paths	用 glob 限定只在处理匹配文件时才自动加载
arguments、argument-hint	定义用户调用时传入的参数

另外，在 Claude Code 里 name 可以省略，默认使用文件夹名，文件夹名就是 / 命令名。其他产品也有自己的扩展，比如 Hermes Agent 把分类、标签等信息放在 metadata.hermes 下面。

这里有一个很实际的兼容性问题：Claude Code 文档说明，通过 claude.ai 上传、通过 Skills API 上传，或用官方打包脚本打包时，只接受规范里的六个字段；带着 context: fork 这类 Claude Code 专属字段去上传，会报 “unexpected key” 错误。所以：要跨产品复用的 Skill，元数据尽量只用规范字段；产品专属能力只在确定只在该产品使用时才加。

附属文件的组织原则

• 引用只保留一层：SKILL.md 直接链接到每个参考文件，不要让 A 文件再引用 B 文件、B 再引用 C。Anthropic 的最佳实践提到，嵌套引用时模型可能只预览文件开头，导致信息读不全。
• 长参考文件加目录：超过 100 行的参考文件，在开头放一个内容目录，让 Agent 即使只读了开头也知道全貌。
• 路径用正斜杠、相对 Skill 根目录：写 references/rules.md，不要写 Windows 风格的反斜杠路径。
• 按领域拆分：一个覆盖财务、销售、产品三类数据的分析 Skill，把表结构拆成 references/finance.md、references/sales.md 等文件，问销售问题时就不必读财务文件。
• 说清楚是运行还是阅读：“运行 scripts/check_page.py 提取字段”和“参考 scripts/check_page.py 里的判断逻辑”是两种完全不同的用法，要写明。

第一条原则最容易被忽视，两种引用方式的对比如下：

常见误区

• 把所有资料塞进 SKILL.md。 触发一次就吃掉几千行上下文，而且关键步骤会被淹没。正文写流程和最容易踩的坑，细节放到 references/。
• name 随手写。 SEO_Audit、seo--audit 都不合规，文件夹名和 name 不一致也不合规。不合规的 Skill 在严格校验的产品里可能根本加载不了。
• 在通用 Skill 里混用产品专属字段。 在 Claude Code 里好好的 Skill，传到 claude.ai 或 API 却报错，通常就是这个原因。

设计要点

评审一个 Skill 的结构时，逐项检查：

• name 符合命名规则，并与文件夹同名。
• description 同时写了“做什么”和“什么时候用”，没有超过 1024 个字符。
• 正文在 500 行以内，只包含每次触发都需要的内容。
• 每个附属文件都在正文里被引用，并写明读取或运行的时机。
• 确定性操作用脚本完成，而不是让模型每次重新生成代码。
• 需要跨产品使用时，元数据只用规范字段。

练习

为「销售周报分析」设计一个 Skill 的结构（约 45 分钟）：

1. 画出目录树：哪些内容放进 SKILL.md，哪些放进 references/（比如各区域的数据口径），哪些做成 scripts/（比如环比计算），哪些是 assets/（比如周报模板）。
2. 写出完整的元数据，description 要覆盖“用户说‘看看上周业绩怎么样’但没提‘周报’”的情况。
3. 如果你本地装了 agentskills 仓库提供的参考校验工具 skills-ref，可以运行 skills-ref validate ./sales-weekly-report 检查元数据是否合规。

延伸阅读

• Agent Skills Specification：目录结构、元数据字段与约束的完整定义。
• Extend Claude with skills（Claude Code 文档）：Claude Code 支持的全部元数据字段、存放位置与调用方式。
• Skill authoring best practices：渐进式披露的组织模式与反模式。

下一步

下一课「Skill 如何被发现与加载」会讲 Agent 如何只凭一句 description 判断要不要用某个 Skill，以及三层加载机制在上下文里到底发生了什么。