Skills 从入门到精通

一、那个替我上线的 skill

去年秋天，团队里一位资深工程师要休陪产假。

他有个"身份"——全组公认的代码审查守门员。不是因为职位，是因为他的 review comment 从来不是「这里少了个分号」。他会在 PR 下面写：「这个抽象会不会太早了？现在只有两个调用方」「这个错误信息用户看不懂，它只告诉了开发者发生了什么，没告诉用户该怎么做」「这个改动的影响面不止这三个文件，你改了序列化格式，数据平台的下游任务也会读到」。

这种人休假，团队是有真实焦虑的。

走之前他花了一个下午，把他的 review 判断逻辑做成一个 skill——不是 lint 规则列表，而是几十条带上下文和例子的判断准则：什么时候该抽象、什么时候该重复代码、错误信息的用户视角怎么检查、跨模块改动的 blast radius 怎么评估。装进了 references/ 目录，SKILL.md 编排加载顺序，干完就上线了。

两周后他收到一条消息：「你那个 review skill 发现了一个并发竞争，我差点把它 ship 了。」

他盯着屏幕看了很久。

他不是创造了什么新判断。他只是把他脑子里每次 review 都在跑的那些「如果……那么要小心……」的判断路径，从自己的脑袋里搬出来，放进了一个 AI 能在需要时自动加载的文件里。那些判断在他脑子里是隐性的、每次都要手动的、换个人就带不走的。放进了 skill 之后，它们变成了显性的、自动触发的、谁用谁有的。

他不是在写一个脚本。他是在把他的「判断」封装成一个 skill。

那个瞬间我意识到，skill 的边界比绝大多数人以为的大得多。它不只是「帮我翻译」「帮我查资料」「帮我写日报」。任何可以被说清楚的判断——不管是一次代码审查、一份技术文档的评审、还是一次采访素材的分析——都可以被封装成可以被调用的能力模块。

万物皆 skill。

但这篇文章不是要再给你解释一遍「什么是 skill」。Anthropic 的文档已经说得很清楚了，《图解 Skill》里也有完整的定义。我要说的是：从你今天装上第一个 skill 开始，到你能像搭积木一样设计自己的 skill 系统，这条路怎么走。

我会从我维护的 awesome-skills 收藏库出发——里面有 17 个技能，从深度代码阅读器到项目架构分析器，从 Markdown 文档审查到知识图谱本体管理。也会大量引用《图解 Skill》这本书里的方法论和案例。这本书我在上周四拿到样书，周末两天读完，里面的很多想法直接推动了我对写作工作流的重构。

从哪里开始呢？从一个最朴素的工程直觉说起。

事不过三，三则 skill

这个标题可能会让老程序员会心一笑。软件工程里有个 Rule of Three 原则：第一遍直接实现，第二遍复制粘贴，第三遍重构抽象。我们常说的「事不过三，三则重构」，就是这个意思。

但在 AI 时代，这个规则的终点变了。不是「重构」——是「封装成 skill」。

拿我自己的经历来说。我需要帮孩子处理英语学习材料：拍一张完形填空或阅读理解的错题照片，让 AI 识别错题里的生词，记录下来，然后用这些生词自动生成一篇全新的完形填空或阅读理解。一开始的操作很简单——用 Claude Code 打开一个空文件夹，敲入需求，让它帮我把事搞定。几个回合下来，它写好了 spec，生成了代码。跑通了。完事之后它问了我一句：

「要不要把这个流程总结成一个 skill，方便下次调用？」

我愣了一下。对啊，这是个会重复发生的需求。今天用，下周还用，下个月还用。为什么每次都要从零开始？

后来这个体验反复出现。搭建知识库的时候，下载文章、下载视频、转 Markdown——每个重复操作都变成了 skill。写作流程也是一样：选题 → 调研 → 写初稿 → 审校 → 排版，每个角色一个 skill，最后用一条管道把它们串起来。

规律就摆在那里：遇到重复的工作，就把它总结成 skill。事不过三，三则 skill。

你看，那些经典工程时代的原则和模式，在 AI 时代照样有用。Rule of Three 没变，变的只是重构的终点——过去是抽象成一个函数、一个类、一个模块，现在可以抽象成一个 skill。

一个正在形成的生态

在展开之前，先给不熟悉的读者做一个定位。今天的 Agent Skill 生态，从三个不同尺度上，可以看到三个典型的样本：

个人级：awesome-skills（原力注入）

这是我维护的一个技能合集，目前收录了 17 个独立技能。它们覆盖了三个维度：文档内容处理（doc-reviewer、md-summarizer、md-translator、md-link-checker、web-content-downloader、tech-outline-planner、reference-organizer、editorial-card-designer）、代码与工程辅助（code-reader、project-analyzer、update-submitter、openspec-assistant、agent-skill-reviewer、dir-organizer）、以及架构与知识管理（drawio-designer、pptx-reader、ontology）。每个技能都是一套完整的 SKILL.md + scripts/ + references/ + assets/ 目录，遵循 Anthropic 的 Agent Skills 协议。

设计理念上，awesome-skills 有几个坚持：受众隔离（面向 Agent 的文件全英文，面向人类的交付物中文输出）、渐进式披露（元数据层 → 核心指令层 → 参考层，避免上下文溢出）、以及「生成 SKILL 而非 Agent」的产品定位——让任意通用 Agent 按需加载技能文件，而不是为每个能力创建独立的持久化 Agent。

社区级：baoyu-skills（宝玉）

宝玉的 baoyu-skills 在 GitHub 上获得了 20,000+ star，是目前最知名的开源 Agent Skill 集。它覆盖了三个场景大类：内容生成（文章配图、信息图、幻灯片、封面图）、AI 生成后端、日常效率工具（翻译、YouTube 字幕提取、图片压缩、发布到微信公众号 / 微博 / X）。

你可以用一行命令安装：

   
   
   npx skills add jimliu/baoyu-skills

