Anatomy

解剖一个 Skill 包

四个目录，四类职责，一条加载生命周期。搞清楚什么东西该放哪儿，Skill 就写好了一半。

01 · Structure

目录结构

点击左侧任一节点，看它的职责与判断依据。

my-skill/ SKILL.md ← 必需 scripts/ ← 确定性 references/ ← 惰性知识 assets/ ← 原样使用
/

SKILL.md

选中左侧节点查看详情。

02 · Lifecycle

加载生命周期

从一个 Skill 被安装，到它被真正执行，中间发生了六件事。

1

注册扫描

Agent 启动时扫描 skill 目录（用户级 + 项目级），解析每个 SKILL.md 的 frontmatter， 把 name 与 description 载入索引。

启动时一次 · 项目级同名优先于用户级
2

元数据常驻

此后每一轮对话，上下文中只有各个 Skill 的名字与一句话描述。 这是唯一的常驻成本，也是路由的唯一依据。

常驻 · ~50–100 token / 个
3

意图匹配

模型读用户请求，与所有 description 做匹配。这一步的准确率， 完全取决于 description 的写法——它不是一个描述，是一段路由规则。

每轮 · 命中率由 description 决定
4

正文注入

命中后，读取 SKILL.md 正文全文并注入上下文。正文必须自足—— 读完就能启动任务，不需要再到处找信息。

一次性 · 建议 < 500 行
5

资源惰性加载

执行过程中，正文里的条件句指名了才去读 references/；需要时才调 scripts/（通常只读输出，不读源码）；套模板时才取 assets/。

惰性 · 无上限，但必须靠正文指路
6

执行与回写

任务完成后执行「交付前自查」。遇到 Skill 未覆盖的情况，把新的做法回写进 SKILL.md——这是 Skill 越用越准的唯一原因。

闭环 · 不做这一步，Skill 必然腐烂

03 · Frontmatter

元数据字段

字段不在多，在于「被谁读」。只有两个字段是普遍必需的。

字段必需作用写法要点
name必需 唯一标识 小写字母 + 连字符，与目录名一致。用「动作-对象」结构，避开 helper/utils 这类通用词
description必需 触发路由的唯一依据 一句话功能 + 什么时候用 + 至少 3 个真实触发词。30–80 字为宜
agent_created推荐 标记为 AI 创建 允许被自动化工具改写。想让 Skill 支持自我进化就加上
version可选 版本追踪 配合 git 使用，主要给人类看
allowed-tools视平台 限制可用工具 只对只读类 Skill 有意义，能显著降低误操作风险
read_when视平台 补充加载条件 与 description 互补，写更细的加载判据
✓ 好的 description
  • 将会议录音或逐字稿整理为结构化纪要，输出决议、待办（含责任人与截止时间）与风险项。触发词：会议纪要、整理录音、会议记录
  • 将一组图片按文件名顺序合成为带交叉淡入淡出转场的 MP4 幻灯片。触发词：图片转视频、照片幻灯片
  • 重构与简化已有代码，在保持外部行为不变的前提下降低复杂度。当用户要求「简化 / 重构这段代码」时使用
✕ 坏的 description
  • 一个强大的文档处理工具，可以帮助用户完成相关工作
  • 处理会议相关的文本内容
  • 提升代码质量
  • 这是一个用于各种场景的通用助手，功能丰富

04 · Responsibility

什么东西该放哪儿

一条根本原则：让模型做判断，让代码做计算。

S

scripts/ — 锁死确定性

判据：如果这件事每次的结果必须一模一样，就该是脚本。

  • 格式转换（docx → HTML、md → PDF）
  • 数据校验（CSV 字段、JSON schema）
  • 环境探测（盘符、依赖版本、端口占用）
  • 批量操作（重命名、下载、打标签）
  • 加密 / 编码（签名、哈希、base64）
脚本必须：参数从命令行传、失败输出结构化错误并退出非零码、输出 JSON 而非散文、设 timeout。
R

references/ — 知识的惰性抽屉

判据：模型需要知道，但不是每次都需要知道。

切分原则只有一条：按使用场景切，不要按知识章节切。
TEXT按场景切（正确）
references/
├── fill-forms.md      ← 只有填表单时读
├── extract-tables.md  ← 只有抽表格时读
├── ocr-fallback.md    ← 只有遇扫描件时读
└── troubleshooting.md ← 只有报错时读
文件名本身就是路由信息。模型看到 ocr-fallback.md， 结合正文的「若遇到扫描件则读取…」，就能做出正确判断。
A

assets/ — 原样使用的模板

判据：不需要被读进上下文思考，而是被直接拿去用。

  • 输出模板（HTML 报告、pptx 母版、docx 样式）
  • 图片、字体、图标
  • 待填充的样例文件
与 references 的界线：references 会被读完再重写， assets 会被原样拿去用。
M

SKILL.md 正文 — 主干流程

判据：每次执行都必须读的部分，才留在正文。

标准骨架包含五段：
1. 目标 — 一句话说清交付物
2. 流程 — 编号步骤，有明确输入输出
3. 边界与禁忌 — 不要做什么
4. 指路清单 — 什么情况读哪个文件
5. 交付前自查 — 可勾选清单
超过 500 行就说明：本该在 references 里的东西被塞进了正文。

05 · Cost

加载时机全景

理解这张表，就理解了为什么 Skill 能装 100 个而不炸。

层级何时被读取典型体积成本类型
name + description每轮对话，始终在上下文~50–100 token常驻
SKILL.md 正文命中触发后建议 < 500 行一次性
references/*.md正文指名要读时按需惰性
scripts/*需要执行时（通常只读输出）极低惰性
assets/*需要套用模板时通常不读入惰性
一个反直觉的结论：Skill 写得越薄，命中率越高。 把 SKILL.md 当成目录，而不是百科全书。正文只保留主干流程与指路清单， 把一切分支、边界、细节推到 references 里，靠条件句串起来。