过去半年GitHub 上最热闹的方向之一不是某个新的模型权重也不是某个推理框架的版本更新而是一堆名字里带 superpowers、deepseek-harness、awesome-agent-skills 的仓库。这些仓库不写传统意义上的 README不靠漂亮的首页截图吸引人而是塞满了各种 markdown 文件——文件的内容不是给人看的项目介绍而是写给 AI 看的“操作手册”。这件事听起来有点反直觉文档不是给人看的吗怎么突然变成了给模型看的但如果你真的上手去拆过几个这样的仓库你会发现这确实是目前让 Agent 真正“能干复杂活”的最有效路径之一。今天这篇我想从 superpowers 和 deepseek-harness 这两个典型项目切入聊聊“写给 AI 看的文档”到底该怎么写、技能包该怎么设计以及踩过哪些坑之后我才搞明白的关键点。1. 为什么“技能包”突然成了风口1.1 从“模型会聊天”到“模型会干活”的鸿沟先讲一个我自己的观察。大概一年前我用各种大模型做事情还停留在“对话式”的范畴写一段文案、改一版代码、解释一个概念。这些任务的特点是模型只要理解自然语言输出自然语言或代码片段就行上下文一两千字就能搞定。但到了今年大家开始让 Agent 做真正的“项目级”任务让它维护一个代码仓库、让它跨多个 API 协调完成数据采集、让它根据一个模糊的目标自己规划执行步骤。这时候问题就来了模型确实聪明但它不知道你的项目结构、不知道你约定的代码风格、不知道哪些操作是危险的、不知道完成到什么程度算“好”。它就像一个能力很强但完全不了解公司规矩的新人你光说“去把这件事办了”它大概率会办砸。这时候出现了两条解决路径。一条是给 Agent 装各种工具function calling / tool use让它能调用搜索、读写文件、执行命令另一条是给它喂“技能”——成套的结构化指令告诉它特定场景下该按什么步骤做什么事。前一条解决的是“手”的问题后一条解决的是“脑”和“流程”的问题。技能包就是后一条路径的产物。1.2 superpowers 和 deepseek-harness 的两个方向superpowers 这个仓库的思路很有意思。它的作者没有把技能做成“单一 prompt”而是把技能拆成了一堆 markdown 文件每个文件聚焦一个具体能力比如“如何拆解复杂问题”“如何写高质量 commit message”“如何进行代码审查”。这些文件不是给人读的教程而是设计给 Agent 在特定场景下自动“想起来”要用的操作规范。deepseek-harness 则是另一个方向它更像是一个“让 Agent 正确使用某个模型能力的脚手架”。这个名字里带 deepseek但它做的事情其实很通用——它把调用模型、处理上下文、组织工具调用这些杂事封装成一个 harness套具让上层 Agent 可以专注于业务逻辑。它包含的文档和配置本质上也是在“告诉 Agent 怎么用这个 harness”。这两个项目放在一起看其实点明了技能包的本质不是给模型多一点知识而是给模型一套“行为准则”和“操作流程”。模型的知识早就够了缺的是约束和引导。1.3 技能包和传统 prompt engineering 的区别很多人会问这不就是写 prompt 吗我觉得区别挺大的。传统 prompt engineering 是“在对话里把话说清楚”技能包是把“行为准则”从对话里抽出来变成独立的、可复用、可版本管理的资产。对话里的 prompt 会随着上下文漂移而且没法系统性地测试和迭代。技能包不一样——它像代码一样有结构可以被懒加载可以根据任务类型选择性注入可以被多个项目复用。我在实际使用中体会最深的一点是技能包解决的问题不是“模型听不懂”而是“模型不知道该按什么流程做事”。模型缺的不是智力是“组织纪律性”。而组织纪律性恰好可以用结构化的文档来灌输。2. 写给 AI 看的文档到底该怎么写2.1 文档的对象不是人是模型——写法完全不同刚开始尝试写技能文档的时候我犯过一个错误我是按“写给人看的教程”的思路来写的结果 Agent 执行效果很差。后来我意识到一个问题人看文档的时候会跳读、会脑补、会根据上下文自动理解省略的内容模型读文档的时候是“逐字逐句”地处理它不会被“你懂的”这种表述自动补全信息。所以写给 AI 看的文档核心原则是把一切默认的、隐含的、需要脑补的内容全部显式化。举个例子。写人看的教程说“打开配置文件修改端口号”人知道配置文件大概在哪、端口号大概长什么样。但给 AI 看就得写清楚配置文件的具体路径是/etc/app/config.yaml需要修改的字段叫server.port原来的值是8080改成9090改完之后需要执行systemctl reload app才能生效。每一处都要落到确定的路径、字段名、命令、预期结果。2.2 技能文件的结构设计基于 superpowers 这类项目的经验我整理出了一套自己常用的技能文件结构。它不一定适合所有场景但至少给了一个可以参考的骨架文件头是元信息区。这里写技能名称、适用场景、触发条件。元信息的目的不是给模型读内容而是给 Agent 的调度层判断“这个技能什么时候该被加载”。没有元信息Agent 面对几十个技能文件时根本不知道该用哪个。正文第一部分是目标描述。明确“这个技能完成之后应该达到什么状态”。注意这里要用可验证的描述比如“所有测试通过”“生成的报告包含三个部分的统计数据”而不是“完成得很好”“尽量优化”。正文第二部分是前置条件。列出所有在执行前必须满足的条件比如“目标仓库已经 clone 到本地”“依赖已经安装”。模型在执行前会自查这些条件不满足时会主动停下来请求补充信息而不是盲目硬跑。这一步非常关键它能避免大量无效操作。正文第三部分是执行步骤。每个步骤都要求包含四要素动作、对象、预期结果、异常处理。动作是“做什么”对象是“对哪个文件/哪个接口/哪个命令”预期结果是“做完之后应该看到什么”异常处理是“如果没看到预期结果应该怎么办”。这四要素缺一不可尤其是异常处理没有它模型就会在意外情况面前陷入死循环。正文第四部分是禁止事项。这一点很多人会忽略。告诉模型“不要做什么”有时候比“要做什么”更重要。比如“不要修改源码文件”“不要在没有测试的情况下推送代码”“不要删除未跟踪的文件”。模型的训练数据里包含了太多“人类可能希望我这样做”的猜测明确的禁止事项可以大幅降低执行风险。2.3 文档语言的去模糊化技巧写完结构再讲几个我实际打磨语言时用到的技巧这些细节对效果影响极大。避免程度副词。像“合理配置”“适度优化”“灵活处理”这类词人看了能理解模型看了等于没看。全都换成具体的量化指标“确保内存占用低于 512MB”“接口响应时间小于 200ms”“误差率低于 0.5%”。避免指代不清。写文档时不要用“它”“这个”“那个”指代前面出现过的东西。模型在处理长上下文时指代消解还是会有偏差。宁可在每个步骤里重复一遍对象名也不要怕啰嗦。写给 AI 看的东西啰嗦是美德。给每条规则加“因为”。不是只写“要这样做”还要写“为什么要这样做”。这一条是我从 deepseek-harness 的项目文档里学到的。模型理解了原因之后在面对文档没覆盖到的边缘情况时能做更好的推断。比如“先跑测试再提交代码因为未验证的代码会破坏主分支的稳定性影响其他协作者的开发”这句话让模型知道“跑测试”不只是一个机械步骤而是一个保护性行为。3. 技能包的核心——从 superpowers 里拆解出的设计模式3.1 技能的粒度设计拆 superpowers 的源码和文档时我收获最大的一点是它的“技能粒度”设计。它的技能不是一个大而全的“全能手册”而是拆成一个一个非常聚焦的小技能。比如“写代码”这个任务在它的体系里被拆成了“理解需求”“设计方案”“编写实现”“编写测试”“运行验证”“提交代码”等多个独立技能。这样拆的好处有三个。第一每个技能都能写得更深入、更具体因为聚焦单一职责时细节密度可以提高。第二技能之间可以灵活组合同一个“编写测试”技能可以被用到不同的项目里不用重写。第三模型在装载技能时只需要装载当前步骤需要的那个小技能不需要把完整工作流的所有约束都塞进上下文这样可以显著减少上下文占用让模型在长任务中保持更好的状态。我自己在实践时也踩过反向的坑一开始把所有要做的事情合并到了一个超长文档里结果模型越到后面越“忘事”前文定义过的规则在后期执行时经常被忽略。拆分成多个小技能之后这个现象明显缓解了。3.2 技能的加载机制与上下文管理技能包不是一股脑全塞给模型的。实际使用时需要一个“技能路由器”来决定当前任务阶段加载哪些技能。这个路由器通常会读取任务描述匹配技能的元信息把匹配到的技能文件内容插入到当前对话的上下文里。这里有一个很关键的工程点技能文件的长度控制。我给自己定的标准是单个技能文件的纯文本长度控制在 800 到 1500 字之间。太短则信息密度不够模型拿不到足够的执行细节太长则加载后挤占上下文空间影响模型对任务本身的注意力。如果需要更长的操作说明拆成多个技能文件用“前置技能”和“后续技能”的方式串联。另外要注意技能文件的加载顺序。我之前遇到过一个怪问题先加载了“代码风格规范”再加载“重构操作步骤”结果模型在重构时过度纠结格式问题忽略了重构本身。后来调整了顺序先加载主流程再加载约束性规范情况就好了很多。这背后的原因可能是模型对后加载的信息关注度更高所以把“操作流程”放在后面、把“背景知识”放在前面执行效果更稳定。3.3 可测试性与版本控制技能包的一大优势是它可以像代码一样做版本管理和回归测试。superpowers 的做法给了我一个启发每个技能都可以配套一个“验收场景”。比如“代码审查”技能有一个测试场景——构造一个包含三个已知 bug 的 demo 仓库让 Agent 使用技能执行审查如果三个 bug 都被识别到了技能就算通过验收。这个思路我认为是目前技能包最有价值的发展方向之一。没有验收场景的技能本质上只是“一段自我感觉良好的 prompt”改没改好完全靠感觉。而有了验收场景技能包就变成了可以持续迭代的工程资产。我目前的做法是给每套技能维护一个tests/目录里面放各种带已知问题的样例项目每次修改技能文档时都跑一遍测试集记录通过率。这个习惯帮我抓到了很多“看起来写得很顺但对 Agent 无效”的文档。4. deepseek-harness 给我的工程启示——技能不只是文档还是代码4.1 从文档到 harness补齐“执行层”的短板如果说 superpowers 偏重“给模型定义行为”那 deepseek-harness 则展示了另一层能力给模型提供一套稳定的“执行环境”。在这个仓库的设计里模型不是一个孤零零的对话接口而是一个被 harness 包裹的执行单元harness 负责管理上下文窗口、负责工具调用的生命周期、负责错误重试、负责把多步操作串联起来。这给我的启发是技能包要想在复杂任务里真正落地光靠“文档层面的引导”是不够的还得有“代码层面的约束”。举个例子我曾经在一个数据采集任务里给 Agent 写了很详细的技能文档告诉它怎么请求 API、怎么处理分页、怎么在限流时退避。但实际跑的时候模型经常在工具调用环节出问题——比如参数格式不对、连续请求失败后没有正确退出、上下文被无效输出塞满。后来我参考 harness 的思路在技能体系里加了一个“执行约束层”用代码封装工具调用用强类型定义工具参数用重试机制兜底网络错误。模型不再直接调用裸工具而是调用被封装过的安全接口。文档负责“告诉模型该做什么”代码负责“保证模型能安全地做到”。这两者配合任务成功率才真正上来。4.2 上下文窗口是 Agent 项目最大的隐形瓶颈在做 Agent 项目时我踩过最深的坑就是上下文管理。模型的能力上限在不断突破但实际工程里上下文窗口的“有效利用率”才是决定任务成败的关键。很多失败案例不是模型不够聪明而是上下文中塞了太多无关信息导致模型“注意不到”关键约束。deepseek-harness 这类项目让我意识到上下文管理不应该靠“写 prompt 时事无巨细地叮嘱”而应该靠工程手段去控制。具体来说有三件事值得做第一引入“信息分层”。把高频使用、不影响判断的固定信息放在更早的位置模型对这个位置的内容有较好的记忆把当前任务的关键信息放在靠后的位置模型对最近收到的信息关注度最高。第二做“核心上下文保护”。Agent 执行长任务时早期的重要约定会被后来的日志、中间结果挤出注意力范围。我现在的做法是在每轮工具调用之后把“当前任务目标”和“关键硬性约束”重新注入到最近的位置形成“提醒机制”效果立竿见影。第三对中间过程做“摘要压缩”。让 Agent 每完成一个阶段就生成一段结构化摘要把原始过程信息替换掉。这样一来上下文始终只保留“最新的关键状态”和“完整的摘要链”既不会丢失全局信息也不会被过程信息淹没。4.3 从 harness 里学到的“错误恢复”设计另一个让我受益很大的设计是“可恢复的错误处理”。在技能文档里写“如果出现异常请停止并报告”其实是不够的。更好的方式是为每个步骤预定义“恢复路径”。我现在会在技能文档里为每个关键操作附一个“错误恢复”段落比如这样如果请求 API 返回 429 限流等待 60 秒后重试连续三次失败则切换到备用数据源如果测试用例失败先读取失败日志定位是环境问题还是代码问题环境问题则修复环境后重跑代码问题则回滚到最近一次通过的提交并重新开始。把恢复路径写清楚之后Agent 在真实执行时的“自主存活能力”明显提升了不再一遇到小异常就中断任务等待人工介入。5. 从零搭建一套可用的技能包——实操全过程5.1 第一步定义你的 Agent 的职责边界动手写技能之前先想清楚一件事你的 Agent 是干什么的、不干什么的。这个边界不定义清楚技能文档就很难取舍。我看过太多的技能包项目写着写着就变成了“万能手册”什么都要管结果模型在处理任务时反而失去了优先级判断。我做技能包的第一版时会做一个“职责清单”。比如我要做一个“代码仓库维护 Agent”那我就列清楚它的职责包括代码审查、测试执行、依赖升级、issue 分类它的非职责包括对外发布版本、直接修改生产数据库、处理用户隐私数据。非职责列表会在技能文档的全局说明里反复强调同时在每个相关技能的禁止事项里再次出现。5.2 第二步任务拆解与技能映射确定边界之后下一步是把 Agent 会接到的任务类型拆解成“最小操作单元”。我会用一个简单的表格来做映射左边是任务场景右边是相关的技能文件。比如“处理新提交的 PR”会映射到“理解变更内容.md”“静态检查分析.md”“测试执行验证.md”“风险标注.md”这四个技能。这一步的关键是拆到“每个技能文件只需描述一个动作目标”为止。拆得太粗技能文件里会塞进多个阶段的内容模型容易阶段切换失败拆得太细文件数量爆炸调度复杂。实际经验来看一个中等复杂度的 Agent20 到 40 个技能文件是一个合理的规模区间。5.3 第三步技能文件的撰写与打磨写技能文件时我建议按下面的顺序操作。先把流程草稿按“目标-步骤-验收标准”三要素写出来然后对照前文说的“避免程度副词、避免指代不清、给规则加因为”三个技巧进行第一轮语言打磨接着把草稿扔给一个普通的对话模型故意让它执行一遍看看它在哪些地方产生疑问或偏离根据疑问点补充文档中的“遗漏信息”再扔回去测一遍。这个“写→测→补→再测”的循环通常要跑四五轮技能文件才能达到“让模型独立执行且结果稳定”的状态。很多开源技能包看起来质量参差不齐本质上就是因为作者省掉了“测试打磨”阶段写完就直接发布了。5.4 第四步配套 harness 的执行封装如果技能只停留在“文档”层面Agent 能干的事还是有限的。我一般会在技能包之外写一个小型的执行封装层也就是我自己的“harness”。它做的事情包括维护技能文件的索引和加载逻辑封装工具调用的参数校验记录执行日志和阶段摘要实现统一的错误捕获和恢复策略。这个 harness 不用做得很复杂一套简单的 Python 脚本、几十个函数就能跑起来。关键是要做到“模型只能通过封装接口做事”不能直接访问底层所有能力。限制反而能提高任务执行的稳定性和可控性。5.5 第五步持续迭代的验收机制最后为技能包建立验收集。我给自己定了三条规矩每个技能至少配一个“正向用例”和一个“负向用例”每次修改技能文档后跑一遍全套验收记录前后差异每个月做一次线上任务的回溯分析把表现不佳的 case 归因到具体的技能缺陷然后针对性修改。这套机制跑起来之后技能包的进化就不再依赖“灵感”了而是变成了一个数据驱动的持续改进过程。效果是显而易见的我的 Agent 在完成复杂任务时的成功率从最初的不到四成逐步提升到了稳定在八成以上而且每一次技能更新都能明确知道是好是坏。6. 常见问题与避坑指南6.1 模型不按技能执行怎么办这是被问得最多的一个问题。技能文档写得明明白白模型就是不听像极了“看了员工手册但就是不照着做”的新同事。我自己总结下来主要原因有三类。第一类是技能加载时机不对技能内容根本没有进入模型的上下文自然不可能被执行这种问题要通过检查实际对话上下文里的注入内容来排查。第二类是技能内容被上下文中的其他信息覆盖了模型在后来的长对话里“忘了”技能约束这种情况要用前文说的“核心上下文保护”机制来解决。第三类是技能本身与任务目标冲突比如“技能要求先写测试再写实现”但用户在对话里的表述是“赶紧把功能做出来”模型会倾向于优先响应最近的用户指令解决方法是把技能的关键步骤写到系统提示词级别的指令里而不是只放在普通文档里。6.2 上下文不够用技能加载不进去长技能文档经常遇到这个问题。我建议的解法是“分阶段加载”而不是“一次性全量加载”。把技能按阶段拆开后每个执行阶段只加载当前阶段需要的技能文件。这样即使模型上下文窗口有限也能保证每个阶段拿到的技能描述是完整的。另一个思路是给技能写“精简版”把核心步骤压缩到几十行先加载精简版等模型进入具体操作阶段时再按需补充细节说明。6.3 技能之间互相冲突当技能包达到一定规模后冲突问题一定会出现。最常见的冲突是两个技能对同一个操作给出了不同的规则。比如“代码风格规范”里要求“变量命名使用驼峰式”而“性能优化指南”里的示例代码又用了下划线风格模型就会纠结。我的排查经验是在技能包里建一个“规则索引”文件把所有技能中出现过的硬性规则统一收录定期检查重复和冲突项。规则索引本身也要注入到上下文中作为技能之间仲裁的“最高法”。只有规则统一了模型在跨技能协作时才不会精神分裂。6.4 技能包在真实项目里没有效果如果你的技能包在测试集里表现不错但在真实项目里没效果大概率是“任务的上下文信息”不足。技能包解决的是“怎么做”的问题但它不能解决“不知道现在面对的是什么”的问题。真实项目里的情况千差万别技能规定得再细如果模型不知道当前仓库的目录结构、不知道当前分支状态、不知道历史提交记录它就很难把技能里的通用步骤落地到具体场景。所以我的做法是在 Agent 启动任务前先执行一轮“项目感知”步骤把项目的结构摘要、当前状态、相关历史记录等信息收集起来整理成结构化的环境描述注入到上下文里。技能 环境感知两个都到位了任务执行质量才会真正稳定。7. 写在最后的一些经验技能包这个方向我前前后后折腾了好几个月最深的体会有三个。第一写给 AI 看的文档本质上是在“做约束”不是在“做教育”。不要试图让模型变得更聪明它已经够聪明了你要做的是让它在你设定的轨道里稳定发挥。第二技能的迭代一定要有验收机制没有验收你根本分不清一次修改到底是在优化还是在破坏。第三文档和代码要配合纯文档的技能包到了复杂任务面前会显得力不从心配上一个简单的执行封装层相当于给士兵既配了作战手册又配了趁手的武器。还有个值得关注的变化是这一类“AI 文档工程”的技能正在成为新的生产力杠杆。过去我们写文档给同事看是为了同步信息、统一认知现在写文档给 Agent 看是在“批量复制行为模式”——一份好的技能文档可以被无限多个 Agent 实例同时使用边际成本趋近于零。这个杠杆效应会让“擅长写 AI 文档”的人在未来变得越来越值钱。最后分享一个小技巧写技能文档时多问自己一句“如果是一个完全不了解背景的新人拿着这份文档能不能直接把事情做对”。这个“新人测试”非常有效它能帮你筛掉那些“自己觉得写得很清楚、但换个视角全是漏洞”的内容。我自己每次写完技能文档都会用这个标准重新审视一遍至少能揪出两三处需要补充的细节。