1. 我在Agent项目里踩过的坑，以及Skills为什么能解决它

1.1 一次让我崩溃的重复翻车

我做AI Agent开发断断续续有三年，最怕听到的话不是“这个需求做不了”，而是用户轻描淡写的一句“让Agent按上周那样再做一次”。同一个任务，明明上周已经磨合出了完整套路，模型这周又像换了个人，从头开始踩所有踩过的坑。

最典型的一次，我让Agent做一份行业竞品分析。第一次干得相当漂亮——框架、数据口径、优劣势结论都到位，我甚至一度觉得可以交付了。第二天我让它按同一标准重新分析另一家竞品，它居然退化成“先问我要资料”的阶段，顺手还编了两条不存在的功能点。我当时以为是模型抽风，可反复测下来，根源其实很明确：我把“一份合格的竞品分析应该怎么做”这几千字全塞进了对话上下文，Agent表面上是会了，本质上只是记住了这一轮对话里的临时约定，根本不是掌握了稳定的能力。换个新会话，一切归零。

这还只是开始。为了让Agent“记住”流程，我试过把操作手册写进系统提示词，结果上下文越堆越长，单轮请求的token开销直接翻倍，响应速度肉眼可见变慢，模型反而开始抓不住重点。团队里几个人各写各的prompt，同一类任务三套做法，输出风格五花八门。那段时间我一直在琢磨：有没有一种机制，能把“某个任务的完整操作方法”打包成独立模块，Agent需要时自动加载照着执行，用完了就放下？研读完Agent Skills之后我确认，这个方向就是对的路子。

1.2 Skills的第一性原理：把操作经验变成可复用资产

Skills概念刚火起来的时候，很多介绍把它说成“给模型加技能包”，这句话没错，但太粗糙了。拆到底层，Skills的第一性原理只有三件事。

第一，把程序性知识显性化。模型内部隐含的知识擅长处理“是什么”，但多步骤任务依赖的往往是“怎么做”，也就是程序性知识。Skills用文档把“怎么做”完整写下来，等于把模型不擅长的隐性知识转成了它能直接阅读的显性指令。

第二，按需加载，不污染上下文。Skill不是常驻的system prompt，而是Agent接到任务后根据描述自主判断，命中某个技能才把对应手册读进上下文，用完了就释放。几十个技能手册不会同时占用对话窗口，这正是它和“狂塞提示词”最本质的区别。

第三，技能可迭代、可分享。一个Skill今天调一版，明天补一个坑，就是一份不断进化的作业指导书。同事之间、社区之间可以互相拷贝复用，不需要重新训练任何权重。我把这三件事浓缩成一句人话：Skills是把老师傅脑子里的手艺，变成谁都能照着做的标准化文件。

1.3 和Tools、Prompt、RAG、微调的边界到底在哪

这个话题每次都要被人问一次，我在这里直接给结论。

Tools是“手”，Skills是“手艺”，RAG是“资料库”，微调是“换人”。这五者不是互斥的，我现在的做法是优先用Skills封装整个流程，Tools作为Skill内部的调用基础，RAG只负责喂事实数据，Prompt做轻量沟通，微调除非场景极其固定且预算充足，否则我基本不碰。

这套思路理清之后，后面的事情就顺了。接下来我从文件结构层面讲，一个标准的Agent Skill到底应该怎么组织。

2. SKILL.md的设计逻辑：Agent Skills的骨架与灵魂

2.1 一个最小Skill长什么样

技能市场的配置文件格式在不同平台细节上有差异，但骨架高度一致。这里以目前社区里最主流的格式为例，先看一个最小可用的目录结构：

my-skill/ ├── SKILL.md ├── scripts/ │ └── generate_report.py └── templates/ └── report_template.md

SKILL.md是整个技能的门面，也是Agent判断“这个任务我能不能用这个技能”的依据。scripts和templates是执行层资产，负责提供具体的脚本工具和输出模板。为什么SKILL.md放在最顶层而不是塞进子目录？因为Agent加载技能时，默认第一个找的就是根目录下这个名字大小写完全一致的文档，路径越固定，命中率越高。头几次做Skill我顺手把文档命名成skill_guide.md，结果Agent经常识别不出来，排查了半天才意识到是文件名的问题。

