Skills与能力封装

Skills 解决的是另一类问题：如果清空了上下文,想让ai重复做过的一套流程,每次都得重复交代做法。

比如让ai整理一篇笔记，麻烦的地方不止”能不能读文件”——还有口吻怎么控制、标题怎么写、代码块要不要注释、截图怎么处理、哪些句式要避开。这些不是一个 API 调用能解决的，更像一套固定工作方式。把这套工作方式写进 SKILL.md，Agent 在需要时再读出来，这就是 Skills 的用处。

一、文件结构

一个 skill 本质上就是一个目录，核心文件是 SKILL.md。

meeting-notes/
  SKILL.md
  references/
    style.md
  scripts/
    export_summary.py
  assets/
    template.md

最小版本只需要 SKILL.md。references/ 放较长的参考材料，scripts/ 放可复用脚本，assets/ 放模板或素材。目录不一定都要有，能用一份 SKILL.md 说清楚的事情，就别硬拆。

SKILL.md 开头有一段 frontmatter，至少写 name 和 description：

---
name: meeting-notes
description: 整理会议记录、行动项和待确认问题时使用。适合把原始会议文字改成清楚的纪要。
---

# 会议纪要整理

把原始会议文字整理成四块：

- 背景
- 结论
- 行动项
- 待确认问题

name 是 skill 名字。description 更关键，Agent 先看到的就是它。描述写得含糊，Agent 就不知道什么时候该用；描述写得太宽，又会在不该触发的时候触发。

二、渐进式读取

Skills 最有意思的地方，是它不会一开始把所有内容都塞进上下文。Agent 通常先看到每个 skill 的名字、描述和路径。任务匹配时，才去读取对应的 SKILL.md。如果 SKILL.md 里还指向 references/，再按需要继续读。

这和把一大段提示词每次都复制进对话里不一样。复制提示词很直观，但多了以后会挤占上下文，而且每次都要手动想“这次该贴哪一段”。Skill 把触发条件和做法放在一个固定位置，Agent 自己先根据描述判断要不要打开。

打个比方，description 像书脊上的标题，SKILL.md 像正文，references/ 像附录。平时书架上只露出标题，真要用到这本书时才翻正文，不会把整柜书都摊在桌上。

三、触发描述

description 写得好不好，会直接影响 skill 能不能被选中。它要写清楚三件事：

• 做什么任务。
• 什么时候触发。
• 什么情况不适合。

比如这个描述就太空：

description: Help with documents.

它没说是写文档、改文档、审查文档，还是导出文档。Agent 只能猜。

稍微具体一点：

description: 整理会议记录、行动项和待确认问题时使用。适合把原始会议文字改成清楚的纪要；不用于写技术教程或项目 README。

这样触发范围就清楚很多。用户说“帮我把会议录音转出来的文字整理成纪要”，这个 skill 很容易匹配；用户说“写一个项目 README”，它就不该出来。

这个地方和工具定义很像。工具的 description 影响模型什么时候调用工具；skill 的 description 影响 Agent 什么时候读取这套做法。

四、正文写法

SKILL.md 里写的是工作方法，不是百科解释。

比如会议纪要 skill，可以写成这样：

# 会议纪要整理

处理原始会议文字时，先保留事实，再整理表达。

输出结构固定为：

- 背景
- 结论
- 行动项
- 待确认问题

行动项要写负责人、动作和时间。如果原文没有负责人，写“负责人待确认”，不要自己补人名。

不要把闲聊都删光。影响决策背景的闲聊可以压成一句，和结论放在一起。

这里没有教 Agent “什么是会议”，也没有写一堆泛泛原则。它记录的是具体做法：结构怎么分，缺字段怎么处理，哪些内容可以压缩，哪些不能乱补。

好的 skill 通常有几个特点：

• 规则少，但每条能落到动作。
• 有输入输出格式。
• 有容易犯错的地方。
• 有必要的示例。

坏的 skill 很像口号：“保持专业、准确、清楚、简洁”。这些词都对，但 Agent 看完还是不知道具体怎么做。

五、参考材料

references/ 适合放长资料。比如写作风格、字段说明、平台操作规范、错误码对照，这些内容如果全塞进 SKILL.md，正文会很长，Agent 每次启用 skill 都要先背一大堆。

更顺的方式是 SKILL.md 只放主流程，并告诉 Agent 什么时候读参考文件：

如果任务涉及纪要口吻，读取 `references/style.md`。
如果任务涉及导出格式，读取 `references/export.md`。

