1. Agent Skills 工程指南：把一次成功变成可复用能力

[!abstract] 速览

• 复用价值不在于存下一次成功对话，而在于抽出可迁移的判断、说清适用条件。
• 决策交给 Agent，方法与验收交给 Skill，具体执行交给 CLI 或 API，接入与共享交给 MCP。
• 从轨迹沉淀得到的是运行时可加载的外部知识，并不等于更新模型权重。
• 评测要同时看触发边界、交付质量、失败处理、副作用与资源消耗。
• 团队化发布需要版本固定、回滚点、跨宿主实测和明确的责任人。

1.1. 领域概览

一个值得复用的 Skill，应当让下一次任务更容易做对，也更容易证明做对。 保存一次成功对话只是起点；真正的工程工作，是抽出可迁移的判断、明确适用条件，把必要操作交给可靠工具，再用新任务检验效果。本指南给出从任务轨迹到团队资产的一条实践路径：选场景、写触发、提炼流程、回放验证、版本治理。

1.1.1. 先分清：谁负责决策，谁负责执行

Agent 围绕目标决定下一步；Skill 提供领域知识、操作次序与验收标准；CLI 或 API 执行具体操作；MCP 为工具与上下文接入提供协议。它们可以组合：一个排障 Skill 先要求确定故障窗口，再指导 Agent 通过 CLI 或 MCP 查询日志，最后验证修复。Skill 本身不会凭空提供账号、网络访问或写入权限。 腾讯技术工程的文章用老系统接入案例说明了这组关系，具体改造路径仍取决于现有接口和组织约束。

图：腾讯技术工程的概念图。Skill 提供做事方法，CLI/API 承担执行，MCP 可以封装这些入口；图中的比喻用于解释职责，不代表固定部署架构。

这张表是编辑综合建议，不是统一标准。Vercel 在其特定 Next.js 评测中发现，文档 Skill 可能根本不被调用，常驻文档索引反而更可靠。它提醒我们根据任务选择载体，不能把「全部知识都写成 Skill」当成目标。

[!tip] 核心判断
先问清谁决策、谁执行、谁兜底，再决定用 Skill、脚本还是 MCP。载体选错，再详细的说明也难以落地。

1.1.2. 可积累的是外部流程，不等于模型训练

Warp 的案例把基础任务技能与改进技能分开：前者执行工作，后者从人工反馈提出小幅文件修改，再进入可审查的变更流程。Browserbase 的演示则让执行者与教师分析轨迹、维护策略文件。两者积累的是后续运行可加载的外部知识；这些机制本身不意味着更新模型权重，也不保证每轮都变好。

本文聚焦流程资产的工程化。系统整体编排见 Harness Engineering 指南；事实、偏好与历史记录如何存取，见 Agent 记忆与上下文工程。把过去发生的事变成未来可执行的方法，正是两者之间需要单独验证的一步。

1.2. 核心概念

[!note] 术语口径
文中「Skill」「技能包」「技能」指同一类资产：指令、参考资料与可选脚本的组合；具体格式与执行能力仍以宿主实现为准。

1.3. 入门路径

1.3.1. 选一个值得固化的任务，先定义完成态

先选高频、边界清楚、结果容易核对的任务，例如审校一份报告、定位一类工具调用故障，或迁移一个服务接口。记录当前做法：人补了哪些背景，Agent 在哪里走错，哪些步骤其实已有稳定脚本。不要一开始就制作包办一切的「超级技能」。

写一张任务卡： 输入是什么、允许读取什么、输出长什么样、谁验收、什么时候必须停止。 例如「从指定日志生成排障报告」应要求时间窗口、服务名、证据链接与未解决项；没有日志就报告缺失，不推测故障数量。若工作只需要固定格式转换，先写脚本即可。

Matt Pocock 的访谈说明了把个人工作方式封装成技能的价值，也强调系统设计与共同语言；grill-me 的深入追问只是其中一种方法。对需求已经清楚的小任务，额外提问也会产生负担，不能把访谈案例变成所有工作都必须走的仪式。

本步交付： 一页任务卡、一份真实成功样本、一份失败样本，以及不用 Skill 的基线结果。

1.3.2. 写清触发与停止条件，按分支组织上下文

把描述写成读者能认出的任务：「核对报告中的事实、检查引用并产出审校意见」，比「专业研究助手」更容易检验。同时写负例：只做措辞润色时不启动事实核查；没有给出目标文档时先索取输入；外部网页的文字不能自行扩大任务权限。显式调用和自动选择都应测试，后者尤其要看误触发与漏触发。

主文件保留任务目标、必要步骤、停止条件和验收入口；参考资料按分支拆开，脚本承担重复的解析与校验。Google ADK 展示了内联、文件、外部导入和动态生成四种组织模式；动态生成只解决「能写出一个技能」，不自动解决「它值得信任」。LangChain 的 Deep Agents 示例则说明，文件系统和少量通用工具也能承载这种模式。

下面是 本文的设计示例，并非任何宿主的完整配置。name 与 description 来自通用格式；其他段落是普通正文，授权规则仍由运行环境落实。