2.2 描述文件里该写什么、不该写什么

SKILL.md通常由一个YAML格式的frontmatter和一段Markdown正文组成。frontmatter里最核心的字段是name和description。

name要短、要唯一，最好直接用动词短语。description这段尤其重要，它是Agent判断技能适用边界的唯一入口，一定要写清楚“什么时候用、输入是什么、输出是什么”。我用过的反面案例是一位同事写的：“本技能用于提升Agent的综合能力，广泛应用于各类场景。”这种描述等于没写，Agent看了根本不知道什么任务该触发它，结果就是技能永远不被使用。

在我自己维护的Skill里，description通常会写成三句话：

• 这个技能解决什么类型的问题（触发场景）
• 需要什么输入（触发条件）
• 完成后的输出是什么（预期结果）

正文部分则按“什么时候用—操作步骤—注意事项—输出格式—示例”的节奏组织。要明确一个原则：正文是写给模型看的操作手册，不是写给人的论文，每句话都指向一个可执行动作，不要堆砌背景知识。凡是“关于XX的背景介绍”这种段落，我全部删掉。

同样重要的，是别在正文里写死细节。比如“使用Python 3.12版本”“运行时间不能超过5秒”这类约束应该写在脚本容错逻辑里，而不是堆在描述文件里让模型执行时临场判断，否则模型会在无关细节上消耗大量推理精力。

2.3 脚本与资源的组织规范

脚本层的规范比想象中更影响最终效果，踩过坑才有体会。我有四条硬性约定。

一是保持最小依赖。Skill脚本尽量用Python标准库，或者只依赖最常见的第三方库，不能一到用户环境就缺包，更不该引导模型现装一堆依赖。

二是路径问题必须自包含。脚本内部读取模板、写输出文件，一律基于脚本自身的相对路径来解析。我早期写的Skill里直接写死了一个内部路径，结果在同事机器上跑直接报错，后来统一改成基于__file__计算路径，问题才彻底解决。

三是输入输出约定写清楚。脚本通过命令行参数接收输入，结果输出到stdout或指定文件，这样模型容易理解如何调用和解析。如果脚本又弹窗又交互，模型根本没法稳定使用。

四是模板集中管理。所有输出模板放到templates目录，和主逻辑分离，后续调整文案格式不用改代码，只改模板即可。比如周报模板的章节名调整，我可以直接改Markdown模板，不用碰生成脚本。

3. 用一个真实案例走完Skill开发的全流程

3.1 需求场景：自动生成项目周报

理论讲太多容易飘，我拿一个真实做过的项目来走完整流程。当时的痛点是：团队每周五要花一个下午人工整理周报，把各仓库的git提交记录捞出来，按功能开发、问题修复、文档调研分类，再拼成一份统一格式的Markdown。纯手工干，繁琐不说，每个人自己拼的格式还五花八门。

我的目标是做一个Skill，让Agent拿到仓库路径之后，自动拉取最近7天的提交记录，自动分类，生成一份统一模板的周报。

3.2 拆解流程与实现细节

整个任务拆成三步：收集数据、分类整理、填充模板。收集数据用git命令，分类整理用关键词规则，模板输出用固定格式的Markdown。

SKILL.md的frontmatter我写成这样：

--- name: weekly-report description: 根据git提交记录生成项目周报。当用户需要汇总本周工作、生成周报或整理交付物清单时使用。 ---

正文里最关键的部分是操作步骤，我明确告诉模型：先运行脚本获取分类数据，再结合用户补充信息填模板，最后输出文件。描述一定要细到“默认只看最近7天”“提交少于5条不强行分类”这类边界规则。

核心的采集脚本分成三块：执行git log拿原始记录、根据提交信息关键词分类、按类别聚合输出JSON。这里的关键词分类规则不需要很复杂，常见的前缀词命中率已经足够高，剩下的全部丢进“其他”类。我的经验是不要追求零漏判，分类规则要保守，宁可多留一点“其他”让模型在填充时自己判断，也不要把规则写死到误伤正常提交。

templates/report_template.md里预留了日期、功能开发、问题修复、文档与调研、风险与阻塞、下周计划等分区。值得强调的是，风险与阻塞、下周计划这两个分区模板里只留标题不留内容，这是有意为之——技能脚本能自动填充的是“已经发生的客观数据”，而风险与计划这类需要判断力的内容，必须留给Agent结合上下文补充，硬塞给脚本反而是错的。

