从今年年初开始我越来越频繁地听到身边同事抱怨同一个问题AI工具明明很聪明但每次都得重新教一遍“我们团队是怎么做事的”。比如团队约定周报必须按“本周目标—进展—风险—下周计划”四段式来写头一天晚上刚给AI讲清楚第二天新开一个会话它又忘了。再比如项目里的代码提交规范、接口设计约束每次都要靠人肉重复一遍。后来我接触到一个思路——Agent Skills也就是把“你的工作方式”直接沉淀成AI可以加载、复用、执行的技能包。方向上是对的但真正用起来之后我发现这件事远不是“写个文档扔给AI”那么简单。这篇文章不聊概念纯讲实践经验。我从零开始设计了一个“符合团队习惯的周报技能”跑通了从技能编写、加载调用到迭代维护的全流程中间踩了不少坑。把这些过程拆开来讲希望能给正在做同样事情的人省点弯路。1. 为什么普通提示词记不住你的工作方式Agent Skills解决的痛点是长期记忆先回答一个最基础的问题既然大模型本身的能力已经这么强为什么还要单独搞一套“技能”机制直接告诉它“按四段式写周报”不行吗1.1 上下文窗口再大也装不下你所有的隐性习惯很多人习惯把所有要求一股脑塞进系统提示词System Prompt觉得只要写清楚了AI就能一直按这个执行。实测下来这个想法过于乐观。一个真实项目里团队积累的代码规范、文档模板、沟通风格、验收标准加起来轻轻松松超过几千甚至上万字。即便是长上下文模型每次对话都把这些全部塞进去既不现实也会严重稀释模型对当前任务的注意力。更深层的问题是大部分“工作方式”根本不是显性的“规则文本”。它们藏在你们的命名习惯里藏在某个约定俗成的流程里藏在老员工下意识的操作里。这些内容如果不去主动结构化AI根本无从“记住”。1.2 技能包的本质把隐性知识变成AI可加载的显式资产Agent Skills之所以比普通提示词更“能记住”核心在于它把知识分成了三层第一层是元信息描述让AI在恰当的时机意识到“这里有对应的技能可调用”第二层是规范与步骤正文告诉AI这项任务应该按什么逻辑、什么顺序来做第三层是脚本与示例把“凭感觉做事”变成“有据可循的确定性动作”。我拿自己做的一个技能举例。团队内部有个约定每周五下午要生成一份项目状态汇报包含本周每个模块的代码提交量、未关闭的Issue、风险项。过去这件事靠人肉从各个平台拉数据再整理耗时四十分钟以上。后来我把这个流程做成了技能包AI在拿到“生成项目周报”这个请求时会自动读取技能中的步骤说明、调用脚本去拉取提交记录、再按团队模板生成报告。这一个技能让四十分钟的重复劳动压缩到了三分钟。更重要的是换任何一个人来用产出的格式完全一致因为格式已经被技能包固化了。1.3 技能包与传统工具的边界不是RAG也不是插件系统有一类问题需要单独说清楚。有人问Agent Skills和RAG检索增强生成、插件Plugin到底有什么区别这里我画一个简化版的边界。RAG解决的是“知识检索”问题——从企业知识库里找答案技能解决的是“行为复现”问题——按你习惯的动作序列完成一项工作。插件更偏向“工具接入”比如封装一个API调用技能则更偏向“工作流封装”它可以是纯文本的步骤规范也可以嵌套调用插件。以一个生活化的类比来说RAG是给AI配了个图书馆你问什么它去查什么插件是给AI配了双手它能操作外部工具而Agent Skills是给AI配了一套“工作手册”告诉它在什么场景下、按照什么顺序、用什么方式把手和图书馆组合起来完成任务。三者可以配合但解决的问题完全不同。这套边界的理解非常重要因为现实中我看到很多团队把三者混淆最后做出来的系统既不是好用的知识库也不是真正能复现工作流的技能体系。2. 技能包内部结构拆解SKILL.md才是真正决定能不能“记住”的核心明白了Agent Skills是“把工作方式变成可加载的资产”接下来就要动手做。但在写任何内容之前必须先搞清楚一个技能包在磁盘和代码层面到底长什么样。2.1 一个技能包的物理结构目录、元信息与资源文件现阶段比较通用的技能包组织方式是把一个技能做成一个独立目录。我习惯用下面的结构weekly-report/ ├── SKILL.md ├── scripts/ │ ├── fetch_git_stats.py │ └── collect_open_issues.py ├── references/ │ └── weekly_report_example.md ├── assets/ │ └── report_template.docx └── tests/ └── test_skill_output.md目录中最重要的文件就是SKILL.md它是一切行为的入口。AI在判断“当前是否该用这个技能”时第一眼看的也是这个文件。其他所有内容——脚本、参考示例、模板——都是围绕SKILL.md里的定义去服务的。这里有一个新手常见的误区以为技能包就是把一堆Markdown文档堆在一起让AI自己“领悟”。实际上AI不会自动通读目录里的所有文件它只会依据SKILL.md中的指示来决定是否加载其他资源。所以SKILL.md的编写质量直接决定了技能包是否真的能被“想起”并正确执行。2.2 SKILL.md的元信息如何让AI在正确时机“想起”这个技能SKILL.md的开头通常包含一段元信息frontmatter它最重要的作用是为技能发现提供索引。我打磨过很多个版本后目前比较稳妥的骨架如下--- name: weekly-report description: 按团队规范的格式生成项目周报。当用户要求生成每周状态汇报、项目进展总结、部门周报时使用。包含 git 提交统计与 Issue 汇总。 when_to_use: 用户明确要求生成周报或上下文出现“本周进展”“每周汇报”等关键词时优先启用。 ---这段元信息看着简单但里面的每一个字段都有讲究。description我强烈建议写成“行为触发词 具体动作”的组合而不要只写“生成周报”四个字。原因是AI判断是否加载技能时靠的是语义匹配。如果描述里明确出现了“本周进展”“项目状态汇报”这些用户可能说的词那么命中率会大幅提升。写得太抽象AI很可能在真正需要技能时根本想不起来。when_to_use是一个很多开源技能包不太强调、但实战中很关键的字段。它相当于给AI一条强制提醒“你应该在这类场景下主动启用本技能”。从运行结果看加了这行后技能被自动启用的准确率明显提高了。2.3 SKILL.md正文的写作方式不是写给人看的说明文档而是写给AI执行的操作规程元信息下面是正文。这里最重要的是转变一个观念你在写的不是“给人看的说明”而是“给AI执行的踩踏点序列”。人看文档跳着读没问题但AI需要你给出明确的动作序列甚至每个动作的输出格式。我写正文时通常遵守四个原则第一先写“输入要求”说清楚用户应该提供哪些信息第二再写“处理步骤”按顺序罗列避免含糊的“根据情况判断”第三在每个步骤里定义“输入—处理—输出”的粒度让AI知道走到哪一步算是完成第四明确“风格与禁忌”比如禁用某些词、必须保留某些字段。用周报技能的正文做个简化示例# 项目周报生成技能 ## 输入要求 - 必需目标时间范围本周或指定日期段 - 可选需要重点汇总的模块名称 ## 处理步骤 1. 调用 scripts/fetch_git_stats.py获取时间范围内的提交记录按模块聚合统计。 2. 调用 scripts/collect_open_issues.py获取未关闭的高优先级 Issue 列表。 3. 按照 references/weekly_report_example.md 中的模板结构生成四段式周报本周目标、进展、风险、下周计划。 4. 风险段必须列出至少一个真实风险项如果没有写明“暂无明显风险”。 ## 输出要求 - 使用中文面向项目负责人 - 段落标题用加粗风险项使用序号列表 - 禁止在报告中输出代码提交的作者姓名。这样的正文AI执行起来几乎不会跑偏。因为它每一步都有明确的输入和输出约束。反过来如果正文只写“生成一份周报”那AI大概率会给你一份“看起来没什么错但完全不是你要的东西”的输出。2.4 脚本和示例的价值把“凭感觉”变成“可复现”SKILL.md负责告诉AI“做什么、按什么顺序”但很多实际操作无法靠文本描述完成比如拉取Git记录、统计Issue。这时脚本就派上了用场。脚本的价值在于它把自然语言里容易产生歧义的描述“获取本周提交”变成了确定性操作执行Python脚本输出JSON。此外示例文件references的作用也常被低估。一个与最终期望输出格式高度一致的示例比十句“请按规范格式输出”的描述都管用。大模型对示例的模仿能力远强于对抽象指令的遵循能力这已经是行业内比较普遍的共识。所以我强烈建议每个技能包至少配一个完整的、带真实数据结构的示例文件。3. 做一个真正能用的技能从复述工作流到校准AI输出概念拆清楚了接下来是动手环节。我以“团队周报生成”这个技能为案例完整走一遍设计与落地的流程。这个案例虽然简单但足够把关键方法讲透把它换成“项目复盘技能”“代码审查技能”逻辑完全一样。3.1 第一步把真实的工作流“录像”而不是凭空想规范很多人在设计技能时有一个通病直接凭印象写操作步骤。这样做出来的技能AI执行得非常机械因为步骤本身就不是对真实工作流的提炼。我建议的做法是先找一次真实完成任务的过程把它完整记录下来。哪怕花一到两周刻意观察“我们现在到底是怎么做周报的”。拿我们团队举例。真实的周报流程是这样的先从Git仓库拉取一个时间区间内的提交日志按模块维度把提交归类人工扫一眼Issue列表挑出未关闭的高优先级内容把上述信息重新组织成四段式文字再检查一遍语言风格是否符合团队习惯最后发给项目负责人。这六个步骤才是技能应该复现的“工作方式”。大多数团队做技能失败不是AI不行而是人根本没有把自己的真实流程梳理清楚。所以我会说技能设计的第一步不是写指令而是观察自己。3.2 第二步把观察到的步骤翻译成AI可执行的语言拿到流程之后开始把它翻译成SKILL.md里的步骤。这中间有个“翻译”的窍门尽量把模糊动词换成可验证的行为。比如“检查语言风格”这种表述AI没法操作。我会改成“检查正文是否包含口语化表达如‘搞定’‘没啥问题’等若出现替换为书面表达”。再比如“人工扫一眼Issue列表”我会改成“获取未关闭且优先级为高或紧急的Issue列表剔除状态为In Testing的条目”。修改的原则很简单把“人脑中的隐性判断”变成“AI可验证的显式规则”。这一步做得越细AI执行得越稳定。这也是为什么同一个技能包不同人写效果千差万别。3.3 第三步用示例输出校准一次给够正反例在写完SKILL.md正文之后我会投入相当多的时间去打磨references下的示例文件。这个环节经常被跳过但它恰恰是性价比最高的。大模型的few-shot能力很强给它一份标准示例它生成的输出会迅速向示例的风格靠拢。我甚至建议示例文件里同时包含“正面示例”和“反面示例”。正面示例展示正确结构反面示例展示常见错误——比如某段风险描述太空泛、某部分遗漏了具体数据。两面夹击AI的错误率会降得非常明显。下面是我在周报技能中用到的一个反面示例片段反面示例风险描述 原文本周项目进度有风险。 问题未说明风险的具体内容、影响范围、计划如何应对。 修改后由于第三方支付接口联调延迟预计订单模块测试进度将推迟2天已协调后端资源优先支持计划下周三前完成。 ## 3.4 第四步测试不是“跑一下”而是持续追问“哪里偏离了预期” 技能包写完后测试环节不能省。第一轮测试我一般会把AI当作什么都不知道的新同事把技能包完整丢给它然后观察它在不看教程的情况下能不能独立完成一次任务。 测试的关键不是看“最终输出对不对”而是看“过程中哪里偏离了预期”。比如AI可能跳过了步骤二直接把所有提交记录堆在一起又比如它可能自作主张在报告里加了一段本不该存在的“本周感悟”。这些偏离就是迭代技能的靶点。 为了系统性地发现问题我会准备一组固定的“验收用例”。比如用户只给了周报两个字用户给了具体日期区间用户要求只汇总某个模块用户额外要求增加数据图表。每种输入都是一次独立的测试观察AI是否在各个场景下都保持稳定的输出格式。 ## 4. AI到底如何“记住”你的工作方式技能发现、加载与调用的实际链路 很多人以为“让AI记住工作方式”就是把技能包放进某个目录剩下的事AI自动搞定。实际上AI对技能的“记忆”是一个有先后顺序的链路理解这个链路才能解释为什么有些场景下技能不被触发有些场景下技能被错误地触发。 ### 4.1 技能发现让AI在恰当的时机想起可用的技能 在整套机制里最容易被忽视的是“技能发现”这个前置环节。AI不会每次对话都扫描一遍所有技能包的内容——那样既费Token又让上下文变得臃肿。它通常的做法是先读取所有技能的元信息描述当用户的请求与某个技能描述匹配时才加载这个技能的完整内容。 这就要求技能的元信息写得足够“像用户会说的话”。比如技能描述里写“当用户要求生成本周工作汇报时使用”那用户说“给我写个周报”AI大概率能匹配上但用户如果说“帮我整理一下这周的产出”描述匹配成功的概率就不好保证了。这也是为什么我前面反复强调元信息描述要尽量多地覆盖同义表达。 实际项目里随着技能数量增多这个环节还会遇到一个很现实的问题AI在技能发现时读到的只是描述信息它可能同时匹配到多个技能而不知道选哪个。这时候技能设计阶段的边界定义就变得极为重要。 ### 4.2 技能加载与上下文注入把完整动作规范放入对话 一旦技能被命中AI会读取该技能对应的资源文件并把关键内容注入到当前对话上下文中。这里需要注意加载不是简单地把文件内容“堆进”对话就完了。好的实现会对内容做结构化处理优先加载SKILL.md正文脚本只读取目录结构和调用方式说明示例只有当需要生成最终输出时才被完整引用。 这种分层加载的好处很明显。一方面对话上下文不会因为加载了大量脚本代码而变得拥挤另一方面重要指令SKILL.md正文始终占据显要位置不容易被子节点信息淹没。 我在实际调试中最常遇到的问题是脚本内容被完整塞进上下文后AI的注意力明显分散甚至开始修改脚本里的代码逻辑。后来调整了加载策略只告诉AI“存在scripts/fetch_git_stats.py它接收日期参数返回JSON格式的统计结果”AI就不再“手痒”去改脚本了。 ### 4.3 冲突处理与优先级多个技能指向同一任务时的选择逻辑 技能越来越多之后另一个问题浮出水面多个技能的描述可能指向同一个任务。比如团队里同时存在“周报技能”和“项目汇报技能”用户说“生成本周项目汇报”两个技能都可能被触发AI到底该用哪个 目前的策略是在技能元信息里增加“适用边界”和“优先级”。比如项目汇报技能的描述里注明“当汇报对象为外部部门负责人时使用本技能”周报技能描述里注明“默认场景使用本技能”。这样一来AI在发现阶段看到两者同时匹配时能根据用户请求中的细节做筛选。 如果两个技能的边界实在无法清晰划分我的建议是直接合并成一个大技能。技能包的粒度过细除了增加维护成本还会严重降低技能自动命中的准确率。这一条在后面避坑部分再展开说。 ## 5. 真实落地后的避坑记录技能膨胀、上下文污染与回归测试 技能包的编写方法已经有了但离“稳定运行”还有一段距离。下面这几条是我在持续维护技能库三个月后总结出的实战教训每一条几乎都是用踩坑换来的。 ### 5.1 技能膨胀AI的技能列表越长技能自动命中率反而越低 一开始我恨不得把团队的每一个操作习惯都做成技能周报技能、文档排版技能、接口文档生成技能、数据库命名检查技能……技能数量一多问题立刻出现了。AI在做技能发现时需要扫描所有技能的元信息描述描述越多混淆概率越高。用户说“帮我写个数据库表结构的说明文档”系统可能同时命中“接口文档技能”和“文档排版技能”。 我在某次测试中让AI“整理接口字段说明”它错误加载了“数据库命名检查技能”输出格式完全不对。排查后才发现两个技能的元信息描述高度重叠。 解决的办法很朴素**技能宁少勿多每个技能的覆盖范围宁大勿小。**一次功能迭代尽量合并相关技能同时为技能的触发添加显式的“排除条件”。比如在元信息里写明“当请求仅为生成表格格式时不要使用数据库命名检查技能”。这一行排除说明命中准确率的提升效果立竿见影。 ### 5.2 上下文污染示例和参考文档加载不当反而干扰输出 这是最隐蔽的问题。给技能包加示例文件时我总觉得示例越多越丰富AI越不容易错。后来发现示例太多反而带偏了输出。 原因是大模型天然倾向于模仿最近看到的文本结构。如果我在references里放了三份示例AI在生成最终输出时有很大概率去模仿其中某一份较长的、结构最复杂的示例而不是严格遵循SKILL.md正文里的规范。有一次生成周报它竟然模仿了示例中一份“管理层汇报”的格式加了一堆本不该出现在日常周报里的总结性标题。 修复方式有两个层面。第一示例文件控制在1到2份且使用场景要与最终输出一致第二在SKILL.md里明确提示“示例仅代表内容组织方式不要复制示例中的具体措辞”。两层约束加在一起问题基本消失。 ### 5.3 每次修改SKILL.mdAI却还在按旧行为执行缓存与版本更新问题 这个问题在实际迭代中最恼火。我每次调整完SKILL.md内容后重新启动新会话测试发现AI的行为依然是修改前的旧逻辑。反复测试好几次几乎要怀疑是不是改错文件了。 后来排查下来是技能缓存机制在作祟。部分实现会对技能包内容做快照或缓存文件更新后缓存没有自动失效。解决办法有两种一是手动清理技能缓存或重启服务二是为技能目录加版本号字段比如在元信息里增加version: 2强制触发技能重新加载。 这件事给我的经验是**每次改完技能包别急着下结论先确认AI读到的是不是最新版本。**可以故意在SKILL.md里加入一行仅在测试时出现的标记然后看输出里是否包含这个标记以此判断缓存是否更新。 ### 5.4 无回归测试的迭代等于裸奔把“验收用例”变成常规资产 技能维护最核心的一环是回归测试。这个想法来源于一个让我印象深刻的bug某次我只改了“输入要求”的字段让用户可选填模块名称结果其他步骤的AI行为全部发生偏移。出问题时才意识到这次的改动虽然没有更动输出格式但因为它影响了AI对任务的整体理解连带输出结构也变化了。 从此之后我把回归测试固化成流程。每次改动技能包我会跑一遍预先准备的验收用例逐个确认输出没有回归。我开始用一个简单的表格来追踪各用例的状态 | 用例场景 | 预期行为 | 上次结果 | 本次结果 | | --- | --- | --- | --- | | 只输入“周报” | 默认拉取本周数据生成四段式报告 | 通过 | 通过 | | 指定日期区间 | 报告范围与指定区间一致 | 通过 | 通过 | | 指定模块名称 | 报告仅汇总该模块数据 | 通过 | 通过 | | 要求附加图表 | 报告末尾附数据表格示例 | 通过 | 待验证 | | 输入包含“近期” | 不触发技能按普通对话处理 | 通过 | 通过 | 这张表看起来简单但它是让技能包从“能跑一次”变成“能长期稳定跑”的关键。如果技能包会被团队其他人共享这张表更是必不可少——否则别人在不知道影响面的情况下乱改技能内容大概率会把一个原本稳定的技能改坏。 ### 5.5 团队协作技能包要当成代码来管而不是当作文档来存 最后一条经验是关于协作方式的。团队开始共享技能库后我逐渐意识到技能包的维护方式应该更接近“代码仓库”而不是“文档库”。 理由是技能包会不断迭代。某个同事为了让AI多输出一段“经验总结”直接改了SKILL.md正文。第二天别人用的时候发现周报里多了一段他根本不需要的总结。这种情况本质上就是没有版本管理带来的混乱。 所以我会建议技能包目录必须纳入版本管理每次修改走评审流程至少包含一个“技术负责人review”的环节。评审看什么主要看三点技能边界是否被破坏、触发描述是否被削弱、示例是否与实际输出保持一致。这套流程跑顺之后团队协作的效率反而提升明显因为大家不用再反复跟AI解释工作方式一切约束都沉淀在技能包里。 ## 最后分享一点我的体会Agent Skills的价值不在于“写”,而在于“持续维护” Agent Skills这个方向的价值我用了三个多月才真正想明白。它不只是一个技术概念而是一种“让经验可沉淀”的思维方式。第一次把周报技能做出来时我只觉得新鲜但当这套机制运行了一个月、两个月团队的新同事用同样的技能产出的周报和老员工写的几乎一模一样的格式和语气时我才真正感受到“工作方式被记住”这件事的力量。 如果你正准备尝试我只有一条最实在的建议从最小粒度开始。不要一上来就做几十个技能挑一个每周都要重复两三次的任务把它做成第一个技能包跑通一整个迭代周期。先体验一遍“观察—拆解—结构化—测试—维护”的完整闭环然后再扩展。技能包的复杂度会随着使用次数增加而自然增长但如果你一开始就追求包罗万象大概率会像我一开始那样被技能膨胀和上下文污染两个问题同时打回原形。 我个人现在的习惯是每完成一个阶段性迭代都会花二十分钟把过程中的“什么描述导致了什么行为”记录下来。这些备注当时看没什么用但两三个月后回头看恰恰是它们让技能包在经历多轮改动后依然能保持最初那种“懂你的工作方式”的稳定手感。