但宝玉自己在 README 里给了一句很重要的警告——「不要一次性安装全部 skills：每个启用的 skill 都会占用 Agent 的上下文，装得越多，日常调用越容易变慢、变乱。建议先看完整清单，只挑当前工作流真正会用到的几个安装。」这个忠告在后面讨论 Skill 的代价时，我们还会再聊到。

工业级：ECC（Everything Claude Code）

如果说 awesome-skills 是工匠作坊，baoyu-skills 是社区广场，那 ECC 就是工厂。它不是一个 skill，而是一整条生产线：61 个专用 Agent、246 个 Skill、76 个命令、完整的 Hook 系统、MCP 配置管理、跨平台（Claude Code、Codex、Cursor、OpenCode、Gemini、Zed、Copilot）。npm 包 ecc-universal 每周下载量持续增长。

ECC 的意义不在于体量大，而在于它证明了一件事：当 skill 数量突破某个阈值，skill 本身不再是瓶颈——skill 之间的关系才是。 这也正是为什么《图解 Skill》第 5 章花了大量篇幅讲写作工作流的串联，而不是教你多写几个独立 skill。

从一个 review skill 到 ECC，从「替我看代码」到「管弦乐队」，这个生态正在从「单个技能」走向「技能系统」。而我们这篇文章要做的，就是为你画出一条从入门到精通的路径。

二、六种技能面孔——你真的知道自己在调用什么吗？

在开始讲「怎么写」之前，先停一步，问一个更根本的问题：当你调用一个 skill，你到底在要什么？

这个问题看起来简单，但多问几次就会发现不对劲。你调用 /translate，你在要结果——把这段文字变成另一种语言。你调用 /code-review，你也在要结果——指出这段代码的问题。但你要的是同一种东西吗？

翻译是变换。代码审查是判断。把这两个算成同一类，就像把菜刀和温度计归类为「厨房用品」——分类没错，但对你理解工具毫无帮助。

我从自己和社区的实践中，把 skill 按调用意图分成了六类。这不是按「功能」或「工具」这种模棱两可的维度去分，而是按你调用它的时候，你究竟在要什么。

干活型（Doer）——「帮我把这事做了」

最常见的类型。你下指令，它出结果。

在 awesome-skills 中，md-translator 是典型的干活型 skill：给它一个 Markdown 文件，它给你一份翻译稿。web-content-downloader 也是：给它一个 URL，它把网页内容转成干净的 Markdown 文件，附带图片本地化。dir-organizer 还是：给它一个乱糟糟的目录，它输出一份重构方案并自动执行。

干活型 skill 是 skill 生态里的蓝领。不废话，就是干。

但它有一个潜藏的陷阱。当「干活」完全变成黑箱，你怎么知道它做对了？翻译 skill 把「source code」翻成「源码」还是「来源代码」，在大多数场景不是问题——但当你翻译一份技术合同时，这个判断就变得致命。

所以一个设计良好的干活型 skill，不会只输出结果。它会告诉你它做了什么假设、在哪些点上有不确定性。好的干活型 skill 自带把关意识。 md-translator 的 SKILL.md 中就内置了排版规范检查——确保中英文之间留有空格、代码块有注释说明——这些不是翻译本身，但它们是翻译质量的锚。

连接型（Connector）——「帮我够到外面那个东西」

干活是内部变换，连接是打通外部。

MCP integration 装了近 10K 次——帮你接上各种外部服务。web-content-downloader 帮你抓网页内容，reference-organizer 替你访问 arXiv API 和 Crossref API 获取学术元数据。ontology 也是连接者——它不产出面向用户的结果，而是将多个 skill 接入同一份结构化的知识图谱，让不同 skill 之间可以读写共享的实体和关系。

这类 skill 的价值不在于它自己能做什么，而在于 它让你能触达原本够不到的地方。reference-organizer 就是一个好例子：它内置了 arXiv 定制的 Python 解析脚本和 Crossref API 调用逻辑，用户不需要知道这些 API 的鉴权方式、响应格式和限流规则——skill 封装好了接口描述和调用逻辑，Agent 就知道什么时候该调、怎么调、调了之后怎么处理结果。

连接型 skill 在设计上最容易被低估的环节是错误处理。外部服务会挂、会超时、会改 API、会限流。web-content-downloader 的 SKILL.md 中有明确的降级策略：当网页抓取失败时，尝试不同的 reader 工具；当图片下载失败时，保留原始外链而不是静默丢弃。

想事型（Thinker）——「帮我换个角度想」

这类 skill 不给你答案，它给你看问题的方式。

tech-outline-planner 不帮你写文章，它帮你搞清楚「这篇到底想说什么」。它在设计上采用组合叙事结构：外层用 Context-first 风格（背景-问题-方案-权衡）确保宏观逻辑的严密性，内层用 Process narrative 程序化描述确保技术细节的自然衔接。整个过程严格遵循「给定信息优先于新信息」（Given before new）的认知原则。

code-reader 某种程度上也是想事型 skill——它不直接帮你写代码，而是帮你「理解一个你不熟悉的代码库」，然后生成一份 SKILL.md 让你（或 AI）以后能更快上手。

想事型 skill 和干活型刚好相反。干活是减少你的工作量，想事是增加你的清晰度。这两种价值有时候会冲突——你想让 AI 少干点活，但同时又想让它多想想。这就是为什么好的 skill 系统往往把「想」和「干」分给不同的 skill，而不是做一个「又会想又能干」的超级 skill。

《图解 Skill》第 5 章的写作工作流就是一个典型案例：outliner 负责想（生成多个差异化大纲方案），writer 负责干（按选定的大纲写作），两个 skill 各司其职，不互相干扰。

把关型（Gatekeeper）——「帮我检查这事对不对」

它一般是一个流程的最后一道门。代码审查、事实核查、风格检查——它的工作就是说「不行」。