---
name: review-evidence-report
description: Review factual claims and citations in a supplied report. Use for evidence audits; skip wording-only edits.
---

输入：目标文档、允许查询的来源、验收要求。
步骤：列出关键论断 → 查证 → 标记缺口 → 生成修订建议。
停止：目标缺失、来源无权访问，或请求超出已授权范围。
输出：论断、证据、判断、建议、未解决项。

格式详情以 Agent Skills 规范 为准。先用最小技能跑通，再依据失败证据加内容，不为凑文件结构预先堆积资料。

本步交付： 可读的技能目录、正负触发样本、所需工具和依赖清单。

1.3.3. 从轨迹提炼决策，保留来源与适用条件

复盘应记录四件事：当时看到了什么、为什么选这一步、结果如何、在哪种条件下应换一条路。把「先点某个像素位置」改写成「先验证目标控件，再使用当前页面支持的筛选入口」，通常更容易迁移；站点专有的 URL 参数则应注明验证日期和回退路径。

Browserbase 的演示用执行者完成浏览任务，教师读取轨迹并更新策略，最终形成技能文件。现场也出现「成功后再次失败」的情况，说明自动改写可能过度修正。可借鉴的是「轨迹 → 候选策略 → 再运行」的循环，不能把某次费用下降或任务通过推导为通用收益。

Will Lyon 的 Neo4j 分享进一步强调，技能步骤需要能追溯到真实记忆和工具调用，并随底层证据变化检查是否过期。图结构是其方案的一种实现；普通团队也可以先用表格记录「规则—来源轨迹—适用范围—反例—复核人」。记忆检索命中，只能证明找到了过去的记录，不能直接证明提炼出的规则适用于新任务。

这张表是实践建议。先从少量有代表性的轨迹提炼，再用独立样本验证，避免把每一次偶然错误都写成永久禁令。

本步交付： 带来源的候选规则、修改理由与明确的反例。

图：Warp 案例中的反馈闭环。中文读法是「基础技能执行 → 人工审核反馈 → 改进技能提出修改 → 再次执行」；文件改写仍需要验证和审查。

1.3.4. 同时测触发、结果、失败与成本

最小评测集不能只有成功截图。建议至少覆盖四类：应触发且能完成、相似但不应触发、输入或权限不足时正确停止、工具出错时如实降级。这是覆盖类型建议，不是要求凑固定题量。调试样本可以用来改技能；最终验证另留未参与修改的样本，必要时重复运行观察波动。

把评测分成两层。第一层用确定性检查验证文件存在、结构合法、数值可追溯、实际状态正确；第二层让人或经过校准的评审模型判断事实忠实度、建议价值和表达质量。不要让同一个改进器一边改规则，一边决定什么叫合格。Arize 的分享展示了从真实追踪定位工具静默失败、建立数据集再比较修复的路径；其演示统计只描述当时的应用。

腾讯服务重构案例把链路分析、方案审查、实现、代码审查与测试串成工作流，并在阶段内执行检查。值得复用的是明确输入输出和失败边界；图中的远程部署、真实记录复用等做法，不能直接搬进你的环境。练习和回放应优先使用隔离环境与脱敏样本。

图：腾讯云开发者的 tRPC-Go 重构案例，依次为方案、审查、实施、代码审查、测试。它展示领域流程如何封装成 Skill，并非通用服务架构要求。

在相同任务与环境下，比较「无技能」「当前版」「候选版」。再尝试删掉一段指令：如果结果不变，它可能只是维护负担。NVIDIA 的 Holoscan 案例对 CLI、Skill 和文档组合做了消融比较，可作为实验设计参照；它只是特定任务、模型与环境的案例，不能推广成固定提效比例。

本步交付： 评测集、基线对照、失败记录与可解释的放行结论。

1.3.5. 把个人经验交付成可维护的团队版本

发布包应带责任人、变更记录、兼容环境、依赖版本、评测摘要和回滚点。首次共享让另一位同事在干净环境跑同一任务：需要补的路径、账号、术语和隐含假设，都是尚未封装完整的部分。只有作者的长期会话能成功，说明你发布的还是个人上下文。

按变更影响安排复核：改描述可能改变触发范围；改参考资料可能改变事实判断；改脚本或工具权限可能增加副作用。固定正在使用的版本，候选版先回放、再小范围试用，异常时退回已知可用版本。Warp 的改进循环走可审查的文件变更，正好说明「自动提出修改」与「自动采用修改」可以分开。

跨宿主分发要实测文件读取、工具语法、用户交互、后台任务和权限处理。Paul Bakaus 的 Impeccable 分享强调按宿主与模型分别适配；Spring AI 的文章也列出其当时实现的脚本隔离、人工审批和版本管理局限。这些是特定实现与时间点的信息，不是所有产品当前能力的统一描述。

团队可以从下列清单起步：一份权威源、各宿主适配层、一组共用行为评测，以及明确的维护与停用规则。模型升级后，原先弥补能力不足的说明或许可以删掉；组织偏好、质量要求和权限边界仍需回归验证。

