系列《把经验封装成能力Agent Skills 设计与落地》本文是系列第二篇。上一篇我们回答了 Skill 是什么这一篇继续往下走为什么 Skill 最重要的价值不只是复用提示词而是把个人和团队的隐性经验变成 Agent 可以稳定执行的显性流程。1. 从上一篇的实践任务说起上一篇结尾留了一个练习从最近一周反复让 Agent 做过的任务里挑一个写下四句话。例如任务名称中文技术文章大纲生成 触发方式用户说“帮我把这个主题整理成文章大纲” 期望输出Markdown 格式的大纲包含目标读者、核心问题、分节标题和实践任务 重复规则面向工程师结构要清晰不要营销腔每篇都要有一个可执行练习这四句话看起来很简单但它们已经触碰到 Skill 设计里最核心的问题你脑子里那些“每次都会默认这么做”的经验怎样才能被 Agent 稳定理解并复用很多时候Agent 表现不稳定并不是因为模型完全不会做而是因为我们没有把任务里的隐性规则讲清楚。比如你说“帮我写个大纲”Agent 可能会给你一个通用大纲你说“帮我写一份技术方案”Agent 可能会漏掉备选方案你说“帮我 review 这段代码”Agent 可能会先纠结命名风格而不是先看正确性和并发风险。这些问题背后都有同一个根因任务经验没有显性化。2. 什么是隐性经验隐性经验不是玄学它只是那些你已经习惯了、但没有写成明确规则的判断。在团队协作里隐性经验通常以这些形态存在老同学知道的排障顺序。代码审查时默认优先看的风险点。文档评审时大家心照不宣的结构要求。某类 API 接入时必须先确认的兼容性问题。处理线上问题时不能跳过的观测指标。生成周报、复盘、方案时反复强调的表达风格。某些脚本的使用方式以及失败后应该怎么处理。这些经验在熟手之间传递得很快因为大家有共同背景。但 Agent 没有这个背景。它只看到当前对话、当前文件和当前可用工具。如果经验没有被写下来Agent 就只能猜。而一旦进入团队场景隐性经验还会带来三个额外问题。2.1 经验难以复制同一个任务A 同学知道要先看错误日志B 同学知道要先查配置C 同学知道某个字段不能随便改。每个人掌握的经验碎片不同最终输出质量就会不稳定。这也是很多团队使用 Agent 时的第一层困扰不是 Agent 不能做而是只有少数会写提示词、熟悉背景的人才能让它做得好。2.2 经验容易漂移如果经验只靠口头传播它会随着人、时间和场景发生漂移。例如团队原本约定技术方案必须包含“备选方案”但几个月后新同学不知道这件事原本代码审查要重点看兼容性但后来大家开始只看格式和命名原本事故复盘要有 owner 和截止日期后来变成了泛泛总结。流程没有被固定下来执行就会慢慢变形。2.3 经验无法评估如果经验没有显性化就很难判断它是否有效。你可能觉得“这样写文档更清楚”但清楚在哪里是标题层级更稳定还是读者更容易找到结论你可能觉得“这样 review 更专业”但专业在哪里是先看正确性还是能覆盖并发、资源泄漏、异常处理一旦经验被拆成明确步骤和检查项才有可能被评估、复盘和改进。3. Agent 为什么尤其需要显性流程人类协作可以依赖默契但 Agent 协作更依赖显性流程。原因很简单Agent 的工作方式决定了它需要被提供清晰的任务边界、上下文和成功标准。3.1 Agent 不拥有团队默认上下文团队成员可能知道“我们这里的周报格式”“我们项目里的兼容性约束”“我们对外文档的表达风格”但 Agent 不天然知道。如果你没有告诉它它可能会根据通用互联网语料生成一个看起来合理、但不符合团队习惯的结果。3.2 Agent 容易被当前局部信息牵引当上下文不完整时Agent 会优先根据当前用户输入和附近文件做判断。这在简单任务里通常没问题但在复杂任务里会带来偏差。例如你让它 review 一个函数如果没有明确说明“先看行为正确性再看边界条件最后看风格”它可能会被最显眼的命名、注释、格式问题吸引而不是先检查真正高风险的逻辑。3.3 Agent 需要明确的停止条件很多任务不是“生成一段文字”就结束了而是要满足某些完成标准。比如文档是否覆盖背景、方案、风险和下一步测试是否真的运行过输出是否符合指定格式脚本失败时是否给出可行动的错误信息是否需要向用户确认高风险决策这些停止条件如果不写清楚Agent 很容易停在“看起来完成”的状态。Skill 的价值就是把这些默认上下文、执行顺序和停止条件显性化。4. 从隐性经验到显性流程的拆解框架把经验写成 Skill不是把脑子里的想法一股脑写进SKILL.md。更好的方式是先把任务拆成八个部分。4.1 触发什么情况下该使用这套经验触发条件回答的是用户怎样表达时Agent 应该想到这个 Skill触发可以来自关键词也可以来自任务意图。例如用户说“帮我写技术文章大纲”。用户说“把这些素材整理成博客结构”。用户说“这个主题适合怎么展开成系列文章”。用户打开了某个文章草稿并要求继续写。这些表达不完全一样但背后的任务意图相同。4.2 输入完成任务需要哪些信息输入不是指用户当前说了什么而是指任务真正需要哪些信息。以技术文章大纲生成为例至少需要文章主题。目标读者。文章目标。读者已有背景。是否有指定风格或平台限制。是否需要代码、图表或案例。如果这些信息缺失Agent 应该知道是先做合理假设还是停下来询问。4.3 上下文有哪些背景规则不能丢上下文包含团队规范、业务约束、历史决策、术语习惯、风格要求。这些内容未必每次都出现在用户输入里但会影响最终结果。例如技术文章要面向工程师不要营销腔。代码示例超过 20 行时要考虑抽象。注释要解释为什么而不是重复代码做什么。输出 Markdown标题层级要清晰。如果涉及变更总结要使用中文变更主题和有序列表。这些都是典型的可沉淀规则。4.4 流程先做什么再做什么流程是 Skill 的骨架。一个稳定流程通常包含识别任务类型。收集必要上下文。判断是否需要调用脚本或读取参考资料。生成初版结果。自查输出是否满足格式和质量要求。对不确定或高风险内容向用户确认。如果没有流程Skill 就容易退化成一堆原则。4.5 工具哪些工作交给脚本或外部工具不是所有事情都应该让模型直接做。适合交给工具的任务通常有几个特征规则稳定。结果可验证。重复执行。出错成本较高。不需要复杂语义判断。比如格式校验、文件转换、目录扫描、测试运行、字段检查都更适合脚本或外部工具。Skill 应该写清楚什么时候用工具、怎么传参、失败时怎么处理。4.6 输出结果应该长什么样输出格式越明确Agent 越容易稳定。“帮我整理一下”是模糊的“输出 Markdown包含背景、核心问题、解决方案、风险、实践任务”就清楚得多。输出格式不仅包括结构还包括语言风格、粒度、是否需要列表、是否需要代码块、是否需要引用来源。4.7 校验怎样判断任务真的完成校验是很多 Skill 缺失的一环。一个任务完成不应该只看 Agent 是否生成了内容还应该看它是否满足成功标准。例如技术文章大纲可以校验是否有目标读者。是否有核心问题。是否有分节结构。是否有实践任务。是否避免空泛口号。是否与系列标题和前文承接。如果任务涉及文件或代码还可以通过脚本校验。4.8 边界什么时候不该使用这套经验好的 Skill 不仅知道什么时候该用也知道什么时候不该用。例如“技术文章写作 Skill”不应该接管所有 Markdown 任务“文档处理 Skill”不应该接管数据库脚本“Claude API Skill”在用户明确使用 OpenAI、Gemini 或其他模型供应商时也不应该强行介入。边界清楚才能减少误触发。5. 哪些知识适合沉淀进 Skill并不是所有知识都适合写进 Skill。我们可以把可沉淀内容分成五类。5.1 稳定流程稳定流程是最值得沉淀的内容。例如写技术方案的步骤。做代码审查的检查顺序。处理 PDF 表单的操作流程。测试 Web 页面时的启动、等待、截图和日志检查流程。创建 MCP Server 时的调研、实现、测试和评估流程。流程越稳定Skill 的收益越高。5.2 格式规范格式规范也很适合沉淀。例如周报结构。事故复盘模板。代码评审输出格式。提交说明格式。技术文章大纲格式。格式规范沉淀之后团队输出会更一致。5.3 判断准则判断准则是隐性经验里最有价值的一类。例如什么时候需要向用户确认。什么时候应该优先读取源码而不是直接猜。什么时候应该运行测试。什么时候应该拒绝执行高风险操作。什么时候该把参考资料拆分而不是继续堆在主文件里。这些准则能明显改变 Agent 的行为质量。5.4 工具使用方式很多团队都有脚本但脚本不一定容易被 Agent 正确使用。Skill 可以把工具的使用方式写清楚先运行--help还是先读源码。参数怎么传。输出怎么看。失败时优先检查什么。哪些命令有副作用需要先确认。这类内容尤其适合放进开发工具类 Skill。5.5 典型示例和反例示例能帮助 Agent 对齐风格。尤其是写作、设计、代码审查、方案评审这类主观性较强的任务仅靠抽象规则往往不够。几个好的示例和反例可以让 Agent 更快理解你要的效果。但示例也要控制数量。过多示例会增加上下文负担也可能让 Agent 过度模仿某个具体案例。6. 哪些内容不适合直接写进 SkillSkill 是长期复用资产所以也要克制。下面几类内容不适合直接写进去。6.1 密钥和敏感信息任何 token、密码、私钥、内部账号、生产环境地址都不应该写进 Skill。如果确实需要访问外部服务应通过环境变量、权限系统或 MCP 工具完成而不是把敏感信息固化在仓库里。6.2 高频变化的信息如果某个规则每天都变不适合写死在 Skill 里。更好的方式是让 Skill 指向权威来源要求 Agent 在执行前读取最新文档或配置。6.3 只适用于个人偏好的细枝末节团队 Skill 应该优先沉淀共识而不是某个人非常个人化的偏好。例如“我喜欢某种标题风格”可以放在个人写作 Skill但如果是团队公共 Skill就应该只保留团队一致认可的要求。6.4 无法执行的口号例如输出要高级。代码要优雅。文档要专业。分析要深入。这些话本身没有错但太抽象。Skill 里更需要可执行规则先给结论再解释原因。每个风险项必须包含影响和缓解方式。代码审查发现问题时必须给出文件位置、风险和修复建议。文档结尾必须包含下一步行动。可执行才可复用。7. 如何判断一个流程值得 Skill 化可以用一个简单的判断表。判断维度适合 Skill 化的信号暂不适合的信号频率每周或每个项目都会出现只会发生一次稳定性流程和规则相对固定规则频繁变化可描述性能说清输入、输出和步骤主要依赖临场感觉可验证性能检查格式、字段、测试或质量标准完全依赖主观判断边界清楚知道何时使用和何时不用几乎什么任务都想覆盖风险出错可发现、可恢复出错影响大且难以发现如果一个任务在大多数维度上都偏左就很适合 Skill 化。如果它只满足“高频”但流程不稳定、边界不清、无法验证那最好先不要急着写 Skill而是先整理任务本身。8. 从提示词片段到能力包很多 Skill 不是一开始就设计得很完整而是从一段反复复制的提示词演进出来的。可以把这个过程分成五个阶段。8.1 阶段一临时提示词这是最早期的形态。你发现某段 prompt 很有用于是每次复制粘贴。例如请面向工程师写作结构清晰不要营销腔。先说明问题再解释原理最后给实践建议。这个阶段成本低但不可维护。8.2 阶段二提示词模板当你发现每次都要填不同主题就会把它变成模板。例如主题[填写主题] 目标读者[填写读者] 输出格式[填写格式] 写作要求面向工程师结构清晰不要营销腔。模板比临时 prompt 稳定但仍然依赖人工复制和填写。8.3 阶段三结构化流程接下来你会发现光有模板还不够还需要流程。例如先确认目标读者。再判断读者已有背景。然后列出核心问题。再设计分节标题。最后检查是否有实践任务。这时它已经开始接近 Skill。8.4 阶段四Skill 雏形当你把触发条件、输入要求、流程、输出格式和约束写进SKILL.md它就成为了一个 Skill 雏形。这一步的关键变化是经验不再散落在聊天记录里而是进入一个可版本管理、可审查、可共享的文件。8.5 阶段五完整能力包随着任务复杂度增加你可能继续增加references/风格指南、案例、术语表。scripts/格式检查、标题层级检查、文件转换。assets/模板、示例输入、示例输出。evals/测试 prompt 和期望结果。这时它就从提示词片段演进成了完整能力包。9. 一个具体例子技术文章大纲生成我们用一个贯穿式例子来说明。一开始用户可能只是反复对 Agent 说帮我把这个主题整理成一篇技术文章大纲面向工程师别写得太营销。这句话背后其实包含很多隐性经验目标读者是工程师。文章应该问题导向而不是功能宣传。结构应该有层次。每节标题要能表达明确问题。最后最好有实践任务。如果主题太大应该拆成系列。如果涉及代码要控制示例长度。把这些经验显性化后可以整理成一个任务卡片。模块内容触发用户要求生成技术文章、大纲、系列选题、写作结构输入主题、目标读者、写作目标、已有材料、平台限制流程确认读者和目标提炼核心问题设计章节补充实践任务输出Markdown 大纲包含标题、定位、分节说明、实践任务校验是否问题导向是否面向工程师是否避免营销腔边界不负责生成最终长文不负责事实核查外部资料这张表就是写 Skill 的前置材料。到第三篇我们就可以把它进一步转换成SKILL.md。10. 团队场景中的收益把隐性经验显性化不只是为了让个人少写几次 prompt。真正的收益在团队场景里更明显。10.1 降低 onboarding 成本新同学不需要靠口口相传学习所有流程。只要 Skill 写得足够清楚Agent 就可以在执行任务时带出团队默认规范。新同学通过使用 Skill也能反过来理解团队是怎么工作的。10.2 降低输出差异同一类任务由不同人发起时Agent 可以使用同一套流程和输出格式。这对周报、方案、复盘、代码审查、对外文档尤其重要。统一不是为了限制表达而是为了减少不必要的格式和流程差异。10.3 降低流程漂移流程写进 Skill 后变更就可以被 review。如果有人想调整代码审查优先级、文档结构或测试流程可以通过修改 Skill 来完成而不是在每个人的聊天习惯里悄悄漂移。10.4 积累团队资产一个成熟团队会沉淀代码库、组件库、脚本库、文档库。Skill 则是另一种资产Agent 工作流库。它沉淀的不是某个函数而是“面对某类任务Agent 应该怎么做”。这类资产会随着团队使用而变得更稳定。11. 常见误区11.1 只沉淀结论不沉淀判断过程比如只写“代码审查要专业”不写先看什么、后看什么、发现问题怎么输出。这样的经验没有真正显性化只是换了一种方式表达口号。11.2 只沉淀格式不沉淀质量标准有些 Skill 只规定输出必须包含哪些标题但没有说明每个部分要达到什么质量。例如技术方案里有“风险”标题不代表真的分析了风险。更好的写法是要求每个风险项包含影响、概率、缓解方式和 owner。11.3 把所有经验一次性塞进去经验显性化不等于越多越好。如果一个 Skill 同时想覆盖写作、代码审查、测试、部署、排障它很可能边界过大。更好的方式是拆成多个职责清晰的 Skill。11.4 忽略异常路径很多流程在顺利时很好写但真实任务经常有缺失信息、工具失败、权限不足、需求冲突。Skill 应该写清楚这些情况如何处理缺少关键信息时是否询问。工具失败时是否重试。结果不确定时是否标注假设。高风险操作前是否暂停确认。异常路径越清楚Agent 越不容易乱猜。12. 小结Skill 的核心价值不是把提示词写得更长而是把隐性经验变成显性流程。隐性经验包括任务触发方式、输入要求、背景规则、执行顺序、工具用法、输出格式、校验标准和边界条件。只有这些内容被结构化之后Agent 才能稳定复用它们。可以记住这句话一个值得 Skill 化的任务通常是高频、稳定、可描述、可验证并且有清晰边界的任务。下一篇我们会开始进入文件结构本身具体拆解一个 Skill 的最小形态SKILL.md、frontmatter、name、description和正文说明应该怎么写。13. 实践任务请选一个你希望 Skill 化的任务填写下面这张表。模块问题你的答案任务名称这个任务叫什么触发方式用户通常会怎么提出这个需求输入信息完成任务必须知道哪些信息背景规则有哪些每次都要重复说明的规则执行流程Agent 应该先做什么再做什么工具资源是否需要脚本、文档、模板或外部工具输出格式最终结果应该长什么样校验标准怎样判断它真的完成了边界条件哪些情况不应该使用这个流程填完这张表后你就已经完成了写SKILL.md前最重要的一步把经验从脑子里拿出来变成可以被讨论、审查和迭代的流程。
