30多个 Skill 装完那一刻我心里其实挺虚的。毕竟对大多数人来说Agent 装两三个定制技能就足够应付日常了而我直接塞了三十多个还给它们编了“岗位”——有人搞检索有人写代码有人改稿有人做测试甚至还有一个专门负责在写方案前先抬杠。结果跑了一两个月比我预期中顺很多。这个经历让我对 Skill 产生了完全不一样的理解。原来大家纠结的“装多少”“哪个好用”根本不是重点真正的问题是你有没有像安排员工一样给每个 Skill 划清楚职责边界、输入产出、协作关系。如果只是把一个又一个技能丢给 AI不让它们归属到具体的“岗位”里那装得越多系统越容易变得不可控。这篇文章想跟你聊聊我是怎么把 30 多个 Skill 组织成 8 个岗位的包括 SKILL.md 的写法、技能触发机制、跨岗位协作的编排逻辑以及运行之后踩过的坑。无论你是在用 Claude Code、Codex、Cursor还是自己写一套 Agent 工作流这套思路都应该适用。1. 为什么不是“装技能”而是“设岗位”1.1 Skill 不是外挂而是一份任务执行协议我先纠正一个常见误解很多人把 Skill 想成“给 AI 装一个外挂模块”装完以后 AI 就突然“会”做某件事了。这个理解不能说全错但它会让你后续的设计走偏。主流 Agent 客户端里的 Skill本质上不是一段独立运行的程序而是一个目录里面放一份SKILL.md说明文件以及可选的数据、脚本、模板等资源。当用户输入与这份说明的description匹配时Agent 会把这份说明读进上下文然后照着里面的步骤去执行。skills/ patent-assistant/ SKILL.md # 技能说明Agent 的“工作手册” scripts/ # 可选辅助脚本 references/ # 可选参考资料看懂这个机制你就明白了一个核心事实Skill 是给 Agent 的一份“任务执行协议”它的作用是约束流程、固定产出格式、沉淀你的高效做法而不是让 AI 平白多出一个大脑。所以我在设计时从来不想“要装一个会写专利的技能”而是想“我要定义一名专利助理的岗位职责用什么流程完成检索、用哪种格式汇报结果”。1.2 三十多个技能乱成一锅粥的真实原因开始我也走过弯路Skill 装多了以后出现的第一个问题是“互相踩脚”。明明我只是想让 AI 给这段代码补几个单元测试它却触发了项目管理技能开始一本正经地帮我写迭代计划。还有一次让它整理会议纪要它居然把质量复盘技能里的检查清单也套了进来一份纪要写得像事故报告。这个现象的根源不是 Skill 本身难用而是技能之间没有任何组织关系。所有技能都被平铺在一个列表里Agent 每次只能靠description去猜该用哪个。当描述写得太宽泛、边界模糊时误触发就成了必然。要解决这个问题不是少装几个而是给每类能力一个明确的“部门归属”。我后来把技能全部做了一次重组按岗位划分每个岗位只对特定任务负责岗位之间通过固定的协作链路衔接。这就像公司里研发、测试、产品各司其职而不是每个人都顺手干别人的活。1.3 岗位化依赖的两条纪律给 AI 设岗位我自己是这么理解的不是简单地把 SKILL.md 分类放进不同文件夹而是两份纪律约束每一个岗位第一每个岗位必须有唯一的职责。只有当输入明确落在它的职责范围内时才允许被触发。第二每个岗位必须有明确的产出契约。它收到什么、交付什么、以什么格式输出事先写在技能的验收标准里。按照这两条纪律来看凡是不能被安排进现有岗位的 Skill就坚决不装。这样“30 多个”听起来很多但它们都归属于 8 个岗位之下管理成本反而比之前 10 个散装技能更低。2. SKILL.md 怎么写才像一份真正可执行的“岗位说明”把 Skill 当岗位来设计后写 SKILL.md 就不再是随缘写提示词了。我写一份技能通常花的时间在 30 分钟到 1 小时其中小半时间在调描述大半时间在打磨正文里的流程与验收标准。2.1 入口决定一切name 和 description 是技能的路由标识一个 SKILL.md 开头是 frontmatter最核心的两个字段是name和description。很多人的 description 写得特别简单比如“用于专利检索”这就等于没有做路由设计。Agent 在执行任务时通常会读取所有技能的 name 和 description再判断哪个技能与当前用户意图最匹配。如果你的描述太宽泛或者里面包含的关键词和其他技能重叠误触发率会急剧上升。所以我会在 description 里尽量写清楚三件事什么时候用、什么时候不要用、主要处理什么类型输入。--- name: patent_search_assistant description: 当用户需要检索专利、分析专利权利要求、进行侵权比对或撰写交底书的现有技术部分时使用。不要将本技能用于普通文献综述或学术论文写作。 ---这是最容易被忽略但又最重要的细节。技能本身写得再好如果入口描述没写好它就像一位经验丰富的老员工却永远接不到真正需要他的工单。2.2 正文结构角色、流程、产出、验收缺一不可前端描述负责被“找到”正文负责让 AI “做对”。我在正文模板中固定保留五个块Role定义这个岗位在协作中的身份。Context说明通常在什么场景下需要调用这个技能。Process给出 4-8 步可执行的核心流程。Output明确交付物格式、文件命名、存放位置。Verification用验收清单检查结果不满足就重新运行。打个比方写 Process 相当于给新员工写标准作业程序写 Output 和 Verification 则是给他立下“干到什么程度算合格”的标准。如果只有流程没有验收AI 很容易以“已完成”的姿态交付一个半成品。2.3 一个专利助理 Skill 的完整写法参考因为我平时会处理不少专利交底书相关的内容这里用一个实际在用的技能做例子。这个技能叫patent_search_assistant归属在知识合规岗位里--- name: patent_search_assistant description: 当用户需要做专利检索、拆解权利要求、对比现有技术或评估一个技术方案的专利新颖性时使用。不用于商标、著作权、普通论文检索。 --- # 岗位角色 你是一名专利检索与情报分析助理。你的任务是辅助工程师完成专利检索并输出结构化报告。 # 处理流程 1. 确认技术方案提炼其中的核心组件、关键参数、创新点。 2. 生成检索式用关键词组合、IPC 分类号和申请人字段构建 3-5 组检索式。 3. 检索与筛选逐条评估检索结果保留与创新点相关的对比文件。 4. 对比分析把对比文件的技术特征与待评估方案逐一比对。 5. 输出报告按指定格式填写结果。 # 输出格式 使用 Markdown 表格输出 | 对比文件 | 相关特征 | 差异点 | 影响等级 | # 验收标准 - [ ] 检索式不少于 3 组 - [ ] 每个对比文件都标注了相关特征 - [ ] 差异点描述不使用“明显不同”这类模糊表述这里必须提醒一句这个 Skill 只负责辅助检索和梳理材料输出结果不能替代专业代理人或顾问意见。所有 AI 辅助产出的内容最终都要经过人的复核并加注辅助工具提示。合规使用是你自己的责任。2.4 哪些技能值得先写我的优先级排序不是所有东西都值得做成 Skill。每次想写新技能我会优先考虑三类第一重复度高的事情。比如每周都要做的代码审查、每篇稿子都需要的语气检查做一次就要沉淀一次。第二流程复杂且容易遗漏的事情。让 AI 自己临场发挥它总会在某个环节漏掉细节比如专利检索的歧义表述、测试用例的边界条件。第三涉及多人协作、需要统一产物格式的事情。相反那些需要灵感和高度依赖情境的事比如头脑风暴、起名、闲聊不建议都写成 Skill。把它们留给主模型的一般能力就好硬套流程反而会扼杀自然表达。这样你装的技能数量不一定会少但每个都确实值得存在。3. 我的 8 个岗位清单30 多个 Skill 怎么归队把散装技能变成岗位体系我第一步做的其实是“归队”。我把 33 个技能按岗位重新梳理了一遍然后把重复、过时、边界模糊的直接淘汰掉一批。3.1 八个岗位与技能方向速览先说岗位视角的分配我用一句话总结了每个岗位的职责以及对应支撑的技能方向岗位一句话职责可能覆盖的 Skill 场景典型产出物研发工程师把需求变成可运行代码项目脚手架、接口实现、重构代码、提交说明代码审查员找出代码里的逻辑缺陷与坏味道代码评审、安全扫描、风格校验审查意见清单质量测试员覆盖正常、异常与边界场景测试用例生成、Bug 复现、报告测试清单、缺陷报告文档工程师把技术内容转成清晰文档README 编写、API 文档、更新日志Markdown 文档专利与情报分析员做检索、对比与风险提示专利检索、交底书梳理、TRIZ 辅助检索表、对比报告算法建模助理辅助数学建模与数据分析数据清洗、模型选型、论文排版建模文档、图表内容创作策划产出脚本、字幕、分镜与创意文本短剧脚本、直播提纲、图文文案脚本、分镜表表达与陪伴教练辅助练习语言表达、复盘思考英语对话、演讲反馈、复盘提问反馈记录、复盘报告不要小看这张表。它最大的作用是当我拿到一个新需求时能第一时间判断该让哪个岗位接活而不是临时去翻技能列表。每个岗位内部有一组技能形成一个子任务池AI 在岗位内选择具体技能而不是从 33 个技能里大海捞针。3.2 研发链路里的四个岗位研发工程师、代码审查员、质量测试员、文档工程师这四个岗位是一条完整交付链。以前我让 AI 写代码就是简单一句“帮我实现一个什么功能”得到的代码经常要返工。后来我发现问题不在生成质量而在于没人“验收”。把代码审查员和质量测试员设为独立岗位后研发工程师写完代码代码审查员按坏味道清单逐项检查质量测试员再补充测试用例整个交付质量立刻上了一个台阶。比如让研发工程师生成一个工具函数它会遵循一套我沉淀在技能里的“最终输出规范”包括函数签名、类型定义、注释格式和调用示例。然后代码审查员会自动检查变量命名、循环边界、异常处理和安全性问题。最后质量测试员会列出不少于 5 条测试用例覆盖正常路径、空输入、超长输入和异常分支。这套岗位链路的本质是把“一次生成完美结果”的期望拆成“多个专业角色各自负责一段”的流水线。单项任务看起来变多了但总体返工次数大幅下降。而且每个岗位都可以独立复用。下次不需要写代码只想要审查意见也可以单独叫出代码审查员。3.3 创作、分析与陪伴类岗位的设定思路后四个岗位偏向知识密集和创意内容它们的设定思路很不一样。专利与情报分析员、算法建模助理这类岗位重流程、重证据。每个结论都必须有依据因此技能里强制要求输出检索式和对比表。内容创作策划岗则相反重结构、轻步骤。AI 一旦被步骤约束太死产出会非常机械。所以给这个岗位的 Skill 我会只写三条规则第一先给三个不同角度的创意方向第二用户选定后再细化脚本第三每段脚本必须标注画面和台词时长。它更像编导的副手负责把大脑里的片段快速落成可用文本。表达与陪伴教练是我最晚加的一个岗位。它的定位不是提供标准答案而是通过提问帮我把想法梳理清楚。比如我丢给它“今天工作有点乱”它会先让我描述具体场景再从优先级、精力分配、目标偏差三个角度追问最后生成一份复盘的框架。这种技能写起来很克制不能要求 AI 输出长报告否则就变成了说教。3.4 Skill 不是越多越好但可以越分越细我有 33 个 Skill但如果你凑近看会发现它们不是 33 个完全不同的能力而是 8 个岗位下不同场景的分支。比如研发工程师岗位下挂着脚手架生成、API 接口实现、数据迁移脚本三个技能表达教练岗位下则分英语对话陪练、演讲结构反馈、复盘提问三个技能。这样做的好处是每次新增一个子技能时我不需要为它重新设计岗位逻辑只需要挂靠到对应岗位并保证和同岗位其他技能的描述差异足够大即可。反过来如果一个需求触发了好几个同岗位技能我会判断是不是该合并而不是任由它们继续膨胀。4. Agent 怎么从 30 多个 Skill 里找到正确的那一个技能数量变多以后很多人会担心性能问题每次对话模型是不是都要把所有 SKILL.md 都读一遍答案取决于具体实现但我们要避免这种想当然的设计。在多数主流实现里Agent 会先扫描 name 和 description 做预筛选只把命中的技能内容载入上下文。所以真正影响命中率的还是怎么组织 system prompt以及每个技能的 description 写得是否清晰。4.1 用“触发条件”代替“技能名称”描述技能时我很少采用“xxx 技能”这种命名。例子description: 当用户给出代码片段并要求做代码评审或提到“这段代码有什么问题”“代码异味”等表述时使用。当目标是完成新功能开发时不应使用本技能。这些“应该触发”和“不该触发”的说明是我使用所有技能里最有价值的部分。它们像岗位说明书里的“职责边界”可以明显降低互相干扰的概率。你可能会想只要把“不该触发”写进 description模型的扫描不是就更长了吗没关系需要覆盖的是高频常见情形而不是穷举所有句子。4.2 跨岗位协作让 Agent 学会“传文件”第 3 节提到的研发链路本质是多个岗位之间的接力。这里我建议用文件作为岗位之间传递信息的容器而不是让 AI 在上下文里背着一长串对话记录。我会在工程目录里建一个workbench/artifacts/文件夹约定每个岗位交付时把结果写入独立文件workbench/ artifacts/ 01-requirement.md 02-code-review.md 03-test-plan.md当一个任务从需求走到代码审核时研发工程师先写出01-requirement.md审查员读它后产出02-code-review.md测试员再基于前两者写03-test-plan.md。通过文件传递可以避免模型被之前的无关对话干扰也便于你随时查看每个岗位的真实产出。我在日常使用时还通过一个“协调者”模式把它们串起来这个协调者不负责执行任何具体岗位任务只负责拆解用户一句话需求并规划工单顺序。例如你输入“把这段代码重构并加测试”协调者判断需要的是代码编写、代码评审、测试生成三步然后依次调用对应岗位。4.3 上下文开销从哪来又该如何控制Skill 的真正上下文开销并不在“扫描 description”阶段而在于技能正文被读入后的长度。如果你一个 SKILL.md 写了几千字里面还有大量背景资料那么每次命中它都会消耗大量 token算力和成本双高。我的 SKILL.md 正文通常控制在 300-600 字核心流程能简则简长资料放到 references 文件中按需再读。文件路径在正文里写明即可Agent 执行到那一步时才主动读取。这样技能数量多的成本就变得可接受。4.4 手动编排与自动路由哪个更实际我给 AI 安排岗位之后最常被问到的问题是你是让 AI 自己决定用哪个 Skill还是每次手动指定答案是两者混用。当一个任务涉及多个岗位且链路固定时我会在 prompt 里明确调用比如“请让研发工程师生成代码然后代码审查员检查质量测试员补充测试”这样 AI 就会逐个搜索对应岗位下的技能。当任务边界比较模糊时我更倾向于让协调能力强的 Agent 自己先判断该用哪一组岗位它会在对话中列出自己的选择逻辑我再确认。实验过后我的感受是不要把所有决策都丢给 AI也不要所有环节都手动指定。最佳状态就像带团队 —— 主管知道员工擅长什么只在关键节点给方向剩下交给员工自己选择执行手段。5. 运行 30 多个 Skill 之后我最常处理的四类故障任何实践都会遇到运行时问题。我使用这套岗位制一个多月遇到最多的是四类问题每一次都让我对 Skill 的理解更深一层。5.1 技能误触发先问一句“你为什么选它”有一次我让 AI 写一份数据分析报告的总结摘要结果它把“表达与陪伴教练”岗位下面一个复盘 Skill 给调用了生成的内容完全偏向个人复盘视角用了大量“下一步行动计划”把一份中性摘要写得像个人成长规划。排查时我直接在对话里追问了它一句“你为什么选择这个技能”它把该技能的 description 列出来我立刻发现原因——我在那个复盘技能描述里写了“当用户需要总结一天或一件事时使用”而“总结摘要”和“总结复盘”在语义上撞车了。这个经历让我养成了一个习惯任何误触发第一时间回去看 description 里的“当”条件。如果一句话可能被多种岗位接收就改写得更精确加否定条件。5.2 流程执行了结果却不符合预期技能有时候走完了 Process但出来的结果还是不像样。最常见的原因是流程步骤只写了“做什么”没写“按什么标准做”。比如测试岗位的 Skill如果流程只写“生成测试用例”AI 很可能只列出十几个正常用例完事。后来我在流程里加了一句“必须包含至少 2 个异常输入和 3 个边界值测试”效果立竿见影。这个细节说明给 AI 写流程本质上和给新员工写 SOP 一样只写步骤是不够的要写清楚合格标准否则每个人都会按自己的理解去做。5.3 跨岗位协作时Agent 容易丢掉前面岗位的产出物在我刚开始用文件传递时经常遇到下一步岗位没读取上一步产出就直接开始的现象。随后我要求每个岗位步骤的前两步固定为“读取指定工件并简要复述其中关键信息”然后在技能验收标准里增加一条“输出应引用上一步文件的具体内容或行号”。这个改动看起来简单却让岗位间的信息失真问题大幅缓解。5.4 不要试图用 Skill 突破边界合规设计更重要还有一种特殊故障给 Skill 写某些“越界”或边界性质的规则。这类内容在短时间里看起来能让模型更听话但长期会削弱模型的稳定性和安全性。实操中我曾尝试让一个用于生成宣传文案的 Skill 放宽审核边界结果模型表现出更多随机错误输出质量反而明显下降。从那以后我遵守两条原则第一Skill 只定义“如何把事做好”不影响内容的合规边界第二任何输出只要触及立场、健康、专业责任保留人工复核环节。如果你把 Skill 看成岗位你就会明白一个好的员工不会为了完成 KPI 去突破公司的合规底线。AI 辅助的角色也一样。6. 一套岗位制用了一个月之后的个人体会这一个月跑下来我最大的体感变化其实是我很少再想“我装了 33 个 Skill 够不够”而是开始想“我的 8 个岗位之间还有哪些环节漏掉了”。以前我评价一个 AI 助手会看它能做到多少种事现在我会看它是不是像我安排的那几个岗位一样有边界感、有稳定的产出格式、知道什么活不归自己干。这个转变挺奇妙的你会发现 AI 不是变得越来越“聪明”而是变得越来越“职业”。对于想尝试这套方法的你我有一个小建议不要一上来就照着我的 8 个岗位抄。你可以先把现在常用的任务列出来归类成 3-5 个岗位每个岗位用 1-2 个 Skill 支撑跑一周再新增。数量从来不是衡量 Skill 体系好坏的标准标准是你能不能快速判断一个问题该由哪几个人协作完成以及每个岗位交出的是不是你想要的东西。最后分享一个提升整体效率的小技巧在项目顶层维护一份SKILL_INDEX.md索引文件相当于团队的“花名册”。每当 AI 不确定要调用哪个岗位时我让它先读这个索引文件再决策。这个方法帮我减少了大量误触发。说白了员工多了以后谁都需要一个值班表AI 也不例外。我现在还在继续调这些岗位的边界与协作方式。等后续遇到更多有意思的边界情况和细节再拿出来和大家继续聊。