虽然已经用了很多 skills，并且也创造过不少 skills 了，但是没有系统地学习和梳理过 skills 的内容。

skills 作为团队经验的沉淀方式，以及 harness 的重要一环，也值得系统学习和梳理。

本文记录 系统学习 skills 的过程。

1. 能力边界

skills 能做的事

  • 给模型记忆：任务步骤、团队规范、输出模板、领域约定，写一次，永久复用。
  • 渐进披露：SKILL.md 放高频要点，细节放 reference.md 等兄弟文件，需要时才 Read 进上下文，节省 token。
  • 配合脚本：在 scripts/ 目录放工具脚本，SKILL.md 里写清楚「运行哪条命令」，代理用终端执行。
  • 配合 MCP：写清楚「何时 call 哪个 MCP tool、参数怎么填、结果怎么整理」，让工作流可复现。

skills 不能做的事

误解 真相
技能是常驻服务 没有运行时，不会自己定时跑，无法监听事件
技能能单独配权限 不能给技能专用 API Key，权限受 Cursor/代理策略控制
脚本自动执行 scripts/只是磁盘文件，需模型主动跑终端命令才执行
技能能登记新 MCP 只能教模型如何用已有MCP，不是把 MCP 打进技能里

skill不是能力的来源，是对已有能力的「使用说明书」。模型还是模型，skill只是告诉它该怎么用手上的工具。

2. skill 的结构

目录布局

技能名/
├── SKILL.md          ← 必须，主指令文件
├── reference.md      ← 可选，skill 中可能引用的具体手册
├── examples.md       ← 可选，示例集合
└── scripts/          ← 可选，工具脚本
    └── helper.sh

SKILL.md frontmatter 字段

---
name: your-skill-name          # 小写字母/数字/连字符，≤ 64 字符
description: >-                # 发现与触发的关键，第三人称，写清 WHAT + WHEN
  做什么。在什么情况下使用。
disable-model-invocation: true # true = 需点名才加载；省略 = 相关对话中更易自动选用
---

3. skill 的运行机制

从形式上来看，skill = 磁盘上的 Markdown 包；「运转」= 模型在需要时把文件读进上下文，然后照做。机制十分简单，也易于理解。

一个 skill 的生命周期共三个阶段：注册、加载、执行。

如何理解“渐进披露”？

为了最大化对话窗口的使用，减少无关上下文，skill 做了渐进披露的设计，即按需加载，在 description 中描述触发条件，关键词触发以后再全量加载 skill 的 body 内容。同时 body 内容不建议超过 500 行，如果 body 中有较细节、长的内容，可以放到 reference.md中通过链接引用。如果有代码运行，可以放在 scripts 文件夹中。

  • 高频、关键的步骤 → 放在 SKILL.md（推荐 ≤ 500 行）
  • 低频、细节的内容 → 放在兄弟文件，正文里写「需要时读 reference.md」
  • 目的：节省上下文 token，让模型在简单任务时不必读完所有内容