最近在做复杂度蛮高的 skill 设计工作。看到阿里云这篇文档，发现其中提到的问题和优化思路，与我在实践中遇到的颇为相似。
链接：https://mp.weixin.qq.com/s/FgGVPw0BOZEu5sH1FdrVoQ

Skill 学习笔记

一、Skill 的基本结构与各部分用处

一个 Skill 本质上是一个文件夹，最简情况只需一个 SKILL.md，复杂时可扩展出 scripts/、references/、assets/ 三个子目录。

1.1 整体目录结构

1
2
3
4
5

my-awesome-skill/
├── SKILL.md          # 灵魂文件：YAML 头 + Markdown 正文
├── scripts/          # 确定性脚本（按需）
├── references/       # 详细参考文档（按需）
└── assets/           # 模板、配置、静态资源（按需）

1.2 SKILL.md = YAML 头 + Markdown 正文

1.3 YAML 头部字段速查

1.4 Markdown 正文的五段式结构

1.5 Skill 的三级渐进式加载机制）

Skill 不是一次性全塞给 Agent 的，而是按需读取：

• L1（始终加载）：所有已安装 Skill 的 name + description —— 用于触发判定
• L2（触发后加载）：被命中 Skill 的 SKILL.md 正文 —— 用于执行
• L3（按需加载）：references/ 中的详细文档、scripts/ 中的脚本 —— 仅在执行步骤明确指出时才读取

二、写法（写作原则与技巧）

2.1 创作前：四步思考的逆向顺序

1

① 触发时机 → ② 输入与输出 → ③ 大致流程（3–7 步骨架） → ④ 细节与规则

2.2 四条核心写作原则

2.3 description 的写法（决定可用性）

description 是 Skill 触发的唯一入口，写法直接决定 Skill 能不能被用上。

核心心法：Agent 倾向”少触发”而非”多触发”，所以 description 要写得积极一些，多列举触发关键词与场景。

2.4 脚本编写的四条建议

• 零依赖优先：脚本尽量用语言标准库
• 多语言 fallback：Python → Node.js → Shell 降级
• 结构化输出：脚本输出 JSON 到 stdout，方便解析
• 明确退出码：成功 0，失败非 0

三、什么时候拆分？拆到哪里？

这是把一个能用的 Skill 升级成可维护 Skill 的关键决策。

3.1 拆分的三个核心信号

3.2 拆到 references/：篇幅与变体管理

触发场景：

• 正文超过 500 行
• 一段详细说明只有少数场景才用得到（比如某个错误码的深度排查）
• Skill 要支持多个变体（不同框架、平台、语言）

目录组织模式（按变体）：

1
2
3
4
5
6

cloud-deploy/
├── SKILL.md                    # 总览 + 变体调度
└── references/
    ├── aws.md
    ├── aliyun.md
    └── gcp.md

正文里只写”如果用户用 AWS，读 references/aws.md”——Agent 只读相关文件，避免无关信息占用上下文。

3.3 拆到 scripts/：确定性下沉

触发场景：

• 操作必须精确执行（签名、加密、格式转换）
• 操作跨平台一致性要求高（不能依赖 LLM 在不同平台复述）
• 操作有副作用（写文件、调 API、改数据库）

关键优势：scripts/ 下的脚本不需要加载到上下文就能直接执行——既省 token 又保证准确性。

3.4 拆到 assets/：静态资源

触发场景：

• 有可复用模板（邮件模板、PR 模板、配置文件）
• 有静态素材（图标、字体、demo 数据）
• 资源在多个步骤中被引用

3.5 拆分决策速查表

3.6 拆分时的常见错误

• ❌ 正文塞太多：把所有错误码、所有变体说明都堆进 SKILL.md，导致正文 800+ 行，触发后上下文被吃光
• ❌ 该用脚本却用 prompt：让 LLM”用某算法计算签名”——跨平台、跨模型行为不一致
• ❌ 拆得太碎：把 50 行的简单内容拆到 references/，反而增加 Agent 调度开销。经验值：单文件 < 100 行的内容不必拆
• ❌ references/ 不命名清楚：导致 Agent 不知道何时该读哪个文件——文件名应明确表达变体或场景

四、一份可复用的写作 Checklist

每写完一个 Skill，按下面九条逐项检查：

• ✅ description 是否列出了 ≥ 5 个触发关键词/场景？
• ✅ 是否做完了”四步思考”，没有跳过 ①②？
• ✅ 工作流步骤是否每条都用祈使句开头？
• ✅ 关键约束是否每条都跟着”因为……”？
• ✅ 正文是否 ≤ 500 行？超出的部分是否拆到 references/？
• ✅ 必须确定执行的逻辑是否下沉到 scripts/？
• ✅ 是否避免了平台特定语法（@、/、!）和硬编码路径？
• ✅ 是否在 ≥ 2 个目标平台跑过冒烟测试，输出一致？
• ✅ description 中是否做了”中性化”，避免出现具体平台名（除非 Skill 本就只服务该平台）？

五、一图记住核心心智模型

1
2
3
4
5
6
7
8
9

┌─────────────────────────────────────────────────────┐
│  L1 (始终加载)：name + description                   │  ← 触发判定
├─────────────────────────────────────────────────────┤
│  L2 (触发后)：SKILL.md 正文（祈使句 + 解释为什么）   │  ← 执行框架
├─────────────────────────────────────────────────────┤
│  L3 (按需)：references/ 详细文档                     │  ← 深度细节
│            scripts/    确定性脚本                    │  ← 精确执行
│            assets/     模板与素材                    │  ← 静态资源
└─────────────────────────────────────────────────────┘

许可协议

本文采用 署名-非商业性使用-相同方式共享 4.0 国际 许可协议，转载请注明出处。

分享文章