这样就形成了第二层渐进式读取。任务只是整理普通纪要时，不需要打开导出格式；任务要求生成固定模板时，再读 export.md。

这点在大一点的技术 skill 里很有用。比如一个 Kubernetes 排查 skill，SKILL.md 写排查顺序，references/dns.md、references/storage.md、references/ingress.md 分别放细节。遇到 DNS 问题再读 DNS，不用每次把所有排查手册都塞进上下文。

六、脚本和素材

scripts/ 放可执行脚本。不是每个 skill 都需要脚本，只有流程里有稳定、重复、适合程序处理的动作时才放。

比如会议纪要 skill 里，可以放一个导出脚本：

scripts/export_summary.py

它负责把整理好的 Markdown 转成固定 JSON：

{
  "title": "项目例会",
  "actions": [
    {
      "owner": "张三",
      "task": "确认接口字段",
      "due": "2026-06-20"
    }
  ]
}

这种事情让脚本做，比让模型每次手搓格式更稳。模型适合理解和整理，脚本适合校验、转换、批量处理。

assets/ 放模板或素材。比如 template.md 里固定纪要格式，Agent 需要输出会议纪要时直接套模板，不用临时生成结构。

七、MCP与Skills

MCP 和 Skills 经常一起出现，但管的不是同一层。

MCP 管外部连接。比如查数据库、读文件、访问浏览器、调用内部 API，这些都需要一个真正能执行动作的入口。没有工具，Agent 知道流程也做不了事。

Skills 管做事方法。比如拿到日志以后按什么顺序看，报告写哪些字段，错误证据怎么整理，哪些动作需要确认。这些不一定是一个工具能表达的，更像一套工作笔记。

放到待办例子里：

• MCP server 暴露 list_todos、get_todo。
• Skill 记录“整理待办日报时，先列未完成，再按优先级排序，最后列风险项”。

一个负责拿资料，一个负责按固定方式处理资料。两者能叠在一起用，但不要互相替代。把排查步骤硬写成 MCP tool，tool 会变得又大又模糊；把数据库连接写进 skill，Agent 还是没有真正的执行入口。

八、版本边界

Skill 也要控制边界。一个 skill 只处理一类稳定任务，不要写成万能助手。

比如 meeting-notes 只管会议纪要，就不要顺手塞进去：

• 写周报
• 写 README
• 生成 PPT
• 翻译英文合同
• 审查代码

这些任务都和文字有关，但处理方式完全不同。塞在一个 skill 里，description 会越来越宽，正文也会越来越长，最后 Agent 每次读完都不知道重点是什么。

更好的做法是拆成多个 skill。每个 skill 名字清楚、触发条件清楚、正文短一点。这样 Agent 选的时候也更准。

九、一个小例子

一个真正能用的会议纪要 skill，大概可以从这个版本开始：

---
name: meeting-notes
description: 整理会议记录、行动项和待确认问题时使用。适合把原始会议文字改成清楚的纪要；不用于技术教程、README 或周报。
---

# 会议纪要整理

原始会议文字先保留事实，再整理表达。

输出固定为四块：

- 背景
- 结论
- 行动项
- 待确认问题

行动项写成 `负责人 - 动作 - 时间`。原文没有负责人或时间时，写“待确认”，不要自己补。

结论只写已经明确同意的内容。讨论过但没定下来的内容放到“待确认问题”。

如果原文很乱，先按话题合并，再写纪要。不要按发言顺序流水账整理。

这个 skill 没有脚本、没有参考文件，但已经能表达清楚做法。后面如果发现纪要都要导出 JSON，再加 scripts/export_summary.py；如果不同团队有不同口吻，再加 references/style.md。

十、常见问题

Skill 失效时，先看 description。很多问题不是正文写得不够长，而是 Agent 一开始就没选中它。

如果误触发太多，说明描述太宽。比如“处理文档时使用”就太大，写教程、写 README、写纪要都会撞上。

如果总是不触发，说明描述没写到用户会说的话。比如用户常说“会议录音整理一下”，但 description 里只写“formal minutes generation”，匹配就会变差。

如果触发了但做不好，再看正文。正文里有没有输出格式，有没有缺字段处理，有没有反例，有没有告诉 Agent 什么时候读 references。只写“保持清晰专业”，基本等于没写。

Skills 的价值不在于把一句提示词包装得更正式，而是把一套反复使用的做法放到固定位置。能复用、能触发、能按需读取，这三件事做好，skill 才真的有用。