最近在好几个技术社区都看到同一个问题为什么我给了 AI Agent 一份 3000 字的 Skill 指令它还是经常“犯低级错误”底下的回复五花八门但有一条让我印象深刻——“你这不是在写 Skill你是在写论文。”这句话点醒了我。过去大半年我一直在折腾各种 Agent 项目从日志分析到 PPT 大纲生成前前后后写了几十个 Skill。最开始我也走过纯堆指令的路子把格式要求、语气要求、禁忌事项、输出规范全部塞进去结果发现指令越长模型反而越容易“失焦”。后来我慢慢摸索出一个核心原则写 Skill 的本质是设计注意力而不是堆叠指令。这篇文章我想把这段时间积累的经验完整梳理一遍。不管你是刚开始接触 Agent 开发还是已经写过不少 Skill 但总觉得效果差一口气这篇内容都值得你花十分钟看完。1. 为什么堆指令是最容易踩的坑1.1 指令越长注意力越分散先讲一个我早先踩过的例子。当时我在给一个内部用的日志分析 Skill 加功能需求是让模型从 Nginx 日志里找出 5xx 错误、统计 Top 10 慢接口、识别异常 IP。一开始我写得非常“周到”把每个子任务的执行步骤、每个指标的计算公式、输出表格的每一列都写进指令里整个 Skill 文件接近 4000 字。实测效果出乎意料地差。模型确实能把 5xx 错误挑出来但表格格式开始“自由发挥”让它分析慢接口耗时变化它会一本正经地编造出“环比上升 23%”这种原文里根本没有的数据。后来我想明白了一个道理当前模型处理长文本的能力是有上限的。指令越长每个字被有效注意到的概率就越低。就像你在一个嘈杂的房间里同时喊十个人说话听众反而谁的话都听不清。堆指令看起来是在“增加约束”实际效果却是“稀释注意力”。1.2 冲突性指令制造认知负担堆指令还有一个更隐蔽的问题指令之间可能互相冲突。比如你同时写了“分析要全面覆盖所有维度的数据”和“输出要简洁不超过 200 字”这两条在模型看来就是互相矛盾的。模型为了“满足”两者最后往往交出既不够全面、也不够简洁的四不像结果。更典型的是“不要做某事”这类否定式指令。我与不少做 Agent 的朋友交流后发现一个共同经验当你反复强调“不要编造数据”时模型反而更容易在不确定的地方“编造”。因为“不要编造”这个词本身就把“编造”这个概念推到了注意力前线。这类问题在认知心理学里叫“白熊效应”——越是让你别想白熊你脑子里越全是白熊。写 Skill 时如果不注意这一点效果就会同样离谱。1.3 不可维护的“指令屎山”纯堆指令还有一个非常现实的代价维护成本极高。我自己见过一个团队维护的半成品 Skill文件里有 40 多个 if-else 式的规则段落每加一个新需求就在末尾追加一节。到后面没有任何人敢动这个文件因为“删一行都可能弄坏某个隐蔽功能”。这类层层堆叠的文档本质上是把“思考责任”全推给了模型而放弃了自己作为设计者的判断力。真正靠谱的 Skill应该像一份精美的地图让模型一眼就看清重点在哪、路径在哪而不是像一本 500 页的用户手册翻到后面已经忘了前面讲什么。2. 设计注意力的底层逻辑2.1 从“命令式”转向“引导式”思维如果说堆指令是在“命令”模型做事那设计注意力就是“引导”模型关注正确的事情。这两者的差别用一个比方来说堆指令像是给一个新手司机写了一份“开车注意事项清单”从“起步要打左转向灯”到“高速上不要猛打方向”全都写上司机根本记不住设计注意力则是给他一张清晰的路牌告诉他“前方 500 米右转进匝道”“下个出口是服务区”只引导他关注此时此刻最重要的事。落到 Skill 撰写上就是不要试图告诉模型“每一步都要怎么做”而是通过结构调整让模型自然地把注意力放到“这一步最关键的输入和输出”上。2.2 用情境信息收窄焦点模型对 Skill 的理解很大程度上由它“看到的第一屏内容”决定。所以我现在的每个 Skill 文件都强制要求写上清晰的元信息头包括触发条件什么时候该用、输入格式需要什么数据、输出风格最终交付形式。不要小看这一段像“剧情简介”一样的内容。它相当于在模型工作之前先给它划定了一个工作区间。比如我写过的一个 PPT 大纲 Skill元信息里写着“本 Skill 适用于输入一段口语化录音转写稿输出 8-12 页的结构化大纲每页包含标题、要点、讲解备注三部分”。这短短一句话就把模型的注意力从“要不要顺便排版、要不要配图建议”这些发散方向拉了回来集中在“从口语稿提炼结构”这一件核心任务上。2.3 工作流拆分让注意力随时有锚点人工作的时候最怕的是“一堆活儿”一起压过来没有先后顺序。模型也是一样。你让它一口气干五件事它就容易“平均用力”每件事都干得浮于表面。我常用的解法是把 Skill 的执行流程拆成 3-5 个显式阶段每个阶段只交代一个目标。还是拿日志分析来说我不再写“先分析 A同时注意 B最后别忘了 C”而是拆成阶段一解析日志识别所有 5xx 和 4xx 状态码。 阶段二按接口维度聚合耗时计算平均响应时间和 P95 响应时间。 阶段三结合时间轴找出异常波动给出排查方向。每个阶段独立成段模型在一个时间点只需要聚焦一个目标输出的准确率明显上升这个改动我实测过很多次效果特别明显。3. 动手写 Skill一步一步实操3.1 定义触发条件和元信息一个 Skill 必须让人或让 Agent 路由系统一眼就能判断“该不该用这个 Skill”。所以文件开头的那一段元信息我建议用标准化的结构来写。我用 YAML frontmatter 的格式大概是这样的--- name: log-anomaly-analysis description: 适用于 Nginx/Apache 访问日志的分析场景。 trigger: 当用户提供一段原始日志或日志文件路径并期望了解错误状态、接口性能或异常流量时使用。 model_compatibility: claude, codex, deepseek version: 1.2.0 ---各位注意 description 和 trigger 这两段一定要写得“可被程序化判断”。Agent 系统的路由逻辑通常是靠关键词、语义相似度来匹配 Skill 的如果你的描述太过文艺比如“深夜亮起的屏幕前总有代码在叹息”模型很可能会跳过这个 Skill转而用通用能力死磕。描述不是写给人看的文学而是写给路由器和模型的“路标”。3.2 用 XML 标签做视觉锚点把元信息写完之后正文部分的第一个原则是不要写长段落要写短小的、带明确标签的模块。我发现模型对 XML 标签天然敏感。就像人在读文章时会自动注意加粗的标题一样模型对context、task、output_format这类标签的注意力系数明显比普通文本高。一个我实际用的日志分析 Skill 核心段长这样context 用户会提供一段原始访问日志字段包含IP、时间戳、请求方法、请求路径、状态码、响应时间、User-Agent。 /context task 识别异常流量和慢请求给出可操作的排查建议。 /task output_format 使用 Markdown 表格输出。表格必须包含四列时间范围、异常类型、影响接口、推荐处置方案。 /output_format编写时请注意标签之间不要放冗余解释。写“经过分析我们发现在一般情况下……”这类句子纯属浪费 token。每个标签内部只放模型决策所必需的信息。3.3 用 checklist 替代长篇大论在需要“检查”或“校验”的环节长段描述远不如 checklist 高效。原因是 checklist 天然带有“逐项核对”的暗示模型在按项执行时注意力会更集中。举一个我在“PPT 大纲 Skill”中的校验清单checklist - 每页标题是否为一句观点明确的短句而非单纯的“产品介绍”。 - 每页要点是否不超过 3 个且彼此不重复。 - 讲解备注是否覆盖了“为什么放这页、该页要起什么作用”。 - 全篇是否有至少 1 页涉及风险或待决事项。 /checklist像这种 4 条以内的短清单模型执行起来几乎不会跑偏。如果清单超过 7 条建议拆成多个阶段的子清单不然模型又会陷入“平均分配注意力”的陷阱。3.4 用 few-shot 示例代替抽象规则“写一句抽象规则”和“给一个具体示例”对模型注意力的引导效果差别极大。抽象规则需要模型自己“翻译”成具体动作中间就可能跑偏而具体示例相当于直接给模型划了重点照着这个样式来。举一个例子。我在写“会议纪要 Skill”时最初有一条规则叫“提炼行动项时要注意负责人和截止时间”。模型常常漏项。后来我改成参考格式 | 行动项 | 负责人 | 截止时间 | 依赖资源 | |--------|--------|----------|----------| | 完成接口联调 | 张三 | 周五 18:00 | 测试环境 |从此以后行动项基本没有漏过负责人和截止时间。如果你只能改一个地方来提升 Skill 质量优先补 few-shot 示例而不是补规则描述。4. 如何做减法与验证4.1 写完 Skill 后先删除 30% 内容我的一个朋友有个很“狠”的习惯写完 Skill 初版之后强制要求删掉 30% 的内容再交付。最初的初衷是嫌文件太长后来发现这招意外地好用——因为当你被迫删内容时你会开始思考“哪句话是真的不可替代”。推荐一个实操顺序先把 Skill 文件里所有“背景描述”“意义说明”“通用知识”类句子标黄。然后把“类似于”“相当于”“之所以这样是因为”这类解释性语句标黄。接着把与主流程无关的边界案例描述标黄。最后把标黄部分整体删除再跑一轮测试对比效果。大多数情况下删完之后效果不降反升。4.2 用测试日志反推注意力盲区Skill 写得好不好不能靠“感觉”要靠跑测试。我建议每个 Skill 都配一个简单的手动测试集3 个标准输入、2 个异常输入、1 个极端输入。每轮修改后都跑一遍把输出差异记录下来。如果发现模型在某个环节反复出错不要急着追加指令去“堵漏”而是回去检查是不是这个环节的信息在 Skill 里出现的位置太靠后、被前面的长文本挤占掉了注意力还是说这个环节缺少一个明确的输出示例我曾在“代码审查 Skill”里发现模型总是忽略“安全漏洞”检查环节。排查了很久最后发现原因是“安全漏洞”这个词被塞在了一个很长的段落中间前后全是并发问题、性能问题等其他内容模型根本没有注意到它。后来我把安全审查单独拆成一个阶段并在task标签里点名问题立刻消失。4.3 版本管理与 A/B 测试像管理代码一样管理你的 Skill 文件。我现在的做法是每个 Skill 都放进一个 Git 仓库每次修改提交前必须写清楚变更原因比如“把阶段数量和输出格式拆成独立段落减少指令稀释”。这样三个月后回头看你能清楚知道哪次改动对效果产生了正面影响。有条件的话可以给 Skill 做简单的 A/B 测试同一组输入分别跑 v1 和 v2把输出结果按“完整度、格式符合度、幻觉率、用户体验”四个维度打分。不用打分很精细1-5 分即可但要坚持记录。改版方向对不对跑三轮测试就能看出来。5. 常见问题与排查技巧实录5.1 写 Skill 时容易踩的坑自查表我把自己这一年来遇到的典型问题整理成了下表读者可以对照自查现象根本原因解决动作模型频繁忽略某条重要要求该要求被埋藏在长段落中间注意力被稀释把它单独拆成一个阶段或标签输出格式每次都不一样只写了“请按表格输出”没有给表格示例给一个具体的 Markdown 表格示例模型会编造超出输入范围的数据上下文里缺少“只能基于给定数据回答”的锚点在context标签首句明示“禁止外推”“不要做 X”反而导致出现了 X否定式指令把 X 推到了注意力中心改成“只做 A、B、C”的肯定式指令Skill 在其他模型上失效某个模型对特定格式不够敏感用兼容性最强的纯文本格式描述核心流程指令一多模型速度明显变慢输入 token 过长每次调用都消耗大量上下文压缩指令砍掉背景信息和通用知识5.2 一个“负优化”案例的完整复盘有一次我把一个“周报生成 Skill”从 v1 改到 v2自信满满地加了非常多的“输出风格要求”包括“语言要专业但不冷冰冰”“不要用感叹号”“每段不超过三行”“多用动词开头”等等总计加了 20 多条。结果 v2 的实测输出反而比 v1 效果差不仅语言变得生硬还经常出现“逻辑断裂”——每条输出都像是被格式化机器切成的等长碎片。复盘后发现问题恰恰出在我过度堆加了输出风格指令。因为每一条风格规则都消耗一部分注意力规则总数一多模型在生成时就要反复“对照规则”写作的连贯性和自然度被严重破坏。后来我把 20 多条风格规则压缩成两条核心导向“像资深同事在写文档不要像机器在填空”和“给结论再给理由不要给套话”v3 的效果立刻恢复。5.3 如何判断该“加内容”还是“减内容”新手最容易困惑的问题是不知道当前 Skill 该加东西还是该减东西。我个人用的是“三连问”判断法第一问模型当前最常犯的错误是“遗漏了某个关键点”还是“某个关键点理解偏了”如果是遗漏优先考虑增加结构比如加标签、加阶段、加示例如果是理解偏了优先考虑删减冗余描述把核心定义说得更直接。第二问Skill 执行一次需要消耗多少 token如果动辄上万大概率是过度设计了。真正好用的 Skill通常控制在 1000-2000 token 以内极端复杂任务也不要超过 4000。第三问如果让一个完全不了解上下文的新同事拿着这份 Skill 来干活他能只看一遍就上手吗如果他需要反复来回读那说明结构清晰度不够应该继续拆分而不是继续解释。5.4 不同模型对 Skill 的“口味”差异我在这几个主流模型上都跑过同一套 Skill讲一下真实体感差异Claude 系列对 XML 标签和 Markdown 结构的响应最稳定给它清晰的标签嵌套它基本上会严格照做Codex 系列在“工具调用”和“多文件操作”场景下表现最好但更容易忽略软性文字描述所以核心要求必须落到极具操作性的步骤上DeepSeek 系列对中文语义理解深但会在长语音记录类任务里倾向于“过度总结”需要更明确的保留粒度比如“保留原话中的时间、金额、人名”。这并不意味着要为每个模型维护一套独立的 Skill 文件而是在设计时留意“通用结构优先”。先把逻辑框架写稳再在最外层用一个“模型适配说明”标签标注不同模型下需要特别注意的执行细节。这样既省维护成本又不会出现“换个模型就彻底失效”的尴尬。一些工具链与协作建议6.1 本地管理 Skill 的目录结构Skill 文件多了之后最怕的就是找不着、改不动。我现在使用的目录结构很简单但非常好用skills/ ├── log-anomaly-analysis/ │ ├── SKILL.md │ ├── examples/ │ │ ├── standard-input.txt │ │ ├── edge-input.txt │ │ └── sample-output.md │ ├── tests/ │ │ ├── run-test.sh │ │ └── expected-output.json │ └── CHANGELOG.md ├── ppt-outline-generator/ │ ├── SKILL.md │ ├── examples/ │ └── CHANGELOG.md └── meeting-minutes/ ├── SKILL.md └── CHANGELOG.md每个 Skill 独立一个目录SKILL.md 是主文件examples 放输入输出样例tests 放自动化测试脚本CHANGELOG 记录每次改版日志。这套结构在个人项目管理、小团队协作里都非常顺手至少省掉了我一半“找文件”的时间。6.2 用版本仓库追踪 Skill 的“进化史”把 skills 目录放进 Git 之后我养成了一个习惯每次改完 Skill提交信息里必须写清楚“我观察到了什么现象我做了哪个改动预期解决什么问题”。这看起来是小事但三个月后回看历史记录时你会非常感激当时的自己。没有这些记录你很容易陷入“反复横跳”——今天删了一段明天又加回来完全凭感觉。我还有一个个人偏好每个月固定抽时间跑一遍所有 Skill 的测试集把输出结果的变化记下来。模型服务商经常更新底层模型同样的 Skill 在不同时间点跑出来的结果可能有肉眼可见的差异。日常维护不只是改 Skill 本身也要关注“环境和版本变化”对 Skill 效果的影响。6.3 从单点 Skill 走向完整 Agent 能力写好单个 Skill 只是第一步。真正让 Agent 能力升级的是多个 Skill 之间的协作方式。比如我的日志分析流程实际上是三个 Skill 串起来的第一个 Skill 负责解析日志并提取异常事件第二个 Skill 负责把异常事件放到时间轴上看趋势第三个 Skill 负责把结论整理成给管理层的摘要报告。每个 Skill 都只负责一个窄问题各自都能保持“注意力高度集中”。串起来之后整体的分析质量大大超过一个大而全的 Skill。我的体会是宁可维护三个 800 字的小 Skill也不要维护一个 3000 字的大 Skill。这一点对任何想深入 Agent 开发的朋友都非常有参考价值。最后分享一点个人体会写了这么多 Skill我最深的一条感受是好的 Skill 设计者更像是一个“注意力设计师”而不是“指令写手”。你要做的是理解模型如何分配注意力然后用结构、示例和标签去引导它把注意力放到该放的地方。这个思维方式比记忆任何具体的写作模板都更重要。如果你现在手头正有一个效果不太满意的 Skill我建议先从“删掉 30% 内容”开始试。删完之后跑一轮测试把输出对比一下你会发现“少即是多”在 Skill 撰写这件事上绝大多数时候是成立的。