3.3 测试方法与迭代经验

写完空跑一步就对了30%，剩余70%全是迭代出来的。先说测试方法。

我的习惯是构造三份测试数据：一份提交关键词很规范，一份包含大量无规则信息，一份提交极少（只有两三条）。分别测试技能的标准情况、噪声情况和边界情况。只有三种情况全部产出合格结果，我才敢把Skill放进生产目录。

第一次实测就发现了两个问题。第一个是脚本把“fix typo in README”归类成“文档与调研”还是“问题修复”，我的规则里“fix”命中问题修复，但实际内容是文档修改，分类明显不合理。处理方式是给规则加优先级，当“docs”和“fix”同时出现时优先判文档类，而不是按第一个匹配结果直接返回。第二个问题更隐蔽：git日志里同一人同一天有十几条提交，周报里全列出来非常冗余。后来在分类输出时加了按作者聚合、合并同质提交的规则，周报一下就清爽了。

调试这个Skill过程里我也明白了：你在测试的根本不是模型智商，而是你写的手册够不够清晰。模型本身能力大家都差不多，差异全在文档和脚本的设计是否站在模型视角考虑。比如我把“提交数目少于5条时，不强行分类，直接列出所有记录”写进注意事项，模型每次都能老老实实执行。后来我从这个约束反过来理解，凡是人类能凭直觉做的事，对模型来说都不是默认的，必须白纸黑字写清楚。

4. Skills生态观察：市场、推荐与避坑

4.1 各平台的技能分发方式

Skills作为一个标准化概念在社区里火起来之后，各个平台都开始搭建自己的分发体系。目前主流的获取方式大致分成官方技能市场、开源社区仓库、自建私有技能库三类。

官方技能市场按技能描述、示例和评级组织，类似于手机应用商店，搜索、安装都比较方便，适合快速上手。开源社区仓库则是把Skill当代码管理，一个仓库就是一个技能合集，开发者通过拉取仓库把别人沉淀的技能同步到本地。自建私有技能库是我目前主力使用的方式，把团队内部高频任务都封装成Skill放版本管理，配合自动化同步，所有人共用一套最新的技能资产。

这三个渠道不矛盾。官方市场负责“外来的成熟技能”，社区仓库负责“薅羊毛试新鲜”，自建库负责“自己真正吃饭的家伙”。我个人的比例大概是官方市场30%，社区仓库20%，自建库50%。

4.2 我长期在用的几个Skill

在技能市场里也淘到过不少好东西，这里列几个我长期在用的，大家可以根据自己场景作为参考。

首先是会议纪要结构化整理。输入一段原始会议转录文本，输出按“讨论主题、决定事项、待办任务、负责人员”组织的结构化纪要。这个技能几乎是职场场景刚需，而且对模型性格判断要求很低，只要手册写得清楚，任何模型都能稳定产出。

第二个是代码审查辅助。给定一个PR的diff，按逻辑正确性、安全隐患、性能问题、代码风格四个维度输出审查意见，并且每条意见标优先等级。这个Skill的关键不是让模型“找茬”，而是让它严格限制在给定的四个维度内，避免东拉西扯。

第三个是我自己写的自动周报，也就是上一章那个案例迭代后的成品。第四个是表格数据分析，能快速读取一个Markdown或CSV格式的表格数据，自动生成描述性统计和可视化的数据说明。这个技能特别适合上周报、月度总结类任务，配合周报Skill一起调用效果很好。

第五个是笔记整理类Skill，把零散的输入列表按主题聚类成一篇逻辑通顺的笔记稿，并且自动补充标题层级和关联标签。这个我选择它不只是因为功能，而是整套技能目录管理方式本身很值得参考，对单文件技能和多文件技能的目录规划都做了很好的示范。

我的选型原则就三条：跟真实工作流强相关、判断标准客观可执行、维护成本低。凡是三个条件缺一条，我都会果断放弃，技能库和代码库一样，宁缺毋滥。

4.3 下载使用第三方Skills时的注意事项

