最近圈子里一直在聊一个词就是 Skills。你可能已经在各种 AI 相关的内容里看到过 Agent Skills、Skill 库、给模型装技能包 之类的说法但对它到底是什么、能解决什么问题、和我平时用的 Prompt 或者工具调用有什么区别还是一头雾水。这块我研究了大半个月把自己从设计思路到落地踩坑的整个流程都过了一遍包括怎么定技能的粒度、怎么写 SKILL.md、怎么处理模型会但不精的尴尬问题、以及用 YAML frontmatter 组织元信息的那套规范。今天干脆一次性说透把我自己搭的一套可复用的技能库方案完整拆出来希望给正在琢磨这个东西的朋友一点参考。1. 先把概念对齐Skills 到底是什么解决什么问题1.1 从 Prompt 到工具调用再到 Skill 的进化逻辑最早我们跟大模型协作靠的是 Prompt。你写一大段详细的指令告诉模型你是一个 XX 专家请按照以下步骤输出……模型按你的要求办事。这种方式的问题是指令和逻辑混在一次性的对话里换一个场景就得重新写完全不能复用。后来有了 Function Calling模型可以在对话过程中动态决定调用某个函数比如查询天气、获取数据库记录、发一封邮件。这解决了模型能不能碰外部世界的问题但依然有个痛点一个复杂的业务任务往往需要模型按顺序、按条件调用多个函数并且每一步之间还有依赖关系、校验逻辑、异常分支。这部分如何编排的知识Function Calling 本身并没有封装好你还是得在外面写代码去驱动。Skills 正好把这个空缺补上了。你可以把一个完整的任务流程——包括它要用到的所有工具、每一步的触发条件、参数的默认值和约束、输出格式的要求、典型示例——全部打包成一个独立的技能模块。一旦定义好了模型只需要知道有这个技能和什么时候该用它剩下的流程细节、工具调用顺序、策略选择都由 Skill 内部的编排逻辑自动完成。从这个角度看Skill 的本质是可复用的任务执行策略它比 Prompt 更结构化比单个工具调用更具备流程编排能力。1.2 我为什么觉得这玩意值得投入时间我在搭建过程中越来越感觉到Skills 最大的价值不是多了一个新概念而是它直接改变了你组织 AI 应用的方式。过去我是这么干的先想需求然后写一套很长的系统提示词再配上几个函数定义接着在主循环里写死调用逻辑。结果是项目与项目之间相同的那部分工作比如处理 PDF、分析表格、生成结构化报告我一遍又一遍地重复写改一个参数就要动一整套代码。现在我把这些重复性工作拆成了独立的 SkillPDF 解析算一个表格分析和字段映射算一个报告结构生成算一个代码审查算一个。每个 Skill 的内部实现是自治的有输入规范、执行步骤、输出协议。新的项目来了我只需要在需求里声明我需要用哪些 Skill然后像搭积木一样把它们组合起来就行。这种模块化的价值打个比方就跟你收拾书房是一个道理。以前所有的工具、文具、文件都堆在桌面上你要找什么东西就得翻半天而且每一次新的活计都得重新理一遍。现在你把它们分类放到不同的抽屉里每个抽屉上贴个标签以后干活只需要拉开对应的抽屉。AI 应用从一次性定制开发变成按需组装这就是 Skills 最核心的意义。2. 核心设计思路拆解一个 Skill 应该长什么样2.1 Skill 文件的目录结构与元信息一个 Skill 在文件层面通常是一个独立的目录里面包含描述文件、参考示例和可选的脚本代码。先说目录和文件这是目前社区比较共识的写法也是我自己沿用并验证过的一套结构skill-name/ ├── SKILL.md # 主描述文件记录技能名称、说明、使用方式 ├── reference/ # 参考资料目录存放示例输出、模板、补充说明 │ ├── example_output.md │ └── template.txt └── scripts/ # 可选存放可执行脚本或辅助代码 └── run.py里面最核心的文件就是SKILL.md。它通常采用类似 YAML frontmatter 的风格在文件头部写清楚技能的元信息然后在正文里写清楚这个技能的触发条件、执行步骤和注意事项。我自己总结的SKILL.md骨架大致如下--- name: extract_table_from_image description: 从表格图片中提取结构化数据适用于截图、扫描件等。 when_to_use: 用户提供了包含表格内容的图片需要转成 CSV/Excel/JSON 结构化数据。 --- ### 执行步骤 1. 接收图片判断清晰度和表格边界。 2. 使用 OCR 识别表头和单元格内容。 3. 根据识别结果进行字段映射补全缺失列。 4. 输出 CSV 或 JSON 格式数据。 ### 注意事项 - 图片倾斜超过 15 度时先做透视矫正。 - 合并单元格时默认取左上角值填充。注意description和when_to_use这两项要写得足够明确。因为很多场景下模型是靠这些描述来决定什么时候该唤起这个技能的。描述写得模糊模型就会犹豫到底用不用触发条件写得宽泛模型就会在不该用的时候强行套用。2.2 描述文件里的触发设计为什么关键我自己实测下来when_to_use这一项的措辞直接影响技能被调用的准确率。先说一个反面例子。我有一个技能是处理 CSV 数据的最开始我写的触发条件是当用户提供 CSV 文件时使用。结果模型经常在用户只是提到数据表两个字的时候就把这个技能调起来生成了过于复杂的处理流程。后来我把when_to_use改成了这样when_to_use: 仅当输入数据已经是 CSV 格式且需要进行列名归一化、类型推断、缺失值统计等清洗操作时使用。如果是普通对话性提问不要调用。加了仅当且这些限定词以及不要调用的负面清单模型的判断准确率明显提高。这说明技能描述不只是写给人看的更是写给模型看的路由条件。写清楚边界实际上是在帮模型做更精准的决策。2.3 参考资料Reference和脚本Scripts如何配合如果这个技能涉及的输出格式比较固定我会在reference目录里放一两个完整的示例输出文件。这个做法非常有效因为模型往往从示例中学习格式要求比读一大段说明文字理解得更快。比如我那个会议纪要技能reference/example_output.md里就放了一份完整的纪要示例包括参会人、议题背景、讨论要点、结论和待办事项。每个待办事项后面都标了负责人和截止日期。模型在生成新纪要及时会潜意识参照这个模板输出的格式一致性高很多。再说scripts目录。有些技能需要执行非模型能力范围内的操作比如读写本地文件、调用某个 API、运行某个算法。这时候脚本目录就派上用场了。我的原则是脚本只做模型做不了的事情凡是模型能通过文本推理完成的工作就让它直接推理生成不要为了看起来工程化而硬接脚本。3. 实操演示从零搭建一个代码审查技能理论讲一堆不如直接上手做一个。我挑一个比较有代表性、大家也都用得到的场景代码审查Code Review。这个技能既要理解代码文件又要按规范做静态分析还要能输出结构化的问题列表很适合说明一个完整的 Skill 是怎么从无到有设计出来的。3.1 技能定义明确输入输出和边界我的目标是让模型在执行代码审查时不要泛泛而谈看起来不错而是严格按一套规则去发现问题。所以第一步我先写清楚了入参和出参。入参代码文件路径或者直接粘贴的代码内容。目标语言Python、JavaScript、Go 等。审查的侧重点比如性能、安全性、可维护性。出参问题清单按严重程度分为阻断Blocker、严重Major、建议Minor三级。每条问题包含文件名、行号、问题描述、修改建议。末尾附一段代码亮点指出写得好或值得保持的地方。我把这些定义写进了SKILL.md的 frontmatter 和正文开头这样模型一读取描述文件就知道自己接下来要扮演的角色边界。3.2 执行流程把审查步骤拆成可复用的固定逻辑代码审查的步骤看着简单真要让模型按固定流程走还是得把步骤写细。我把整个流程分成了五步每一步在SKILL.md里单独成段先通读代码结构理解模块划分和数据流不要急着挑毛病。逐函数、逐类检查重点关注错误处理、资源释放、条件边界。对照预先设定的规则清单逐项排查比如 SQL 注入、正则灾难性回溯、循环内重复计算。汇总问题按严重程度分级并给出可操作的修改方向。生成最终报告格式参照reference/example_output.md。这里有个细节值得说一下。第二步先理解再挑毛病是我吃过亏之后特意加上的。最早我的流程是一上来就让模型找问题结果模型会把一些局部写法当成错误而忽略了整个模块的设计意图。改成先通读、后逐项分析之后审查报告的质量明显提升。3.3 配套参考示例给模型一个对的样子技能里我放了两份参考文件第一份reference/example_output.md是一份完整但是虚构的审查报告里面包含了每个问题的严重级别、问题描述、所在行号以及修改后的代码片段。这样模型输出时不会因为不知道报告应该长什么样而自由发挥。第二份reference/rule_checks.md是一份通用的代码审查规则清单比如资源文件、数据库连接、网络请求是否确保关闭是否对用户输入做了校验和过滤异常分支是否吞掉了错误导致问题无法追踪是否有明显的并发安全问题日志是否记录了足够的关键上下文这相当于把资深工程师脑子里的审查清单外置成了模型可查阅的知识文件。模型不用每次靠记忆去回想应该检查什么而是会主动去翻阅这份规则清单按照清单逐项对号入座。3.4 不用脚本也能完成的高效实现代码审查这个技能我没有写任何scripts下的脚本。原因是模型本身理解代码的能力已经足够强审查逻辑完全可以通过提示词和参考文档来驱动。如果强行加一个语法检查脚本反而会打断模型的分析节奏。不过我也遇到过需要脚本的场景。比如处理一个超大型仓库直接让模型一次性读取所有文件token 消耗巨大且容易超出上下文窗口。这种时候我会额外写一个scripts/chunk_files.py按目录结构把大仓库切分成小块逐块调用模型进行分析最后再把各块结果合并成完整报告。脚本的使用原则很简单能用文本推理解决的不走脚本只有涉及文件系统操作、网络调用、大规模分块处理时才引入脚本辅助。4. 实操过程与核心环节实现手写一个会议纪要技能第二个案例我选一个非程序员也会很需要的会议纪要技能。这个技能我用了大概两个月迭代了三个版本对我的日常工作效率提升很大。它不像代码审查那么硬核但对描述文件设计的细节要求一点不少。4.1 版本一先让流程跑通第一版非常简单SKILL.md里只有三部分接收一段口语化的会议讨论记录或录音转写文本提取关键讨论点和结论输出结构清晰的会议纪要。实际用下来第一版有几个明显问题模型分不清讨论过的内容和最终决策的区别经常把中间讨论过程也当成结论写进去。待办事项缺少负责人和截止日期会后还要人工逐条核实。对口语转写中的语气词、重复语句处理不太干净纪要读起来比较啰嗦。这个版本虽然能用但并没有比直接甩一大段提示词给模型强多少算不上一个称职的 Skill。于是我做了第二轮迭代。4.2 版本二细化输出协议和提取规则针对第一版的问题我在SKILL.md里明确规定了以下几条规则所有表述要使用书面化、简洁的句子去掉口头禅、重复和语气填充词。讨论过程统一归纳为背景和各方观点只保留关键分歧点不逐句还原对话。结论必须是达成一致的内容如果讨论过程中某一事项没有明确结论一律归入待议事项不强行写进结论。待办事项采用统一的[负责人] 事项描述截止时间格式没有明确负责人的标注待指定。同时我更新了reference/example_output.md加入一份标准格式的全文模板。模板分为四块会议背景、讨论要点、结论、待办事项。每一块的写法都清晰规定。这个版本上线后输出的纪要质量明显提升基本能达到稍作修改就能发出去的水平。4.3 版本三加入参会人和议题标签第三个版本的迭代动力是我发现自己开完会后经常需要回头去找某个人说了什么、某个议题的讨论脉络是什么。这时候光有四段式的纪要不顶用需要在内容结构上进行扩展。我在模板里增加了一个参会人列表并且在每段讨论要点前标注了对应的议题标签。比如[议题数据中心迁移]这样的开头。这样一来整份纪要不再是一个流水账而是一个按议题索引的档案文件。更关键的是我在when_to_use里加了一条限制仅当输入内容包含多人讨论或会议场景时使用普通的工作日志、任务整理不要使用本技能。 这个边界设定非常重要否则模型会在你随手写一段工作感想的时候跳出来强行帮你生成会议纪要体验很差。4.4 这个案例给到的设计启发会议纪要技能三个版本的迭代浓缩出一个很重要的经验Skills 的进化不是靠加功能而是靠收边界。第一版功能最简单但边界也最模糊第二版往输出协议里加了大量细节功能变强了到了第三版我没有继续加功能规则反而花了大量心思去设定什么时候不该用这个技能。这就像工具箱里的锤子锤面做得好是功能但更重要的是你得知道什么时候不该拿它砸东西。Skills 设计到后期真正拉开体验差距的往往是那些负向规则写得好不好。5. 常见问题与排查技巧实录实际操作了一段时间之后我总结了一些高频问题和处理经验这里直接整理成一个速查表方便大家少走弯路。典型现象可能原因排查思路与解决办法模型在不需要时调用了技能when_to_use写得太宽泛在触发条件里加入限定词并显式补充什么情况下不要使用技能输出格式不稳定只在描述里写了要求缺少示例在reference目录中放一份或两份完整示例让模型模仿技能内部步骤经常被跳过步骤顺序描述不清晰把步骤拆成编号列表并对每一步补充输出物说明生成了正确步骤但结果错误参考文档信息过时或不匹配检查reference里的示例是否与当前版本一致及时更新技能与其他技能功能重叠技能边界没有划清在各自的when_to_use里写明互斥条件避免模型混淆调用技能后 token 消耗大增技能把无关内容也拉进了上下文收缩参考文档范围只保留与本次执行直接相关的内容5.1 模型总是会但不精怎么办这是我最初迭代时最头疼的问题。模型看了技能描述后能大致执行但做出来的结果总是差点意思——格式对但细节粗糙流程对但缺少专家级洞察。后来我想通了一个道理模型对技能的掌握完全取决于你喂给它的上下文质量。你只给它一份概述性的描述它就只能给出概述性的结果你给它精细的规则和高质量的范例它就能模仿出同样精细的风格。所以我现在的习惯是每做一个技能至少写两份文件一份是SKILL.md一份是reference/example_output.md。前者是怎么做的流程说明后者是做成什么样的标杆。两者缺一不可。5.2 技能库大了之后的管理问题当我攒到十几个技能之后新的问题出现了模型在决策调哪个技能时会犹豫甚至选错。我排查了一下发现原因是技能描述里缺少区分度。两个技能如果描述里用了太多相似的高频词模型就难以分辨。解决办法有两个一是给每个技能的when_to_use加上排他性描述。比如一个技能是处理表格图片另一个是处理扫描 PDF我会在各自的描述里明确写如果输入是扫描 PDF请使用 XX 技能而不要使用本技能。二是定期整理技能清单。我每隔一段时间会输出一份技能总览文档把所有已存在技能的名称和一句话描述列一遍。这既能帮助模型更快路由也能让我自己发现自己是不是建了一些冗余的技能。5.3 命名规范与版本管理的血泪教训前期的技能命名比较随意出现了handle_csv、csv_processor、csv_to_json这种职能高度重叠的目录。等技能多起来以后不仅模型容易混淆我自己看一眼目录列表也会愣住。我后来统一了命令规范动词开头 对象 场景全部用小写下划线连接例如extract_table_from_imagegenerate_meeting_minutesreview_python_codesummarize_long_document同时我在每个技能目录里增加了一个简单的版本字段version: 2.0记录大版本号。当参考文档或者脚本逻辑有较大调整时就升级版本号。这个习惯在后期排查为什么这个技能表现跟以前不一样了的时候非常有用。6. 一点个人心得说到底Skills 不是什么颠覆性的黑科技它更像是一套把经验固化成可复用资产的方法论。你平时怎么总结自己的高效工作流怎么整理自己的知识库就可以怎么用 Skills 驱动 AI 去执行具体任务。我在实际使用中发现真正拉开差距的往往不是会写多少代码、用了多复杂的框架而是能不能把一件事的流程拆干净、边界划清楚。技能写得好的人不一定懂最多的模型原理但他一定是最清楚这件事到底该怎么做的人。所以如果你准备开始试我的建议是先不要贪多挑一个你每周都会重复做三次以上的任务把它拆成一个 Skill 试试。跑通了再往下铺。技能库是慢慢养出来的不是一蹴而就的。
Agent Skills 实战：从 Prompt 到 SKILL.md 的技能包设计指南
最近圈子里一直在聊一个词就是 Skills。你可能已经在各种 AI 相关的内容里看到过 Agent Skills、Skill 库、给模型装技能包 之类的说法但对它到底是什么、能解决什么问题、和我平时用的 Prompt 或者工具调用有什么区别还是一头雾水。这块我研究了大半个月把自己从设计思路到落地踩坑的整个流程都过了一遍包括怎么定技能的粒度、怎么写 SKILL.md、怎么处理模型会但不精的尴尬问题、以及用 YAML frontmatter 组织元信息的那套规范。今天干脆一次性说透把我自己搭的一套可复用的技能库方案完整拆出来希望给正在琢磨这个东西的朋友一点参考。1. 先把概念对齐Skills 到底是什么解决什么问题1.1 从 Prompt 到工具调用再到 Skill 的进化逻辑最早我们跟大模型协作靠的是 Prompt。你写一大段详细的指令告诉模型你是一个 XX 专家请按照以下步骤输出……模型按你的要求办事。这种方式的问题是指令和逻辑混在一次性的对话里换一个场景就得重新写完全不能复用。后来有了 Function Calling模型可以在对话过程中动态决定调用某个函数比如查询天气、获取数据库记录、发一封邮件。这解决了模型能不能碰外部世界的问题但依然有个痛点一个复杂的业务任务往往需要模型按顺序、按条件调用多个函数并且每一步之间还有依赖关系、校验逻辑、异常分支。这部分如何编排的知识Function Calling 本身并没有封装好你还是得在外面写代码去驱动。Skills 正好把这个空缺补上了。你可以把一个完整的任务流程——包括它要用到的所有工具、每一步的触发条件、参数的默认值和约束、输出格式的要求、典型示例——全部打包成一个独立的技能模块。一旦定义好了模型只需要知道有这个技能和什么时候该用它剩下的流程细节、工具调用顺序、策略选择都由 Skill 内部的编排逻辑自动完成。从这个角度看Skill 的本质是可复用的任务执行策略它比 Prompt 更结构化比单个工具调用更具备流程编排能力。1.2 我为什么觉得这玩意值得投入时间我在搭建过程中越来越感觉到Skills 最大的价值不是多了一个新概念而是它直接改变了你组织 AI 应用的方式。过去我是这么干的先想需求然后写一套很长的系统提示词再配上几个函数定义接着在主循环里写死调用逻辑。结果是项目与项目之间相同的那部分工作比如处理 PDF、分析表格、生成结构化报告我一遍又一遍地重复写改一个参数就要动一整套代码。现在我把这些重复性工作拆成了独立的 SkillPDF 解析算一个表格分析和字段映射算一个报告结构生成算一个代码审查算一个。每个 Skill 的内部实现是自治的有输入规范、执行步骤、输出协议。新的项目来了我只需要在需求里声明我需要用哪些 Skill然后像搭积木一样把它们组合起来就行。这种模块化的价值打个比方就跟你收拾书房是一个道理。以前所有的工具、文具、文件都堆在桌面上你要找什么东西就得翻半天而且每一次新的活计都得重新理一遍。现在你把它们分类放到不同的抽屉里每个抽屉上贴个标签以后干活只需要拉开对应的抽屉。AI 应用从一次性定制开发变成按需组装这就是 Skills 最核心的意义。2. 核心设计思路拆解一个 Skill 应该长什么样2.1 Skill 文件的目录结构与元信息一个 Skill 在文件层面通常是一个独立的目录里面包含描述文件、参考示例和可选的脚本代码。先说目录和文件这是目前社区比较共识的写法也是我自己沿用并验证过的一套结构skill-name/ ├── SKILL.md # 主描述文件记录技能名称、说明、使用方式 ├── reference/ # 参考资料目录存放示例输出、模板、补充说明 │ ├── example_output.md │ └── template.txt └── scripts/ # 可选存放可执行脚本或辅助代码 └── run.py里面最核心的文件就是SKILL.md。它通常采用类似 YAML frontmatter 的风格在文件头部写清楚技能的元信息然后在正文里写清楚这个技能的触发条件、执行步骤和注意事项。我自己总结的SKILL.md骨架大致如下--- name: extract_table_from_image description: 从表格图片中提取结构化数据适用于截图、扫描件等。 when_to_use: 用户提供了包含表格内容的图片需要转成 CSV/Excel/JSON 结构化数据。 --- ### 执行步骤 1. 接收图片判断清晰度和表格边界。 2. 使用 OCR 识别表头和单元格内容。 3. 根据识别结果进行字段映射补全缺失列。 4. 输出 CSV 或 JSON 格式数据。 ### 注意事项 - 图片倾斜超过 15 度时先做透视矫正。 - 合并单元格时默认取左上角值填充。注意description和when_to_use这两项要写得足够明确。因为很多场景下模型是靠这些描述来决定什么时候该唤起这个技能的。描述写得模糊模型就会犹豫到底用不用触发条件写得宽泛模型就会在不该用的时候强行套用。2.2 描述文件里的触发设计为什么关键我自己实测下来when_to_use这一项的措辞直接影响技能被调用的准确率。先说一个反面例子。我有一个技能是处理 CSV 数据的最开始我写的触发条件是当用户提供 CSV 文件时使用。结果模型经常在用户只是提到数据表两个字的时候就把这个技能调起来生成了过于复杂的处理流程。后来我把when_to_use改成了这样when_to_use: 仅当输入数据已经是 CSV 格式且需要进行列名归一化、类型推断、缺失值统计等清洗操作时使用。如果是普通对话性提问不要调用。加了仅当且这些限定词以及不要调用的负面清单模型的判断准确率明显提高。这说明技能描述不只是写给人看的更是写给模型看的路由条件。写清楚边界实际上是在帮模型做更精准的决策。2.3 参考资料Reference和脚本Scripts如何配合如果这个技能涉及的输出格式比较固定我会在reference目录里放一两个完整的示例输出文件。这个做法非常有效因为模型往往从示例中学习格式要求比读一大段说明文字理解得更快。比如我那个会议纪要技能reference/example_output.md里就放了一份完整的纪要示例包括参会人、议题背景、讨论要点、结论和待办事项。每个待办事项后面都标了负责人和截止日期。模型在生成新纪要及时会潜意识参照这个模板输出的格式一致性高很多。再说scripts目录。有些技能需要执行非模型能力范围内的操作比如读写本地文件、调用某个 API、运行某个算法。这时候脚本目录就派上用场了。我的原则是脚本只做模型做不了的事情凡是模型能通过文本推理完成的工作就让它直接推理生成不要为了看起来工程化而硬接脚本。3. 实操演示从零搭建一个代码审查技能理论讲一堆不如直接上手做一个。我挑一个比较有代表性、大家也都用得到的场景代码审查Code Review。这个技能既要理解代码文件又要按规范做静态分析还要能输出结构化的问题列表很适合说明一个完整的 Skill 是怎么从无到有设计出来的。3.1 技能定义明确输入输出和边界我的目标是让模型在执行代码审查时不要泛泛而谈看起来不错而是严格按一套规则去发现问题。所以第一步我先写清楚了入参和出参。入参代码文件路径或者直接粘贴的代码内容。目标语言Python、JavaScript、Go 等。审查的侧重点比如性能、安全性、可维护性。出参问题清单按严重程度分为阻断Blocker、严重Major、建议Minor三级。每条问题包含文件名、行号、问题描述、修改建议。末尾附一段代码亮点指出写得好或值得保持的地方。我把这些定义写进了SKILL.md的 frontmatter 和正文开头这样模型一读取描述文件就知道自己接下来要扮演的角色边界。3.2 执行流程把审查步骤拆成可复用的固定逻辑代码审查的步骤看着简单真要让模型按固定流程走还是得把步骤写细。我把整个流程分成了五步每一步在SKILL.md里单独成段先通读代码结构理解模块划分和数据流不要急着挑毛病。逐函数、逐类检查重点关注错误处理、资源释放、条件边界。对照预先设定的规则清单逐项排查比如 SQL 注入、正则灾难性回溯、循环内重复计算。汇总问题按严重程度分级并给出可操作的修改方向。生成最终报告格式参照reference/example_output.md。这里有个细节值得说一下。第二步先理解再挑毛病是我吃过亏之后特意加上的。最早我的流程是一上来就让模型找问题结果模型会把一些局部写法当成错误而忽略了整个模块的设计意图。改成先通读、后逐项分析之后审查报告的质量明显提升。3.3 配套参考示例给模型一个对的样子技能里我放了两份参考文件第一份reference/example_output.md是一份完整但是虚构的审查报告里面包含了每个问题的严重级别、问题描述、所在行号以及修改后的代码片段。这样模型输出时不会因为不知道报告应该长什么样而自由发挥。第二份reference/rule_checks.md是一份通用的代码审查规则清单比如资源文件、数据库连接、网络请求是否确保关闭是否对用户输入做了校验和过滤异常分支是否吞掉了错误导致问题无法追踪是否有明显的并发安全问题日志是否记录了足够的关键上下文这相当于把资深工程师脑子里的审查清单外置成了模型可查阅的知识文件。模型不用每次靠记忆去回想应该检查什么而是会主动去翻阅这份规则清单按照清单逐项对号入座。3.4 不用脚本也能完成的高效实现代码审查这个技能我没有写任何scripts下的脚本。原因是模型本身理解代码的能力已经足够强审查逻辑完全可以通过提示词和参考文档来驱动。如果强行加一个语法检查脚本反而会打断模型的分析节奏。不过我也遇到过需要脚本的场景。比如处理一个超大型仓库直接让模型一次性读取所有文件token 消耗巨大且容易超出上下文窗口。这种时候我会额外写一个scripts/chunk_files.py按目录结构把大仓库切分成小块逐块调用模型进行分析最后再把各块结果合并成完整报告。脚本的使用原则很简单能用文本推理解决的不走脚本只有涉及文件系统操作、网络调用、大规模分块处理时才引入脚本辅助。4. 实操过程与核心环节实现手写一个会议纪要技能第二个案例我选一个非程序员也会很需要的会议纪要技能。这个技能我用了大概两个月迭代了三个版本对我的日常工作效率提升很大。它不像代码审查那么硬核但对描述文件设计的细节要求一点不少。4.1 版本一先让流程跑通第一版非常简单SKILL.md里只有三部分接收一段口语化的会议讨论记录或录音转写文本提取关键讨论点和结论输出结构清晰的会议纪要。实际用下来第一版有几个明显问题模型分不清讨论过的内容和最终决策的区别经常把中间讨论过程也当成结论写进去。待办事项缺少负责人和截止日期会后还要人工逐条核实。对口语转写中的语气词、重复语句处理不太干净纪要读起来比较啰嗦。这个版本虽然能用但并没有比直接甩一大段提示词给模型强多少算不上一个称职的 Skill。于是我做了第二轮迭代。4.2 版本二细化输出协议和提取规则针对第一版的问题我在SKILL.md里明确规定了以下几条规则所有表述要使用书面化、简洁的句子去掉口头禅、重复和语气填充词。讨论过程统一归纳为背景和各方观点只保留关键分歧点不逐句还原对话。结论必须是达成一致的内容如果讨论过程中某一事项没有明确结论一律归入待议事项不强行写进结论。待办事项采用统一的[负责人] 事项描述截止时间格式没有明确负责人的标注待指定。同时我更新了reference/example_output.md加入一份标准格式的全文模板。模板分为四块会议背景、讨论要点、结论、待办事项。每一块的写法都清晰规定。这个版本上线后输出的纪要质量明显提升基本能达到稍作修改就能发出去的水平。4.3 版本三加入参会人和议题标签第三个版本的迭代动力是我发现自己开完会后经常需要回头去找某个人说了什么、某个议题的讨论脉络是什么。这时候光有四段式的纪要不顶用需要在内容结构上进行扩展。我在模板里增加了一个参会人列表并且在每段讨论要点前标注了对应的议题标签。比如[议题数据中心迁移]这样的开头。这样一来整份纪要不再是一个流水账而是一个按议题索引的档案文件。更关键的是我在when_to_use里加了一条限制仅当输入内容包含多人讨论或会议场景时使用普通的工作日志、任务整理不要使用本技能。 这个边界设定非常重要否则模型会在你随手写一段工作感想的时候跳出来强行帮你生成会议纪要体验很差。4.4 这个案例给到的设计启发会议纪要技能三个版本的迭代浓缩出一个很重要的经验Skills 的进化不是靠加功能而是靠收边界。第一版功能最简单但边界也最模糊第二版往输出协议里加了大量细节功能变强了到了第三版我没有继续加功能规则反而花了大量心思去设定什么时候不该用这个技能。这就像工具箱里的锤子锤面做得好是功能但更重要的是你得知道什么时候不该拿它砸东西。Skills 设计到后期真正拉开体验差距的往往是那些负向规则写得好不好。5. 常见问题与排查技巧实录实际操作了一段时间之后我总结了一些高频问题和处理经验这里直接整理成一个速查表方便大家少走弯路。典型现象可能原因排查思路与解决办法模型在不需要时调用了技能when_to_use写得太宽泛在触发条件里加入限定词并显式补充什么情况下不要使用技能输出格式不稳定只在描述里写了要求缺少示例在reference目录中放一份或两份完整示例让模型模仿技能内部步骤经常被跳过步骤顺序描述不清晰把步骤拆成编号列表并对每一步补充输出物说明生成了正确步骤但结果错误参考文档信息过时或不匹配检查reference里的示例是否与当前版本一致及时更新技能与其他技能功能重叠技能边界没有划清在各自的when_to_use里写明互斥条件避免模型混淆调用技能后 token 消耗大增技能把无关内容也拉进了上下文收缩参考文档范围只保留与本次执行直接相关的内容5.1 模型总是会但不精怎么办这是我最初迭代时最头疼的问题。模型看了技能描述后能大致执行但做出来的结果总是差点意思——格式对但细节粗糙流程对但缺少专家级洞察。后来我想通了一个道理模型对技能的掌握完全取决于你喂给它的上下文质量。你只给它一份概述性的描述它就只能给出概述性的结果你给它精细的规则和高质量的范例它就能模仿出同样精细的风格。所以我现在的习惯是每做一个技能至少写两份文件一份是SKILL.md一份是reference/example_output.md。前者是怎么做的流程说明后者是做成什么样的标杆。两者缺一不可。5.2 技能库大了之后的管理问题当我攒到十几个技能之后新的问题出现了模型在决策调哪个技能时会犹豫甚至选错。我排查了一下发现原因是技能描述里缺少区分度。两个技能如果描述里用了太多相似的高频词模型就难以分辨。解决办法有两个一是给每个技能的when_to_use加上排他性描述。比如一个技能是处理表格图片另一个是处理扫描 PDF我会在各自的描述里明确写如果输入是扫描 PDF请使用 XX 技能而不要使用本技能。二是定期整理技能清单。我每隔一段时间会输出一份技能总览文档把所有已存在技能的名称和一句话描述列一遍。这既能帮助模型更快路由也能让我自己发现自己是不是建了一些冗余的技能。5.3 命名规范与版本管理的血泪教训前期的技能命名比较随意出现了handle_csv、csv_processor、csv_to_json这种职能高度重叠的目录。等技能多起来以后不仅模型容易混淆我自己看一眼目录列表也会愣住。我后来统一了命令规范动词开头 对象 场景全部用小写下划线连接例如extract_table_from_imagegenerate_meeting_minutesreview_python_codesummarize_long_document同时我在每个技能目录里增加了一个简单的版本字段version: 2.0记录大版本号。当参考文档或者脚本逻辑有较大调整时就升级版本号。这个习惯在后期排查为什么这个技能表现跟以前不一样了的时候非常有用。6. 一点个人心得说到底Skills 不是什么颠覆性的黑科技它更像是一套把经验固化成可复用资产的方法论。你平时怎么总结自己的高效工作流怎么整理自己的知识库就可以怎么用 Skills 驱动 AI 去执行具体任务。我在实际使用中发现真正拉开差距的往往不是会写多少代码、用了多复杂的框架而是能不能把一件事的流程拆干净、边界划清楚。技能写得好的人不一定懂最多的模型原理但他一定是最清楚这件事到底该怎么做的人。所以如果你准备开始试我的建议是先不要贪多挑一个你每周都会重复做三次以上的任务把它拆成一个 Skill 试试。跑通了再往下铺。技能库是慢慢养出来的不是一蹴而就的。