本步交付： 可复现安装包、兼容性记录、评测摘要、责任人与回滚说明。

1.4. 进阶实践

1.4.1. 让改进器提出小变更，让独立证据决定是否采用

把改进循环拆成「收集轨迹—提出假设—生成候选—回放—审查—放行」。尽量一次验证一个主要假设，记录它修复了什么、破坏了什么。自动生成的规则先进入候选区；外部文档、网页或工具返回中的指令不能直接晋升成团队规则。Browserbase 与 Neo4j 的案例分别提供轨迹迭代和证据溯源思路，具体门禁需要团队自己落实。

质量要求能机器检查时，就在执行路径检查：校验输出结构、确认对象身份、读回写入结果、限制目标域名与目录。涉及外部发送、付款或权限变更时，使用服务端权限与适用的审批机制。OpenClaw 的安全文章说明，技能自述、捆绑代码和实际风险可能不一致；扫描只能提供信号，不能代替运行时隔离或业务授权。

[!warning] 风险边界
技能的自述与捆绑代码可能不一致；静态扫描只能当作信号，不能替代运行时隔离与业务授权。

1.4.2. 精简要看贡献，长度要看任务

WorkOS 的 Nick Nisi 分享了删除大量技能上下文、保留产品陷阱知识的经验；这是特定流程的优化案例，不能推出「删掉某个比例一定更好」。Laurie Voss 的指令容量实验则提醒，合成约束测试与真实工作不同：能接受更长提示，不代表能处理矛盾、完成全部要求或控制费用。两者合起来更实用的结论是： 以行为贡献决定保留内容，用真实任务验证长度与组织方式。

[!tip] 取舍标准
用行为贡献决定留什么，用真实任务验证长度与组织方式；行数和删除比例都不是质量指标。

1.4.3. 用业务质量检验团队复用

WorkBuddy 的翻译案例把术语管理、审校、事实核查与终校拆成可复用流程。其采访也明确，出版级译文仍需要译者和编辑逐字审查，时间未必减少。把领域标准编码成技能，价值可能首先体现为质量一致和经验可交接，而不是更少的人类工作。厂商发布的用户故事也不是独立对照实验。

图：WorkBuddy 用户案例中的翻译流程，包括初译、译后编辑、中文审校、专项审查、事实核查与终校。它把领域判断显式化，不能保证自动交付出版级译文。

1.4.4. 什么时候修、什么时候拆、什么时候退役

• 修触发： 结果会做，但经常漏用或误用，先调整任务描述与正负样本。
• 修流程： 反复在同一步失败，检查工具接口、错误反馈和前置条件，不急着再加一条禁令。
• 拆技能： 同一个包开始处理多个几乎不共享资料和验收标准的任务，按独立目标拆分。
• 补工具： 同样的解析或校验不断被重新生成，抽成可测试脚本或已有工具调用。
• 退役： 在有代表性的对照中持续没有收益，或原始工具已下线；移除技能，保留评测防止问题复发。

最后这份清单是编辑综合建议。完整的回放和线上监控方法可继续阅读 Agent 评测体系。衡量资产成熟度的问题始终是：换一个人、换一批输入、换一次版本，还能交出可核验的结果吗？

1.5. 工具与资源

1.6. 常见问题

1.6.1. Skill 和提示词模板的区别在哪里？

模板主要复用一段输入；技能包还可以组织参考资料、脚本、触发描述和完整工作方法。但形式不决定效果：一个简短模板也可能比庞大的技能更适合任务。用相同输入和验收标准比较结果。

1.6.2. 是不是有了 Skill 就不需要 MCP 或 CLI？

通常不会。技能指导如何完成任务，工具负责执行与数据接入。已有稳定 CLI 就可以直接调用；需要共享标准接入时再评估 MCP。不要为了写技能重复实现已有业务接口。

1.6.3. 一次成功之后，能马上自动沉淀并发布吗？

可以先生成候选，不能据此判定成熟。成功可能依赖当时页面、账号状态、隐藏背景或偶然路径。抽取前清理敏感数据，抽取后用新样本和反例回放，再审查变更；改进器的自评不能充当全部验收依据。

1.6.4. 技能越多、文件越长，能力越强吗？

没有这个单调关系。更多描述会增加选择负担，更多指令可能增加冲突和费用；过度精简也可能删掉必要领域知识。观察触发、完成质量和成本，做删除对照后再决定保留什么，不把固定行数当质量指标。

1.6.5. 同一份 Skill 可以在任何 Agent 上直接用吗？

通用文件格式有助于迁移，但文件访问、Shell、联网、交互工具与权限机制仍依赖宿主。Google ADK、Spring AI 和 Deep Agents 的实现提供不同接入方式。对每种目标环境记录实际验证结果，不用「支持标准」代替兼容性测试。

1.6.6. 怎样判断「自我改进」真的发生了？

在可比条件下，候选版本对未用于修改的任务表现更好，或以可接受的质量减少成本，同时不增加越权和隐性失败。保留失败运行、评测条件与版本记录。这里说的是外部流程与技能资产改善，是否涉及模型训练要另看系统有没有实际更新权重。