第三方Skills和第三方软件一样，最大的坑首先是安全问题。因为你拿到的Skill不止是文档，里面往往带可执行的脚本。安装之前必须逐行审查脚本内容，重点看三点：有没有执行网络请求并向未知地址上传数据、有没有执行危险系统命令（比如删除文件、修改系统配置）、有没有试图读取Agent的敏感上下文或凭证信息。我之前见过一个“便利”的Skill，号称能自动抓取用户浏览器历史生成摘要，这种功能就是把用户隐私直接送到第三方服务，绝对不能放进工作环境。

其次是描述文件的适用范围。很多第三方Skill的作者会为了覆盖度拼命把description写宽，导致Agent在不相干任务上频繁误加载技能，白白浪费token。所以安装后第一件事是检查description，范围写得太宽的直接改窄再入库。

第三是版本兼容。不同平台的Skills机制细节有差异，Claude平台的Skill格式和Codex的skills仓库不完全互通。我在代码库还是笔记库场景下都遇到过迁移技能时格式不适配的情况。跨平台使用前，先在隔离环境里跑一遍，确认功能正常再引入正式目录，能省掉大量排障时间。

5. 多Agent架构下Skills的编排与演进

5.1 Skills在Agent框架中的位置

讲完单个Skill的开发和生态，必然要回到一个现实问题：真实项目里，Agent不是只有单一技能，而是多个Agent、多个技能协同工作的系统。Skills在这个体系里到底处于哪一层？

从我自己的项目实践看，Skills本质上是一种“能力单元”，它和Agent是解耦的关系。框架层（不管是LangGraph、CrewAI还是自研的多Agent流程）负责流程编排、状态管理和Agent之间的通信，Skills则作为挂载在Agent上的能力模块，通过接口层对外暴露。接口层现在最常用的是MCP这类标准化协议，让Agent能够以统一方式调用外部工具和技能。简单说：框架决定“哪个Agent在什么时候干活”，Skills决定“这个Agent具体会干什么活”。

把Skills独立成能力单元之后还有一个好处：同一个Skill可以被不同Agent复用。比如周报技能既可以挂在项目经理Agent上，也可以挂在研发助理Agent上，不需要为每个Agent单独实现一遍。

5.2 多Skill协同与冲突

多个Skill放在一起，实际会遇到两类冲突，处理和预期差别很大。第一类是触发冲突，即同一个任务同时匹配了多个技能的description。第二类是上下文冲突，多个技能被加载后，各自的操作步骤反而会互相干扰。

触发冲突的解决办法是给技能明确的应用边界。我在设计描述时有一个习惯：每个Skill的description里都写一句“什么样的情况不要用这个技能”。这一句负向约束看着简单，实际对降低误触发率非常有效。此外在编排层还可以给技能设优先级，当多个技能匹配时，按优先级高者优先，低者作为补充。

上下文冲突则需要控制单次任务加载技能的数量。我自己的经验值是两个技能以下是安全的，三个以上几乎必然出现“手册互相打架”的情况。比如“生成周报”和“表格数据分析”两个技能同时加载，通常没问题；但同时加载五个技能，模型就会在“先做分类还是先做统计”之间来回摇摆，输出质量反而下降。所以我在框架层给单Agent设置了技能加载数量上限，超出的部分走二次触发，而不是全塞进去。

5.3 从Skills开始走向Agent产品化

最后聊一点个人判断。Skills这套机制最大的价值不是提升单次任务质量，而是让Agent的“能力一致性”变得可控。没有Skills的时候，同一个Agent今天靠谱、明天智障，全看上下文缘分；有了Skills，能力被固化成了文档、脚本、模板这些可审计、可版本管理的资产，Agent的行为稳定性大幅提升。这在我看来，就是Agent能走向产品化的前提。

我现在做Agent项目，第一步已经不再是搭框架，而是先盘需求、拆技能。把每个高频任务写成Skill，先解决“能力从哪来”，再考虑“Agent怎么跑”，整个开发效率比前几年高了一个量级。更重要的是，Skills让经验和知识能够跨项目、跨团队沉淀，而不是每次从零开始。如果你正在从零开始做自己的Agent项目，我的建议很简单：先挑一个你每周都要做一次的重复任务，把它做成第一个Skill。那个过程会让你真正理解这套机制这个方向的价值所在。