在 awesome-skills 里，doc-reviewer 是把关型 skill 最完整的代表。它把技术文档审查拆成四种独立评审：大纲评审（检查目录与结构逻辑）、内容评审（检查文字准确性与代码质量）、资产与链接评审（校验链接与引用合规）、格式评审（校对纯视觉排版与标点）。四种评审各有一套独立的 references/*-review-rules.md 文件，按需加载，避免单次评审时的上下文膨胀。

md-link-checker 也是把关者：多线程并发扫描 Markdown 文件中的所有链接，验证本地文件路径和外部 URL 的连通性，内置 LRU 缓存和反爬虫重试机制。agent-skill-reviewer 更是把关中的把关——它审查别的 skill 本身是否符合规范。

好的把关者不只说「不行」，它会告诉你为什么，并且在明确指出问题后，支持在用户授权下自动应用修复。doc-reviewer 的四种评审类型，每一种在指出问题后都会给出具体的修改建议——不说笼统的「有问题」，而是精准定位到哪个维度、哪条规则、怎么改。

分身型（Persona）——「帮我借用别人的脑子」

这个类型有点上头。

persona skill 让你模拟特定角色的思维方式。你用乔布斯的 skill 评审产品设计，本质上是在问：「如果乔布斯看到这个，他会怎么骂？」以前你要读一堆传记、访谈、内部邮件，才能勉强「模拟」一个人的思维。现在一个精心构造的 prompt 就能做到七八成。

科技博主「数字生命卡兹克」开源了自己的写作 skill khazix-writer。装上之后，AI 写出来的东西，读着就像他写的——一样的句式节奏、一样的比喻习惯、一样的价值判断倾向。不是抄他的文章，是借他的脑子想。

在 awesome-skills 中，openspec-assistant 也具备一些分身型的特质——它支持架构师、开发、QA 三种角色的协同，每种角色有自己独立的思考方式和关注重点。

分身型 skill 最核心的设计挑战是边界声明。如果一个 skill 声称自己模拟乔布斯，它必须同时声明自己的局限——它没有乔布斯的全部人生经历，它的判断基于公开文本的重构，不是真实人格的复制。这不是免责声明，这是用户正确使用这个工具的前提。

但分身型 skill 的价值不在「像不像」——在于它提供了一个你原本没有的视角。你让乔布斯 skill 评审产品，不是在找正确答案，而是在找被遗漏的问题。它提出的质疑你自己也能想到，但你可能不会往那个方向想。这就是分身型的核心：不是替代思考，是撬动思考。

也正因如此，分身型 skill 是六种类型中最容易被误用的。给它太宽泛的任务（「帮我写一篇乔布斯风格的文章」），输出很容易滑向刻板印象。给它足够具体、有约束的上下文（「这是产品方案，从极简主义、用户体验优先、是否解决了真问题三个角度批评它」），它才真正有价值。好的分身型 skill 需要的不是更多的角色背景描写，而是更精准的视角约束。

调度型（Orchestrator）——「帮我协调其他 skill」

这个类型现在还小，但可能是未来最重要的。

project-analyzer 在 awesome-skills 中是最接近调度型的设计：它协同了模块专家、运维工程师和首席架构师三个角色的多智能体协作模式。它不仅关注代码级别的逻辑——底层调用 code-reader 生成的模块技能文件作为中间产物，上层再由首席架构师汇总代码逻辑和基础设施配置。模块专家扫描代码生成认知技能文件，运维工程师提取构建、测试和部署策略，首席架构师做最终的汇总与一致性校验。

没有调度者的 skill 群只是小提琴独奏。有了调度者，才变成管弦乐队。

《图解 Skill》第 5 章的写作工作流是调度型 skill 最完整的公开案例。宝玉设计的流水线从 content-analyzer（素材分析）开始，经过 outliner（大纲生成）、writer（写作）、article-polish（润色），最后到 article-illustrator（配图）。每个环节的输出是下一个环节的输入，调度者确保数据和上下文在环节之间不丢失。

一个不够 MECE 的分类（但够用）

说实话，这个分类不够 MECE——相互独立、完全穷尽。

比如「把关」和「干活」的边界模糊——code-review 到底是帮我干活还是帮我把关？「连接」和「干活」也有重叠——web-content-downloader 内部是不是也在「连接」外部 API？reference-organizer 是不是同时兼具连接（抓取 API）、干活（格式化输出）、和把关（校验引用格式）三重面孔？

但这些不重要。分类的目的不是穷尽所有可能性，是帮你建立一种直觉：当你有一个想法，你能快速判断它适合变成哪种 skill。

而且你会发现，同一段能力，换个 framing 就是不同的类型。一段代码分析能力，加上「请严格检查并指出问题」就是把关，加上「请用乔布斯的方式评价」就是分身，加上「请重构并输出最佳实践」就是干活。底层能力一样，只是被怎么用不同。skill 的类型不是由它「是什么」决定的，而是由它「被怎么用」决定的。

或者更简单——你甚至不需要判断类型。只要你发现自己第三次重复同一件事，就把它变成 skill。类型只是事后归纳，「事不过三，三则 skill」才是事前行动准则。

三、从格式到设计——为什么写 SKILL.md 不是最难的部分

如果你去翻 Anthropic 的 Agent Skills 文档，或者看网上大多数 Skill 教程，你会发现它们都在讲同一件事：格式。YAML frontmatter 怎么写、allowed-tools 怎么配、description 要多长。这些东西花十分钟就能学会。

但正如 Google Cloud Tech 的文章中指出的：

「随着超过 30 个 Agent 工具（如 Claude Code、Gemini CLI 和 Cursor）采用相同的布局，格式问题实际上已经过时了。真正的挑战在于内容设计。」

规范解释了如何打包一个 Skill，但对如何结构化内部逻辑完全没有指导。一个封装 FastAPI 约定的 Skill 与一个四步文档管道的运作方式完全不同，尽管它们表面的 SKILL.md 文件看起来一模一样。

先看骨架：一个生产级 skill 的结构

在讨论「怎么写」之前，先弄清楚「长什么样」。awesome-skills 里每一个 skill 都遵循同一套目录结构：

   
   
   skill-name/
├── SKILL.md       # 核心指令文件（文件名必须大写）
├── scripts/       # 可执行脚本（Python / Shell）
├── references/    # 按需加载的补充文档
└── assets/        # 静态资源（图片、模板）

但不是所有 skill 都需要四个目录全满。code-reader 只有 SKILL.md 和 references/（存放三个角色的 prompt 模板：技术作者、QA 工程师、初级开发者）。doc-reviewer 也只有 SKILL.md 和 references/（存放四种评审规则文件）。editorial-card-designer 最完整，四个目录全有：SKILL.md 编排流程，scripts/ 放截图和裁剪脚本，references/ 放设计 prompt 和排版骨架，assets/ 放 HTML 模板。

目录是手段，不是目的。缺什么就补什么，不需要的就别建。

SKILL.md 是技能的灵魂。它的开头是一段 YAML frontmatter：

   
   
   ---
name: code-reader
description: 深度阅读陌生代码库并生成可复用的认知技能文件。当用户提供代码仓库路径或URL并要求分析时使用。
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
---

这里面最容易被写坏的是 description。它是 skill 唯一的触发机制——Agent 通过匹配 description 来判断是否应该加载这个 skill。写模糊了，skill 永远触发不了；写太窄了，该触发的时候不触发。

awesome-skills 的公式是：[功能描述] + [触发场景] + [关键词]。看看这个实际例子——md-summarizer 的 description：

分析和总结指定的本地 Markdown 文件，并输出结构化的中文总结。当用户请求总结、分析或提取本地 Markdown 文档信息时调用此技能。

功能清楚（分析和总结 Markdown 文件），场景明确（用户请求总结、分析或提取），关键词（总结、分析、提取）覆盖了用户可能的表达方式。

受众隔离：写给谁的，就用谁的语言

awesome-skills 里有一条贯穿始终的原则叫受众隔离。

面向 Agent 的文件（SKILL.md、提示词模板）全部用英文写——因为大语言模型在英文指令上的遵循精度显著高于中文。面向人类读者的交付物（分析报告、生成文档）全部用中文输出，格式上遵循中文排版规范（中英文之间加空格）。

这听起来像一个细节，但影响比你以为的大得多。设想一个场景：你的 SKILL.md 用中英混杂写，前半段中文描述业务逻辑，后半段英文写技术指令。Agent 需要在两种语言的推理模式之间频繁切换，指令遵循的稳定性会打折。

不过这个规则有例外。awesome-skills 里的 dir-organizer 和 doc-reviewer，它们的 SKILL.md 就是中文的。原因是它们的操作对象是中文文档标准和中文目录规划——涉及到大量中文特有的概念（比如「顿号」「书名号」「标题层级」），用英文反而会丢失精度。

规则是为目的服务的。受众隔离的目的是最大化指令精度，不是遵循教条。

渐进式披露：skill 的「不要一口气全说」原则

每个启用中的 skill 都会占用 Agent 的上下文窗口。这就像一个有限的背包——每装一件东西就要挤掉另一件。如果你把参考文档、示例代码、错误处理指南全部塞进 SKILL.md 正文，Agent 很可能还没读到核心指令就已经被无关信息填满了。

awesome-skills 的做法是三层加载：

1. 1. 元数据层（始终加载）：只包含 skill 的 name 和 description。Agent 扫一眼就知道这个 skill 是干什么的。
2. 2. 核心指令层（触发时加载）：一旦 Agent 判定需要这个 skill，完整加载 SKILL.md 的正文——执行步骤、约束条件、输出格式。
3. 3. 参考层（按需加载）：references/ 目录下的文件，只有在 Agent 真正需要时才读。

这三层合在一起，你在 skill 目录放了 50KB 的参考文档，但 Agent 日常只背着 200 字节的元数据。只有当它确实要用这个 skill 时，才会逐步打开后续的内容。

doc-reviewer 是渐进式披露的绝佳示例。它的 references/ 下有四个文件——outline-review-rules.md、content-review-rules.md、assets-review-rules.md、format-review-rules.md。当用户要求「检查这篇文章的内容准确性」时，Agent 只加载 content-review-rules.md，其他三份文件保持关闭。四个文件加起来可能有几十 KB，但 Agent 当前只需要其中一份。

《图解 Skill》里宝玉花了很大篇幅讲这个设计，书中术语叫「渐进式披露」（progressive disclosure）。他又进一步细分了三个层级所对应的 token 预算：Level 1（frontmatter）30–100 tokens，Level 2（正文）200–5,000 tokens，Level 3（辅助资产）无上限。这个量化标准在实操中非常有用——当你写 SKILL.md 正文时，时刻记着「5,000 tokens 是上限」，自然就会想哪些内容是必不可少的、哪些可以移到 references 里。

《图解 Skill》里的设计方法论

写到这儿，需要正式介绍一下《图解 Skill》这本书。

书名全称是《图解 Skill —— AI 提效实战指南》，作者宝玉。书中的配图全部由他自己开发和迭代的 book-illustrator skill 生成——这本身就是一个「用 skill 写一本关于 skill 的书」的闭环。

书的结构是一层一层往上走的：

• • 第 1–2 章：Skill 是什么，为什么需要 Skill——教你建立心智模型。如果你完全没接触过 Agent Skill，这两章读完就能理解它和传统编程有什么区别。
• • 第 3 章：从零写一个 Skill 的完整流程——环境搭建、编写、测试、发布。你会跟着操作把一个 idea 变成实际可用的 skill。
• • 第 4 章：提示词工程与 Skill 的结合——怎么写才能让 Agent 稳定执行。这是全书最「硬」的部分，涉及到 prompt 结构设计、边界条件处理、防退化策略。
• • 第 5 章：写作工作流的完整案例。从素材分析到文章配图，8 个 skill 模板的简化版与完整版对照。这一章读完，你对 skill 的理解会从「一个工具」切换到「一个系统」。
• • 第 6–7 章：进阶场景——数据分析 skill 的三次迭代、访谈整理工作流。

我在读到第 5 章的示例之后，当天晚上就把自己的写作 skill 工作流做了重构。不是因为书里教了什么新技术，而是它给了你一个参照系——让你终于能回答「我写的这个 skill 到底够不够好」。

awesome-skills 的工程补丁

《图解 Skill》教的是「怎么把一件事做成 skill」，而 awesome-skills 的工程实践补充了一个同样重要的问题：「怎么确保 skill 不退步」。

code-reader 是 awesome-skills 里最复杂的一个 skill。它的设计引入了三重智能体协作模式：

• • 技术作者：阅读代码，写技能文档
• • QA 工程师：根据技能文档出测试题
• • 初级开发者：只看技能文档（不看源代码）来解答测试题——这是一场「闭卷考试」

如果初级开发者的回答和源代码中的实际情况不一致，说明技能文档写错了或者写漏了。QA 工程师把反馈发给技术作者，修改文档，再出一轮题。循环直到闭卷考试通过。

这个设计解决了一个根深蒂固的问题：大多数代码总结都是浅尝辄止的。 你让 AI 「帮我看看这个项目」，它输出一份看起来有道理的报告，但你没法知道哪些描述是准确的、哪些是它脑补的。三重智能体 + 闭卷考试，本质上是用对抗性验证来保证文档质量的底线。三个角色的 prompt 分别存储在 code-reader/references/ 下的三个独立文件中：tech-writer-prompt.md、qa-engineer-prompt.md、junior-dev-prompt.md——每个角色只能拿到自己该看到的上下文，这种信息隔离本身就是防脑补的机制。

project-analyzer 在 code-reader 的基础上再扩一层：它不仅看代码逻辑，还解析构建、测试和部署配置。最终输出的《项目架构深度分析报告》中，系统架构与核心模块深度解析占 70% 的篇幅，项目全局摘要、质量与性能评估、二次开发指南占 30%。

这个 70/30 分配是有意为之的。大多数 AI 生成的「项目分析」恰好相反——70% 是泛泛而谈的摘要，30% 才是真正有信息量的内容。好的分析报告应该让读者在 70% 的篇幅里学到新东西，而不是在 70% 的篇幅里确认已知信息。

四、五种设计模式——从抄技能到设计技能

知道怎么写 SKILL.md，你还只是「会写 skill」。能从零设计一个 skill，才是「会设计 skill」。

Google Cloud Tech 团队在分析生态中的 Skill 构建方式后，归纳了五种常见的设计模式。这里我结合 awesome-skills 中 17 个技能的实际实现、《图解 Skill》和 baoyu-skills 中的案例，逐一拆解它们的适用场景和设计要点。

模式一：工具包装器（Tool Wrapper）

这是最简单的起点。它解决一个很具体的问题：你不想把某个库的全部文档塞进系统提示词里，但你又希望 Agent 在用到这个库时能准确遵循约定。

做法很简单：SKILL.md 里定义触发条件（通常是特定库或框架的关键词），当 Agent 识别到用户正在使用该技术时，动态加载 references/ 下的约定文档。

   
   
   ---
name: api-expert
description: FastAPI 开发最佳实践和约定。用于构建、审查或调试 FastAPI 应用、REST API 或 Pydantic 模型。
---

你是 FastAPI 开发专家。

## 审查代码时
1. 加载 'references/conventions.md' 获取完整约定列表
2. 根据每条约定检查用户代码
3. 对每个违规，引用具体规则并建议修复

这个模式的精髓在于「不打扰」。平时 Agent 不会加载 FastAPI 的约定，只有在用户真正写或审 FastAPI 代码时才会触发。按需加载优于全量记忆——这是 Agent Skill 和传统系统提示词最本质的差别。

在 awesome-skills 中，md-translator 的设计逻辑也类似：平时不加载翻译规则，只有当用户要求翻译 Markdown 文档时才触发。reference-organizer 也符合这个模式——它内部的参考文献格式化规则（GB/T 7714、APA、IEEE）只在用户请求整理参考文献时才加载。

工具包装器的关键设计决策是：什么放在 SKILL.md 正文里始终加载，什么放在 references/ 里按需加载。 好的判断标准是：正文里只放编排逻辑（「什么时候读哪个文件」），具体的规则、约定、模板全放 references。

模式二：生成器（Generator）

如果你苦于 Agent 每次运行生成不同的文档结构，生成器模式通过编排「模板 + 样式指南 + 填空」来解决一致性问题。

结构上，生成器型 skill 利用两个子目录：assets/ 放输出模板，references/ 放样式指南。SKILL.md 不包含具体的布局或语法规则，只负责编排：

   
   
   步骤 1：加载 'references/style-guide.md' 获取语调与格式规则
步骤 2：加载 'assets/report-template.md' 获取输出结构
步骤 3：询问用户缺失的变量
步骤 4：按模板填充内容，逐段对照样式指南

在 awesome-skills 中，editorial-card-designer 和 drawio-designer 是生成器模式的最佳体现。前者知道 8 种固定比例的 HTML 信息卡模板（3:4、4:3、1:1、16:9、9:16、2.35:1、3:1、5:2），每种比例在 references/recommended-skeletons.md 中有可复用的版式骨架（Hero + Stats + 主次模块 + 页脚条带等）；后者能直接操作 draw.io 的底层 XML 生成架构图，内置 AWS 官方图标和配色规范。

它们都是「你有模板，AI 来填」的模式。模板约束了结构，Agent 填内容——结构的一致性和内容的灵活性同时实现。

模式三：管道（Pipeline）

管道模式是最能体现 skill 系统化价值的设计。前一步的输出，是下一步的输入，像流水线一样依次流转。

《图解 Skill》第 5 章的写作工作流是管道模式的最佳教学案例：

   
   
   content-analyzer → outliner → writer → article-polish → article-illustrator
    (素材分析)      (大纲)     (写作)      (润色)            (配图)

管道里每一个环节是独立的 skill，它们通过「输出 → 输入」的约定衔接，而不是被一个巨大的「写作超级 skill」捆绑。这种设计的好处是灵活——比如你不是每次都配图，那就把 article-illustrator 去掉；你想在润色之前加一道事实核查，就在 writer 和 article-polish 之间插入一个把关型 skill。

在 awesome-skills 中，管道的理念体现在 project-analyzer 的设计上：它底层调用 code-reader 生成的模块技能文件作为中间产物，上层再由架构师角色汇总。这不是一个「大一统」的 skill，而是 layer 在 layer 之上的组装。openspec-assistant 也体现了管道理念——架构师写 Spec、开发写代码、QA 写测试，三者按序流转。

管道模式的核心挑战不是「怎么连」，而是「怎么确保上一个环节的输出够好，下一个环节不会在垃圾上建大厦」。这就需要每个环节自带把关——code-reader 的三重智能体 + 闭卷考试是这一关的工程化实现，doc-reviewer 的四种独立评审也是。

模式四：多智能体（Multi-Agent）

多智能体模式是当任务超过单个 Agent 的认知负荷时，把它拆给多个角色并行处理。

code-reader 的「技术作者 + QA + 初级开发者」就是三智能体协作。gstack 项目把软件工程拆成 CEO、工程经理、设计师、QA、发布工程师等 21 个角色，每个角色一个 skill，是更大尺度的多智能体实践。

但多智能体模式有一个重要陷阱，宝玉在《图解 Skill》里讲得很坦率。他的 adversarial-polish 技能设计上依赖「批评者 → 改写者 → 综合者 → 盲评者」四个角色的对抗循环，理论上像学术同行评审一样打磨稿件。但在实际使用中，当前主流平台不支持真正的角色之间的上下文隔离，导致效果远不如预期。他在技能说明里直接标明了：

「仅供学习研究用，不具备实际使用价值——保留在此仅供读者理解角色隔离与对抗式推理的设计思路。」

这个诚实的态度比一个「一切完美」的宣传有价值得多。它告诉你一个关键的工程判断：在设计多智能体 skill 之前，先确认你的运行环境是否真的支持角色隔离。 如果不支持，四个角色混在一个上下文中互相「对抗」，等于一个人分饰四角跟自己吵架——没有真正的信息差，对抗就沦为形式。

awesome-skills 中对这个问题的应对策略是 sub-agent spawn：code-reader 的三个角色分别作为独立的 sub-agent 生成，各自只能看到分配给自己的 prompt（分别存储在三个独立的 references/*-prompt.md 文件中），互不可见。主 Agent 只负责调度和收集结果，不做实际的分析工作。这是在平台层面的真相隔离无法实现时，在工程层面做的最好替代。

模式五：自主循环（Autonomous Loop）

这是五种模式里最激进的。你给 skill 一个目标和一个收敛条件，它自己反复执行直到满足条件。

《图解 Skill》第 7 章的数据分析 skill 是一个典型。宝玉展示了同一个 skill 的三个迭代版本（v1 → v2 → v3）。v1 只是简单的「分析 Excel 并输出结论」；v2 加入了三阶段分析法（描述性统计 → 相关性分析 → 深度解读）；v3 引入了自动可视化和 HTML 报告生成。这三版不是一口气设计出来的，而是在反复使用中发现不足、逐步修出来的。

在 awesome-skills 中，code-reader 的闭卷考试循环就是自主循环模式的一个子单元：QA 出题 → 初级开发者闭卷作答 → 对比源码验证 → 反馈修正 → 再出一轮题。这个盒子里的循环直到所有关键知识点通过验证才终止。

自主循环模式的核心约束不复杂：循环终止条件必须明确，且必须有最大迭代次数限制。 否则你的 skill 会一直优化一个已经不需要优化的结果，白白消耗 token 和时间。code-reader 中的循环条件是「闭卷考试通过（所有关键知识点的回答与源码一致）」，并且有明确的轮次上限，超过上限则标记为「无法收敛」并报告未通过的知识点。

五、从 Skill 到 Skill Suite——当你的技能需要体系化

skill 少的时候不需要调度者，就像一个人吃饭不需要项目经理。但当你的工作流节点从 5 个变成 50 个，你就会撞到一面叫「复杂度」的墙。

你的 skill 群该升级了吗？

什么时候你的 skill 不再只是「一堆 skill」，而需要一个体系？我的经验是四个信号：

1. 1. 数量触发：候选项超过 10 个，且合计 token 超过了单个 SKILL.md 正文的建议上限（约 5,000 tokens）。
2. 2. 多入口：你能通过不止一种路径进入这个能力集合——比如同一个代码库，你有时想「读某个模块」(code-reader)，有时想「分析整个项目」(project-analyzer)，有时想「只查依赖关系」。
3. 3. 依赖图不连通：你的几个 skill 之间没有调用关系，但它们共享数据和上下文——没有调度者，上下文就要靠你手动传递。
4. 4. 工具集发散：不同 skill 需要不同的 allowed-tools——有的只需要读写文件（md-summarizer），有的需要执行命令（drawio-designer 需要 headless Chrome），有的需要网络访问（web-content-downloader）。把它们的权限混在一起是安全隐患。

这四个信号中，任意一个响了就应该考虑套件化。

套件关系的四种类型

一个 Skill Suite 不是简单的文件堆叠。技能之间有四种关系：

• • depends-on：A 的输出是 B 的必要输入。比如在写作工作流中，outliner 依赖 content-analyzer 的分析结果。
• • composes：A 的逻辑上由 B、C、D 组合而成。比如 project-analyzer 组合了 code-reader 的代码分析能力和基础设施分析能力。
• • bundled-with：A 和 B 经常一起用，但不是强依赖关系。比如 md-translator 和 md-summarizer——你用翻译器的时候不一定要总结，但它们经常出现在同一条文档处理链上。
• • requires-output-from：比 depends-on 更强的时序约束。A 必须等 B 完全完成后才能开始，不能用中间结果。

在 awesome-skills 中，code-reader 和 project-analyzer 之间是 composes 关系——后者在前者的基础上扩展。md-link-checker 和 doc-reviewer 之间是 bundled-with 关系——在文档发布前经常一起跑，但各自独立工作。

质量保障：你的 skill 不会在迭代中退化吗？

这是 skills 从入门到精通的分水岭问题。

初学者只关心「我的 skill 能跑吗」——通了就收工。有经验的 skill 作者会再往前想一步：「下次我改了这个 skill，它还会继续管用吗？」

awesome-skills 在 unit-test/ 下建立了双重测试体系：

Tier 1：静态检查（无 LLM，CI 必须通过）：

   
   
   python3 ./unit-test/tests/run_static.py <skill-name>

它检查的东西很机械但很关键：链接格式是否正确（只允许 http:// 或 https://，锚点 # 例外）、图片路径是否有效（禁止绝对路径和外部链接）、命名是否规范（小写 + 中划线，不含空格与下划线）、有没有不小心把敏感信息（API key 等）写进了文件。这些检查不需要调用大模型，几秒钟跑完，CI 里挂了就拦截。

Tier 2：端到端评估（需要 LLM）：

   
   
   SKILL=<skill-name> bash ./unit-test/opencode-skill-eval.sh all

这一步会把 skill 交给真实的 Agent 环境（OpenCode CLI）去跑，记录完整的 JSONL 事件追踪——调用了哪些工具、产生了什么输出、消耗了多少 token。然后再用行为断言脚本去验证输出是否符合预期。评估维度包括三个：结果（产出是否可用、格式是否保留）、过程（是否遵循预期步骤，如先拷贝到沙盒再修改，防止主干污染）、效率（Token 消耗是否合理，有没有无谓的循环）。

目前 doc-reviewer 和 md-translator 已经有完整的静态检查和端到端测试覆盖。其他 skill 的静态检查在运行时会打印警告并退出，端到端测试则需要为每个 skill 编写对应的行为断言脚本。

测试的投入不是「锦上添花」，而是防止信任崩塌。一个用户装了你写的 skill，用了三次，两次结果不对——他不会去想「这个 skill 可能刚刚改坏了」，他只会想「这个 skill 不好用」然后卸载。Skill 的信用是脆弱的，自动化验证是它唯一的锚。

六、边界与代价——什么时候不该做 Skill

前面五章都在讲「怎么做」。这一章要讲「什么时候不做」。

上下文是零和的

每个启用的 skill 都会占用 Agent 的上下文窗口。这个窗口是有限的——装了一个 skill，就挤掉了一部分原本可以用来理解用户意图的空间。

宝玉在 baoyu-skills 的 README 里写了这么一句话，我认为是所有 skill 使用者都应该刻在脑子里的：

「不要一次性安装全部 skills：每个启用的 skill 都会占用 Agent 的上下文，装得越多，日常调用越容易变慢、变乱。建议先看完整清单，只挑当前工作流真正会用到的几个安装。」

这跟软件工程里的「依赖最小化」原则完全一致。你装了一个 npm 包，它占的是磁盘空间和构建时间；你启用了一个 skill，它占的是每次对话都和你竞争窗口的认知预算。

渐进式披露改善了这个问题——skill 的元数据层很轻量。但它不是银弹。当 Agent 需要扫描 20 个 skill 的 description 来决定该不该触发某个 skill 时，这个扫描本身就已经在消耗注意力了。

awesome-skills 的实践中，日常激活的 skill 通常不超过 5 个——根据当前的工作场景动态启用和禁用。这是对认知预算的主动管理，而不是被动接受。

Skill 不是 Agent

这是一个经常被混淆的概念。

Skill 是能力模块。Agent 是执行主体。Skill 不会自己做任何事——它被 Agent 加载后，成为 Agent 当前能力的一部分。

awesome-skills 的核心设计选择之一，就是「生成 SKILL 而非 Agent」。code-reader 和 project-analyzer 的输出是 SKILL.md 文件，不是持久化的 Agent 角色。这样任何通用 Agent 都可以按需加载这些文件来获得特定模块的知识，而不是为每个模块创建一个永久存在的 Agent。

这个选择的背后逻辑很简单：Agent 多了是负担，Skill 多了只是选项。 20 个 Agent 同时在你的系统里运行，你光协调它们就要花掉大量 token 和精力。20 个 Skill 安静地躺在磁盘上，只有被调用时才进入上下文——这是完全不同的资源消耗模型。

《图解 Skill》里也用了一章的篇幅来区分这两个概念。宝玉的观点和 awesome-skills 的设计选择是一致的：用 Skill 做能力封装，用 Agent 做运行时调度，别把两者混在一起。

「事不过三」的陷阱

「事不过三，三则 skill」是我在这篇文章一开头就提出的行动准则。但它有适用边界。

不是所有重复操作都值得变成 skill。你要做一个快速的成本判断：

重复频率 × 每次节省的时间 > 维护成本？

如果一个操作你每周做一次，每次省五分钟，但它的逻辑每周都在变——那做成 skill 的维护成本（反复改 SKILL.md、调整执行步骤、更新参考文档）可能比省下来的时间还多。

有些事写成脚本就够了。你不需要为每个 ffmpeg 命令写一个 skill——写一个带参数的 shell 脚本，把它放在 scripts/ 目录下，你口头调用就行了。Skill 的价值不在于「替代一切手工操作」，而在于「封装那些需要判断和上下文才能做对的事」。

什么是需要判断和上下文的事？判断一段代码该不该重构——需要理解代码意图、对比设计方案、评估改动风险。这是 skill 该干的事。什么是脚本就能干的事？把一个目录里的所有 PNG 转成 WebP——一行 ffmpeg 命令，没歧义。这是脚本该干的事。

把脚本能解决的事写成 skill，是过度工程。把需要判断的事写成脚本，是削足适履。分清边界，才是真正的「精通」。

七、你的第一个 Skill 系统

我们绕了一大圈，从一个 review skill 讲到设计模式讲到测试讲到边界。现在回到最开始的问题：你，怎么开始？

第一步：盘点你本周的重复操作

打开你的终端历史记录，或者翻一下这周你在 AI 助手里重复输入过的指令。有没有什么你说了三次以上的话？

如果有，那就是你的 skill 种子。

第二步：从工具包装器开始

不要一上来就设计管道或多智能体。从最简单的工具包装器模式入手——把你团队的一个编码规范或者你常用的一个框架约定写成一个 skill。触发条件是「当用户使用框架 X」，内容是一套加载在 references/ 里的约定文档。

这个 skill 只需要两个文件：SKILL.md 和 references/conventions.md。十分钟写完，装上去试一次。体验一下「Agent 在你没特别提示的情况下，自动遵循了你的约定」的感觉。

这种感觉就是 skill 的核心魅力——不是「你告诉 AI 做什么」，而是「AI 在需要的时候自动知道怎么做」。

第三步：用别人的 skill，然后改它

不要从零写所有东西。装上 baoyu-skills，挑两三个你真正会用的。研究 awesome-skills 中的 code-reader 和 doc-reviewer 的 SKILL.md 是怎么写的。不是看格式——格式你已经知道了——是看它的执行步骤是怎么切割的、什么情况它说「我做不到」、它把什么内容放在 references 里而没有堆在正文里。

看几个具体的例子：

• • code-reader/SKILL.md：看它如何编排三个角色的协作，看它如何把技术作者、QA、初级开发者的 prompt 拆成三个独立文件。
• • doc-reviewer/SKILL.md：看它如何将审查拆成四种独立评审，每种规则独立存储、按需加载。
• • editorial-card-designer/SKILL.md：看它如何使用 scripts/ 和 assets/ 来编排 html → screenshot → trim 的完整流程。

然后改。把你用着不顺的地方改掉。把一个通用 skill 改成适配你自己的工作流。改的过程就是你真正理解 skill 设计的过程。

推荐阅读顺序

如果你要读《图解 Skill》，我建议的顺序是：

1. 1. 第 1–2 章先读，建立认知基础——Skill 是什么、为什么需要。不用做笔记，读完理解就行。
2. 2. 第 3–4 章跟着操作。读完第 3 章你应该已经写出了自己的第一个 skill。第 4 章的提示词工程部分比较硬，可能要多读一遍。
3. 3. 第 5 章是最值得精读的一章。看完宝玉的写作工作流设计之后，对着你自己的日常工作流，画一张图：哪一步产生什么输出、哪一步依赖什么输入、有没有重复的环节可以合并。
4. 4. 第 7 章看数据分析 skill 的 v1→v2→v3 演化。它是「事不过三」最直观的展示。你会发现，那些最终看起来很成熟的 skill，最初也是一坨勉强能跑的 prompt。
5. 5. 附录什么时候翻都行。附录 D 有四个完整技能的 SKILL.md 全文，是你自己设计 skill 时最好的参考模板。

资源索引

• • 《图解 Skill —— AI 提效实战指南》（宝玉著）：京东 u.jd.com/RDY9YwC / 图灵电子书 ituring.com.cn/book/3616 / 配套仓库 github.com/JimLiu/Illustrated-Agent-Skills
• • awesome-skills（原力注入）：github.com/ForceInjection/awesome-skills — 17 个可复用的 Agent Skill，覆盖文档处理、代码工程辅助、架构与知识管理三大维度。带完整测试框架（静态检查 + 端到端评估）、五种设计模式深度解析（Google Cloud Tech 文章翻译）、以及 gstack/superpowers 项目深度解析。
• • baoyu-skills（宝玉开源技能集）：github.com/JimLiu/baoyu-skills — 20,000+ star，涵盖内容生成、AI 后端、日常效率三类场景。npx skills add jimliu/baoyu-skills 一键安装。
• • ECC（Everything Claude Code）：生产级多 Agent 系统，61 个 Agent + 246 个 Skill + 76 个命令。npm i ecc-universal。如果你想看「skill 工业化之后长什么样」，这是最完整的样本。
• • Repo2Skill：github.com/ForceInjection/Repo2Skill — 把任意 Git 仓库自动转化为 Agent Skill 的工具。pip install -e . 后 repo2skill <path> -o ./output。如果你想「自动化 skill 生产」，这是目前最成熟的方案。
• • CUDA Code Skill：github.com/ForceInjection/cuda-code-skill — CUDA 开发者专属技能库，覆盖 PTX ISA、CUDA Runtime/Driver API、cuBLAS、NCCL。如果你做 GPU 编程或 LLM 推理优化，这是必备。
• • DDD Skills：github.com/ForceInjection/domain-driven-design-skills — 领域驱动设计专属技能库，封装了 DDD 的战略设计、战术设计和事件驱动架构模式。

最后一个问题

回到开头那个故事。

那位休陪产假的工程师，在创建 review skill 的那个下午，可能没想过架构模式，没想过渐进式披露，没想过 skill 测试金字塔。他只是想：我每次 review 都在做同样的判断，能不能把这些判断从脑子里搬出来，放进一个别人也能用的地方？

这就是「事不过三，三则 skill」最朴素也最强大的版本。不需要理解架构，不需要设计模式，不需要测试金字塔。只需要你意识到：「这件事我做了三次了，下次我不要再手动做。」

他留给团队的是一份可以被反复调用的能力，而不是一份「等老王回来再看」的 TODO。

你脑子里有哪些判断，也能搬出来，变成一个 skill？

可能比你以为的多得多。

本文基于 awesome-skills（原力注入 Agent Skill 合集）的工程实践、《图解 Skill —— AI 提效实战指南》（宝玉著）的方法论体系，以及作者在 Agent Skill 生态中的持续观察写成。文中提到的所有 skill 项目均为开源项目，可自由使用和研究。