1. 从“能跑”到“敢上线”Skill 质量保障的整体思路1.1 为什么 Skill 的“写好”和“测好”是两件事很多人第一次接触 Agent Skills脑子里想的都是“我把提示词写清楚把工具挂上去它就能干活了”。这个阶段我称之为“能跑”。但能跑和敢上线之间隔着一条很宽的河。我见过太多 Skill 在本地测试时表现惊艳一放到真实环境就翻车——要么是边界情况没覆盖要么是权限给大了导致误操作要么是输出格式飘忽不定让下游解析直接崩掉。写得好核心是意图表达清晰、工具边界明确、输出结构稳定。测得好核心是覆盖足够多的异常路径、验证权限最小化、确认失败时的行为可预期。这两件事的评判标准完全不同前者看的是“正常路径下能不能完成任务”后者看的是“异常路径下会不会造成破坏”。一个 Skill 写得再优雅如果没有经过系统性的测试和权限收敛上线就是给自己埋雷。我个人的经验是把 Skill 的开发分成三个阶段草稿期、加固期、上线期。草稿期只关心功能能不能实现怎么快怎么来加固期专门处理边界、异常、权限和输出稳定性上线期则是灰度、监控和回滚预案。很多人跳过加固期直接上线结果就是线上反复修修补补用户体验极差。1.2 一个 Skill 上线前必须回答的五个问题在动手写测试用例之前我习惯先问自己五个问题。这五个问题答不上来说明 Skill 的设计本身就有漏洞测试也测不到点子上。第一个问题这个 Skill 的输入边界在哪里用户可能传进来空字符串、超长文本、特殊字符、二进制数据、甚至是恶意构造的注入内容。你的 Skill 对这些输入分别是什么行为是报错、是忽略、还是直接崩溃第二个问题这个 Skill 会触碰哪些外部资源读写文件、调用接口、操作数据库、发送消息——每一个外部操作都需要明确权限范围。能不能只读不写能不能限定目录能不能限定接口的白名单第三个问题失败的时候会发生什么是静默失败、是抛异常、还是部分完成部分完成是最危险的因为它可能留下不一致的中间状态。比如一个“整理文件”的 Skill移动到一半失败了剩下的文件怎么办第四个问题输出格式是否稳定下游如果依赖这个 Skill 的输出做解析那么输出的结构、字段名、类型必须固定。不能这次返回字符串下次返回数组。第五个问题有没有办法在不影响用户的情况下验证也就是灰度能力。能不能先对内部账号开放或者先在一个隔离环境里跑确认没问题再全量这五个问题看起来简单但真正逐条回答的时候你会发现很多设计上的模糊地带。而这些模糊地带恰恰就是线上事故的高发区。1.3 质量保障的三个层次功能、边界、安全我把 Skill 的质量保障分成三个层次从低到高分别是功能验证、边界覆盖和安全收敛。功能验证是最基础的确认正常输入能得到预期输出。边界覆盖是进阶的确认异常输入不会导致崩溃或错误行为。安全收敛是最高层的确认即使 Skill 被恶意利用也不会造成超出预期的破坏。这三个层次不是并列关系而是递进关系。功能验证没过谈边界没有意义边界覆盖没做谈安全就是空中楼阁。但现实中很多人只做了第一层就上线了因为功能验证最容易做写几个正常用例跑通就行。边界和安全需要构造大量“不按套路出牌”的输入费时费力而且短期内看不到收益——直到出事。我的建议是把三个层次的测试用例都纳入 CI 流程。每次修改 Skill 定义或工具配置都自动跑一遍。这样虽然前期投入大但后期每次迭代都能快速确认没有引入回归问题长期来看反而省时间。2. 把 Skill 写好的核心要素意图、工具与输出2.1 意图描述让 Agent 知道“做什么”和“不做什么”Skill 的本质是一段给 Agent 看的说明书。这段说明书的质量直接决定了 Agent 的行为边界。我见过很多 Skill 的描述写得像产品需求文档充满了“尽可能”“尽量”“优先”这类模糊词汇。Agent 不是人它不会“领会精神”它只会严格按照字面意思执行。你写“尽量删除临时文件”它可能把不该删的也删了因为它认为“尽量”就是“能删就删”。好的意图描述应该包含三个部分任务定义、约束条件、例外处理。任务定义说清楚这个 Skill 要完成什么用动词开头一句话讲明白。约束条件列出所有“不能做”的事情比如“不得修改原始文件”“不得访问指定目录之外的路径”“不得在输出中包含敏感字段”。例外处理说明当约束条件与任务目标冲突时怎么办比如“如果目标文件不存在返回错误码而不是创建新文件”。我习惯用这样的结构来写意图描述## 任务 将指定目录下的日志文件按日期归档到对应月份的子目录中。 ## 约束 - 只处理 .log 后缀的文件 - 不修改文件内容只移动位置 - 目标目录必须已存在不自动创建 - 如果同名文件已存在跳过并在结果中标记 ## 例外 - 如果源目录不存在返回错误码 ENOENT - 如果目标目录不存在返回错误码 ENOENT - 如果文件正在被占用跳过并在结果中标记这种结构化的写法比一段散文式的描述要可靠得多。Agent 解析起来歧义更少测试的时候也更容易对照检查。2.2 工具选型能用只读就不用读写能限定就不用全局Skill 的能力来自于它挂载的工具。工具给得越多Skill 能做的事情越多但出错的概率也越大。我的原则是能用只读工具就不用读写工具能限定范围就不用全局权限能一步完成就不要拆成多步。举个例子如果一个 Skill 只需要读取文件内容做分析那就只挂载读取工具不要挂载写入工具。这样即使 Agent 理解错了意图它也没有能力去修改文件。这就是所谓的“能力最小化”原则——不是靠提示词去约束行为而是靠工具权限从物理上限制行为。再比如如果 Skill 需要访问某个 API尽量使用限定范围的凭证而不是管理员级别的密钥。如果 API 支持按资源粒度授权就精确到具体资源。如果支持 IP 白名单就加上。每多一层限制就少一类潜在事故。还有一个容易被忽略的点工具的调用顺序。有些 Skill 需要先读后写如果 Agent 把顺序搞反了可能造成数据不一致。这种情况下可以考虑把多个步骤封装成一个原子操作的工具或者用状态机来约束调用顺序。虽然实现起来麻烦一点但比事后修数据要划算得多。2.3 输出格式结构化、可验证、可追溯输出格式的稳定性是 Skill 能否被集成到自动化流程中的关键。如果输出是自由文本下游就没法可靠地解析。我强烈建议所有 Skill 的输出都采用结构化格式比如 JSON 或 YAML并且明确定义每个字段的类型和含义。一个典型的输出结构应该包含状态码、结果数据、错误信息、执行元数据。状态码用枚举值比如 success、partial、failed。结果数据根据具体任务定义。错误信息在失败时填充包含错误类型和可读的描述。执行元数据包括时间戳、耗时、处理的记录数等方便排查问题。{ status: partial, data: { processed: 42, skipped: 3, skipped_files: [a.log, b.log, c.log] }, error: null, meta: { started_at: 2025-01-15T10:30:00Z, duration_ms: 1250, skill_version: 1.2.0 } }这种结构的好处是下游可以根据 status 字段决定后续流程根据 data 字段做进一步处理根据 error 字段做告警根据 meta 字段做监控。每个字段都有明确的用途不会出现“这个字段有时候有有时候没有”的情况。另外输出中不要包含敏感信息。比如文件路径中可能包含用户名API 响应中可能包含令牌。如果确实需要输出这些信息用于调试应该做脱敏处理或者只在 debug 模式下输出。3. 测试 Skill 的完整方法论从单元到集成3.1 测试用例设计正常路径、边界路径、异常路径测试用例的设计核心是覆盖三类路径正常路径、边界路径、异常路径。正常路径验证功能是否正确边界路径验证极端输入下的行为异常路径验证失败时的处理。正常路径的用例比较好写就是典型的输入和预期的输出。比如“归档日志”这个 Skill正常路径就是给一个包含若干 .log 文件的目录验证文件是否被正确移动到对应月份的子目录。边界路径需要动点脑筋。常见的边界包括空输入、单个元素、最大数量、超长字符串、特殊字符、重复元素、大小写差异、路径中的空格和中文。比如空目录、只有一个文件、文件名超长、文件名包含空格或中文、同一天有多个文件、文件名大小写不一致等。异常路径是最容易被忽略的。常见的异常包括源目录不存在、目标目录不存在、文件被占用、权限不足、磁盘空间不足、网络超时。这些情况在本地测试时很难复现但线上一定会遇到。我的做法是用 mock 工具模拟这些异常确认 Skill 的行为符合预期——是返回错误码还是重试还是跳过。我通常会维护一个测试用例表每个用例包含用例编号、输入描述、预期输出、实际输出、是否通过。这个表随着 Skill 的迭代不断补充成为回归测试的基础。用例编号类型输入描述预期行为TC-001正常目录含 3 个 .log 文件全部归档statussuccessTC-002边界空目录不报错statussuccessprocessed0TC-003边界文件名含中文和空格正常归档TC-004异常源目录不存在statusfailederrorENOENTTC-005异常目标目录不存在statusfailederrorENOENTTC-006异常文件被占用跳过该文件statuspartial3.2 自动化测试让每次修改都能快速回归手工测试只能覆盖有限的场景而且每次修改都要重新跑一遍效率极低。自动化测试是必须的。对于 Agent Skills自动化测试的难点在于 Agent 的行为有一定的不确定性——同样的输入可能因为模型版本、温度参数、上下文长度的不同而产生不同的输出。我的做法是分层测试。第一层是工具层的单元测试直接测试 Skill 挂载的每个工具函数这部分是确定性的可以用传统的单元测试框架。第二层是 Skill 层的集成测试模拟 Agent 调用 Skill 的过程验证输入到输出的映射关系。这一层需要固定模型版本和参数尽量减少随机性。第三层是端到端测试在真实或接近真实的环境中跑完整流程验证与其他系统的交互。工具层的单元测试用 pytest 或 jest 这类框架就行重点是覆盖所有分支和异常。Skill 层的集成测试可以用一个固定的测试 harness把 Agent 的决策过程 mock 掉直接测试 Skill 定义和工具组合的行为。端到端测试则需要在隔离环境中部署完整的 Agent 运行时用预定义的输入跑一遍对比输出。自动化测试的另一个好处是可以把测试用例作为 Skill 的“契约”。每次修改 Skill 定义如果测试挂了说明修改影响了已有行为需要确认是有意为之还是引入了 bug。这种反馈循环比人工 review 要可靠得多。3.3 灰度与回滚上线前的最后一道防线即使测试再充分线上环境总会有测试覆盖不到的情况。灰度发布是降低风险的有效手段。具体做法是先把新版本的 Skill 开放给一小部分用户或流量观察一段时间确认没有异常后再逐步扩大范围。灰度的维度可以按用户、按请求量、按时间段来划分。比如先对内部账号开放跑一天没问题再对 1% 的外部用户开放再逐步扩大到 10%、50%、100%。每个阶段都要有明确的观察指标和回滚条件。观察指标包括成功率、错误率、平均耗时、异常日志数量。回滚条件比如错误率超过 1%、出现未预期的错误类型、耗时超过阈值。回滚预案要提前准备好不能等出事了再想。回滚的方式取决于 Skill 的部署形态。如果是配置类的 Skill回滚就是切回旧版本的配置。如果是代码类的 Skill回滚就是重新部署旧版本。无论哪种方式都要确保回滚操作本身是经过验证的不会因为回滚引入新的问题。我个人的习惯是每次上线新版本之前先把旧版本的配置和代码打一个 tag记录在案。回滚的时候直接切到 tag 对应的版本避免手忙脚乱找错文件。4. 权限与安全Skill 上线的红线4.1 权限最小化从“能做什么”到“只能做什么”权限最小化是 Skill 安全的第一原则。很多事故的根源不是 Skill 的逻辑写错了而是权限给大了。一个只需要读取配置的 Skill如果被赋予了写入权限那么当 Agent 理解偏差时就可能修改配置导致服务异常。实现权限最小化需要从几个层面入手。文件系统层面限定 Skill 只能访问特定目录并且区分读写权限。如果只需要读取就挂载只读。如果只需要写入特定文件就精确到文件级别而不是整个目录。网络层面限定 Skill 只能访问白名单内的地址避免被诱导访问恶意端点。API 层面使用最小权限的凭证避免使用管理员密钥。还有一个容易被忽略的点环境隔离。如果 Skill 需要执行代码或命令尽量在沙箱或容器中运行限制其对宿主环境的影响。即使 Skill 被恶意利用破坏范围也被限制在沙箱内。我见过一个案例一个“清理临时文件”的 Skill因为挂载了全局的删除权限结果 Agent 把用户的重要文件也删了。如果当初只挂载了特定临时目录的删除权限这个事故就不会发生。权限最小化不是限制功能而是限制破坏范围。4.2 输入校验不信任任何外部输入Agent Skills 的输入可能来自用户、来自其他系统、来自模型自身的生成。无论来源是什么都不能信任。输入校验的目标是确保输入符合预期的格式和范围拒绝任何可疑的内容。常见的校验包括类型校验是不是字符串、是不是数字、长度校验是否超过最大长度、格式校验是否符合正则表达式、范围校验是否在允许的枚举值内、内容校验是否包含注入字符。对于文件路径还要校验是否包含..等路径穿越字符。对于命令参数要校验是否包含 shell 元字符。校验失败时的行为也很重要。是直接拒绝并返回错误还是尝试清洗后继续我的建议是直接拒绝因为清洗规则很难覆盖所有情况而且清洗后的输入可能仍然有风险。直接拒绝虽然用户体验差一点但安全边界清晰。另外校验要在 Skill 的最外层做不要依赖 Agent 去判断。Agent 的判断是不可靠的它可能被诱导绕过校验。把校验逻辑放在工具函数内部作为第一道防线这样无论 Agent 怎么调用校验都会执行。4.3 审计与监控出了问题能查到原因审计日志是安全体系的重要组成部分。每次 Skill 被调用都应该记录谁调用的、什么时候调用的、输入是什么、输出是什么、耗时多少、是否成功。这些日志在排查问题时非常有用也是事后追责的依据。审计日志本身也要注意安全。日志中不能包含敏感信息比如密码、令牌、个人隐私数据。如果确实需要记录要做脱敏处理。日志的存储也要有访问控制避免被未授权的人查看。监控是在审计日志的基础上做实时告警。比如错误率突然升高、出现未预期的错误类型、调用量异常增长、单次调用耗时过长。这些指标可以帮助你第一时间发现异常而不是等用户投诉才知道出了问题。我通常会设置几个关键的告警规则错误率超过 5% 持续 5 分钟、出现新的错误类型、单次调用耗时超过 30 秒、调用量超过历史峰值的 2 倍。这些规则不是一成不变的需要根据实际情况调整。太敏感会导致告警疲劳太迟钝会错过问题。5. 常见问题与排查技巧实录5.1 输出格式飘忽不定怎么办这是最常见的问题之一。同样的输入有时候返回 JSON有时候返回带解释的文本。原因通常是 Skill 的意图描述中没有强制输出格式或者 Agent 在遇到不确定的情况时“自由发挥”了。解决办法是在 Skill 定义中明确输出格式并且给出示例。示例要尽可能详细包括成功和失败两种情况。另外可以在工具函数中对输出做后处理强制转换为结构化格式。如果 Agent 返回的是自由文本工具函数尝试解析解析失败就返回标准错误格式。还有一个技巧是在 Skill 描述中加入“无论结果如何都必须以 JSON 格式返回”这样的强制语句。虽然不能 100% 保证但能显著提高一致性。5.2 权限不足导致的静默失败权限不足时有些工具会返回空结果而不是报错导致 Skill 看起来“成功”了但实际上什么都没做。这种静默失败非常危险因为下游可能基于错误的结果继续执行。排查方法是在工具函数中显式检查权限如果权限不足主动抛出错误而不是依赖底层工具的返回值。另外在测试用例中专门覆盖权限不足的场景确认 Skill 的行为是报错而不是静默成功。如果 Skill 需要访问某个资源但权限配置可能因环境而异可以在 Skill 启动时做一次权限自检确认所有需要的权限都已具备。自检失败就拒绝启动避免运行到一半才发现问题。5.3 常见问题速查表问题现象可能原因排查方法解决方案输出格式不一致意图描述未强制格式检查 Skill 定义中的输出部分增加格式约束和示例静默失败权限不足但未报错检查工具函数的错误处理显式检查权限并抛错部分完成多步操作中途失败检查日志中的中间状态增加事务或补偿逻辑耗时过长工具调用阻塞检查各步骤耗时增加超时和异步处理误操作权限过大检查工具挂载的权限范围收敛到最小权限注入风险输入未校验检查输入处理逻辑增加校验和转义5.4 几个我踩过的坑第一个坑是过度依赖 Agent 的判断。我曾经写过一个 Skill在描述中说“如果文件超过 10MB 就跳过”。结果 Agent 有时候判断对了有时候判断错了因为它对“10MB”的理解不稳定。后来我改成在工具函数中硬编码这个阈值Agent 只负责传递文件路径判断逻辑由代码执行。这样就稳定了。第二个坑是忽略了并发场景。一个 Skill 在单次调用时没问题但多个调用并发执行时可能同时读写同一个文件导致数据不一致。解决办法是加锁或者使用原子操作。如果 Skill 本身不支持并发就在描述中明确说明“此 Skill 不支持并发调用”。第三个坑是回滚不彻底。有一次上线新版本后发现问题回滚到旧版本但旧版本依赖的一个配置已经被新版本修改了导致回滚后仍然异常。后来我养成了习惯每次上线前把相关配置也一起备份回滚时一并恢复。第四个坑是日志中泄露敏感信息。有一次排查问题时发现审计日志中记录了完整的 API 响应其中包含用户的令牌。虽然日志的访问有控制但仍然是不必要的风险。后来我在日志记录前增加了脱敏步骤把令牌、密码等字段替换为掩码。这些坑的共同点是它们都不是功能逻辑的问题而是工程实践的问题。功能逻辑可以通过测试发现但工程实践的问题往往要在真实环境中才会暴露。所以我的建议是在加固期就要考虑这些场景不要等到上线后才补。6. 从开发到上线的完整检查清单6.1 上线前的自检项在点击“发布”按钮之前我通常会过一遍这个清单。每一项都确认无误才敢上线。意图描述是否包含任务、约束、例外三个部分工具权限是否已经收敛到最小范围输出格式是否结构化且有明确定义测试用例是否覆盖正常、边界、异常三类路径自动化测试是否全部通过审计日志是否已配置且脱敏监控告警规则是否已设置回滚预案是否已准备并验证灰度计划是否已制定相关文档是否已更新这个清单看起来繁琐但每一条都对应着一种常见的线上问题。花半小时过一遍清单可能省下几小时的排查时间。6.2 上线后的观察要点上线不是终点而是另一个起点。新版本上线后的前几个小时是最关键的观察期。我通常会盯着几个指标错误率、耗时、调用量、异常日志。如果错误率突然升高或者出现未预期的错误类型就立即回滚。除了技术指标还要关注用户反馈。有时候技术指标正常但用户感知到了问题比如输出内容不符合预期、操作结果与预期不符。这些反馈往往能发现测试覆盖不到的盲区。观察期结束后如果一切正常就可以逐步扩大灰度范围。每次扩大范围后都要重新观察一段时间。不要一次性全量给自己留出反应时间。6.3 持续迭代的心态Skill 的上线不是一劳永逸的。随着使用场景的变化、依赖工具的更新、模型版本的升级Skill 的行为可能会发生变化。所以需要定期回顾和更新。我个人的习惯是每个月回顾一次线上 Skill 的运行情况看看有没有新的错误模式、有没有可以优化的地方、有没有需要补充的测试用例。另外每次模型版本升级后都要重新跑一遍回归测试确认行为没有变化。还有一点很重要记录每次变更的原因和影响。这样当出现问题时可以快速定位到是哪次变更引入的。变更记录不需要很复杂一句话说明改了什么、为什么改就行。但一定要记否则时间久了就忘了。说到底Skill 的质量保障是一个持续的过程而不是一次性的任务。写好、测好、安全上线每个环节都需要认真对待。但也不用追求完美先保证核心路径可靠、权限收敛、有回滚预案就已经超过了大多数人了。剩下的可以在迭代中逐步完善。 Agent Skill 质量保障：从能跑到敢上线的测试与安全实践
1. 从“能跑”到“敢上线”Skill 质量保障的整体思路1.1 为什么 Skill 的“写好”和“测好”是两件事很多人第一次接触 Agent Skills脑子里想的都是“我把提示词写清楚把工具挂上去它就能干活了”。这个阶段我称之为“能跑”。但能跑和敢上线之间隔着一条很宽的河。我见过太多 Skill 在本地测试时表现惊艳一放到真实环境就翻车——要么是边界情况没覆盖要么是权限给大了导致误操作要么是输出格式飘忽不定让下游解析直接崩掉。写得好核心是意图表达清晰、工具边界明确、输出结构稳定。测得好核心是覆盖足够多的异常路径、验证权限最小化、确认失败时的行为可预期。这两件事的评判标准完全不同前者看的是“正常路径下能不能完成任务”后者看的是“异常路径下会不会造成破坏”。一个 Skill 写得再优雅如果没有经过系统性的测试和权限收敛上线就是给自己埋雷。我个人的经验是把 Skill 的开发分成三个阶段草稿期、加固期、上线期。草稿期只关心功能能不能实现怎么快怎么来加固期专门处理边界、异常、权限和输出稳定性上线期则是灰度、监控和回滚预案。很多人跳过加固期直接上线结果就是线上反复修修补补用户体验极差。1.2 一个 Skill 上线前必须回答的五个问题在动手写测试用例之前我习惯先问自己五个问题。这五个问题答不上来说明 Skill 的设计本身就有漏洞测试也测不到点子上。第一个问题这个 Skill 的输入边界在哪里用户可能传进来空字符串、超长文本、特殊字符、二进制数据、甚至是恶意构造的注入内容。你的 Skill 对这些输入分别是什么行为是报错、是忽略、还是直接崩溃第二个问题这个 Skill 会触碰哪些外部资源读写文件、调用接口、操作数据库、发送消息——每一个外部操作都需要明确权限范围。能不能只读不写能不能限定目录能不能限定接口的白名单第三个问题失败的时候会发生什么是静默失败、是抛异常、还是部分完成部分完成是最危险的因为它可能留下不一致的中间状态。比如一个“整理文件”的 Skill移动到一半失败了剩下的文件怎么办第四个问题输出格式是否稳定下游如果依赖这个 Skill 的输出做解析那么输出的结构、字段名、类型必须固定。不能这次返回字符串下次返回数组。第五个问题有没有办法在不影响用户的情况下验证也就是灰度能力。能不能先对内部账号开放或者先在一个隔离环境里跑确认没问题再全量这五个问题看起来简单但真正逐条回答的时候你会发现很多设计上的模糊地带。而这些模糊地带恰恰就是线上事故的高发区。1.3 质量保障的三个层次功能、边界、安全我把 Skill 的质量保障分成三个层次从低到高分别是功能验证、边界覆盖和安全收敛。功能验证是最基础的确认正常输入能得到预期输出。边界覆盖是进阶的确认异常输入不会导致崩溃或错误行为。安全收敛是最高层的确认即使 Skill 被恶意利用也不会造成超出预期的破坏。这三个层次不是并列关系而是递进关系。功能验证没过谈边界没有意义边界覆盖没做谈安全就是空中楼阁。但现实中很多人只做了第一层就上线了因为功能验证最容易做写几个正常用例跑通就行。边界和安全需要构造大量“不按套路出牌”的输入费时费力而且短期内看不到收益——直到出事。我的建议是把三个层次的测试用例都纳入 CI 流程。每次修改 Skill 定义或工具配置都自动跑一遍。这样虽然前期投入大但后期每次迭代都能快速确认没有引入回归问题长期来看反而省时间。2. 把 Skill 写好的核心要素意图、工具与输出2.1 意图描述让 Agent 知道“做什么”和“不做什么”Skill 的本质是一段给 Agent 看的说明书。这段说明书的质量直接决定了 Agent 的行为边界。我见过很多 Skill 的描述写得像产品需求文档充满了“尽可能”“尽量”“优先”这类模糊词汇。Agent 不是人它不会“领会精神”它只会严格按照字面意思执行。你写“尽量删除临时文件”它可能把不该删的也删了因为它认为“尽量”就是“能删就删”。好的意图描述应该包含三个部分任务定义、约束条件、例外处理。任务定义说清楚这个 Skill 要完成什么用动词开头一句话讲明白。约束条件列出所有“不能做”的事情比如“不得修改原始文件”“不得访问指定目录之外的路径”“不得在输出中包含敏感字段”。例外处理说明当约束条件与任务目标冲突时怎么办比如“如果目标文件不存在返回错误码而不是创建新文件”。我习惯用这样的结构来写意图描述## 任务 将指定目录下的日志文件按日期归档到对应月份的子目录中。 ## 约束 - 只处理 .log 后缀的文件 - 不修改文件内容只移动位置 - 目标目录必须已存在不自动创建 - 如果同名文件已存在跳过并在结果中标记 ## 例外 - 如果源目录不存在返回错误码 ENOENT - 如果目标目录不存在返回错误码 ENOENT - 如果文件正在被占用跳过并在结果中标记这种结构化的写法比一段散文式的描述要可靠得多。Agent 解析起来歧义更少测试的时候也更容易对照检查。2.2 工具选型能用只读就不用读写能限定就不用全局Skill 的能力来自于它挂载的工具。工具给得越多Skill 能做的事情越多但出错的概率也越大。我的原则是能用只读工具就不用读写工具能限定范围就不用全局权限能一步完成就不要拆成多步。举个例子如果一个 Skill 只需要读取文件内容做分析那就只挂载读取工具不要挂载写入工具。这样即使 Agent 理解错了意图它也没有能力去修改文件。这就是所谓的“能力最小化”原则——不是靠提示词去约束行为而是靠工具权限从物理上限制行为。再比如如果 Skill 需要访问某个 API尽量使用限定范围的凭证而不是管理员级别的密钥。如果 API 支持按资源粒度授权就精确到具体资源。如果支持 IP 白名单就加上。每多一层限制就少一类潜在事故。还有一个容易被忽略的点工具的调用顺序。有些 Skill 需要先读后写如果 Agent 把顺序搞反了可能造成数据不一致。这种情况下可以考虑把多个步骤封装成一个原子操作的工具或者用状态机来约束调用顺序。虽然实现起来麻烦一点但比事后修数据要划算得多。2.3 输出格式结构化、可验证、可追溯输出格式的稳定性是 Skill 能否被集成到自动化流程中的关键。如果输出是自由文本下游就没法可靠地解析。我强烈建议所有 Skill 的输出都采用结构化格式比如 JSON 或 YAML并且明确定义每个字段的类型和含义。一个典型的输出结构应该包含状态码、结果数据、错误信息、执行元数据。状态码用枚举值比如 success、partial、failed。结果数据根据具体任务定义。错误信息在失败时填充包含错误类型和可读的描述。执行元数据包括时间戳、耗时、处理的记录数等方便排查问题。{ status: partial, data: { processed: 42, skipped: 3, skipped_files: [a.log, b.log, c.log] }, error: null, meta: { started_at: 2025-01-15T10:30:00Z, duration_ms: 1250, skill_version: 1.2.0 } }这种结构的好处是下游可以根据 status 字段决定后续流程根据 data 字段做进一步处理根据 error 字段做告警根据 meta 字段做监控。每个字段都有明确的用途不会出现“这个字段有时候有有时候没有”的情况。另外输出中不要包含敏感信息。比如文件路径中可能包含用户名API 响应中可能包含令牌。如果确实需要输出这些信息用于调试应该做脱敏处理或者只在 debug 模式下输出。3. 测试 Skill 的完整方法论从单元到集成3.1 测试用例设计正常路径、边界路径、异常路径测试用例的设计核心是覆盖三类路径正常路径、边界路径、异常路径。正常路径验证功能是否正确边界路径验证极端输入下的行为异常路径验证失败时的处理。正常路径的用例比较好写就是典型的输入和预期的输出。比如“归档日志”这个 Skill正常路径就是给一个包含若干 .log 文件的目录验证文件是否被正确移动到对应月份的子目录。边界路径需要动点脑筋。常见的边界包括空输入、单个元素、最大数量、超长字符串、特殊字符、重复元素、大小写差异、路径中的空格和中文。比如空目录、只有一个文件、文件名超长、文件名包含空格或中文、同一天有多个文件、文件名大小写不一致等。异常路径是最容易被忽略的。常见的异常包括源目录不存在、目标目录不存在、文件被占用、权限不足、磁盘空间不足、网络超时。这些情况在本地测试时很难复现但线上一定会遇到。我的做法是用 mock 工具模拟这些异常确认 Skill 的行为符合预期——是返回错误码还是重试还是跳过。我通常会维护一个测试用例表每个用例包含用例编号、输入描述、预期输出、实际输出、是否通过。这个表随着 Skill 的迭代不断补充成为回归测试的基础。用例编号类型输入描述预期行为TC-001正常目录含 3 个 .log 文件全部归档statussuccessTC-002边界空目录不报错statussuccessprocessed0TC-003边界文件名含中文和空格正常归档TC-004异常源目录不存在statusfailederrorENOENTTC-005异常目标目录不存在statusfailederrorENOENTTC-006异常文件被占用跳过该文件statuspartial3.2 自动化测试让每次修改都能快速回归手工测试只能覆盖有限的场景而且每次修改都要重新跑一遍效率极低。自动化测试是必须的。对于 Agent Skills自动化测试的难点在于 Agent 的行为有一定的不确定性——同样的输入可能因为模型版本、温度参数、上下文长度的不同而产生不同的输出。我的做法是分层测试。第一层是工具层的单元测试直接测试 Skill 挂载的每个工具函数这部分是确定性的可以用传统的单元测试框架。第二层是 Skill 层的集成测试模拟 Agent 调用 Skill 的过程验证输入到输出的映射关系。这一层需要固定模型版本和参数尽量减少随机性。第三层是端到端测试在真实或接近真实的环境中跑完整流程验证与其他系统的交互。工具层的单元测试用 pytest 或 jest 这类框架就行重点是覆盖所有分支和异常。Skill 层的集成测试可以用一个固定的测试 harness把 Agent 的决策过程 mock 掉直接测试 Skill 定义和工具组合的行为。端到端测试则需要在隔离环境中部署完整的 Agent 运行时用预定义的输入跑一遍对比输出。自动化测试的另一个好处是可以把测试用例作为 Skill 的“契约”。每次修改 Skill 定义如果测试挂了说明修改影响了已有行为需要确认是有意为之还是引入了 bug。这种反馈循环比人工 review 要可靠得多。3.3 灰度与回滚上线前的最后一道防线即使测试再充分线上环境总会有测试覆盖不到的情况。灰度发布是降低风险的有效手段。具体做法是先把新版本的 Skill 开放给一小部分用户或流量观察一段时间确认没有异常后再逐步扩大范围。灰度的维度可以按用户、按请求量、按时间段来划分。比如先对内部账号开放跑一天没问题再对 1% 的外部用户开放再逐步扩大到 10%、50%、100%。每个阶段都要有明确的观察指标和回滚条件。观察指标包括成功率、错误率、平均耗时、异常日志数量。回滚条件比如错误率超过 1%、出现未预期的错误类型、耗时超过阈值。回滚预案要提前准备好不能等出事了再想。回滚的方式取决于 Skill 的部署形态。如果是配置类的 Skill回滚就是切回旧版本的配置。如果是代码类的 Skill回滚就是重新部署旧版本。无论哪种方式都要确保回滚操作本身是经过验证的不会因为回滚引入新的问题。我个人的习惯是每次上线新版本之前先把旧版本的配置和代码打一个 tag记录在案。回滚的时候直接切到 tag 对应的版本避免手忙脚乱找错文件。4. 权限与安全Skill 上线的红线4.1 权限最小化从“能做什么”到“只能做什么”权限最小化是 Skill 安全的第一原则。很多事故的根源不是 Skill 的逻辑写错了而是权限给大了。一个只需要读取配置的 Skill如果被赋予了写入权限那么当 Agent 理解偏差时就可能修改配置导致服务异常。实现权限最小化需要从几个层面入手。文件系统层面限定 Skill 只能访问特定目录并且区分读写权限。如果只需要读取就挂载只读。如果只需要写入特定文件就精确到文件级别而不是整个目录。网络层面限定 Skill 只能访问白名单内的地址避免被诱导访问恶意端点。API 层面使用最小权限的凭证避免使用管理员密钥。还有一个容易被忽略的点环境隔离。如果 Skill 需要执行代码或命令尽量在沙箱或容器中运行限制其对宿主环境的影响。即使 Skill 被恶意利用破坏范围也被限制在沙箱内。我见过一个案例一个“清理临时文件”的 Skill因为挂载了全局的删除权限结果 Agent 把用户的重要文件也删了。如果当初只挂载了特定临时目录的删除权限这个事故就不会发生。权限最小化不是限制功能而是限制破坏范围。4.2 输入校验不信任任何外部输入Agent Skills 的输入可能来自用户、来自其他系统、来自模型自身的生成。无论来源是什么都不能信任。输入校验的目标是确保输入符合预期的格式和范围拒绝任何可疑的内容。常见的校验包括类型校验是不是字符串、是不是数字、长度校验是否超过最大长度、格式校验是否符合正则表达式、范围校验是否在允许的枚举值内、内容校验是否包含注入字符。对于文件路径还要校验是否包含..等路径穿越字符。对于命令参数要校验是否包含 shell 元字符。校验失败时的行为也很重要。是直接拒绝并返回错误还是尝试清洗后继续我的建议是直接拒绝因为清洗规则很难覆盖所有情况而且清洗后的输入可能仍然有风险。直接拒绝虽然用户体验差一点但安全边界清晰。另外校验要在 Skill 的最外层做不要依赖 Agent 去判断。Agent 的判断是不可靠的它可能被诱导绕过校验。把校验逻辑放在工具函数内部作为第一道防线这样无论 Agent 怎么调用校验都会执行。4.3 审计与监控出了问题能查到原因审计日志是安全体系的重要组成部分。每次 Skill 被调用都应该记录谁调用的、什么时候调用的、输入是什么、输出是什么、耗时多少、是否成功。这些日志在排查问题时非常有用也是事后追责的依据。审计日志本身也要注意安全。日志中不能包含敏感信息比如密码、令牌、个人隐私数据。如果确实需要记录要做脱敏处理。日志的存储也要有访问控制避免被未授权的人查看。监控是在审计日志的基础上做实时告警。比如错误率突然升高、出现未预期的错误类型、调用量异常增长、单次调用耗时过长。这些指标可以帮助你第一时间发现异常而不是等用户投诉才知道出了问题。我通常会设置几个关键的告警规则错误率超过 5% 持续 5 分钟、出现新的错误类型、单次调用耗时超过 30 秒、调用量超过历史峰值的 2 倍。这些规则不是一成不变的需要根据实际情况调整。太敏感会导致告警疲劳太迟钝会错过问题。5. 常见问题与排查技巧实录5.1 输出格式飘忽不定怎么办这是最常见的问题之一。同样的输入有时候返回 JSON有时候返回带解释的文本。原因通常是 Skill 的意图描述中没有强制输出格式或者 Agent 在遇到不确定的情况时“自由发挥”了。解决办法是在 Skill 定义中明确输出格式并且给出示例。示例要尽可能详细包括成功和失败两种情况。另外可以在工具函数中对输出做后处理强制转换为结构化格式。如果 Agent 返回的是自由文本工具函数尝试解析解析失败就返回标准错误格式。还有一个技巧是在 Skill 描述中加入“无论结果如何都必须以 JSON 格式返回”这样的强制语句。虽然不能 100% 保证但能显著提高一致性。5.2 权限不足导致的静默失败权限不足时有些工具会返回空结果而不是报错导致 Skill 看起来“成功”了但实际上什么都没做。这种静默失败非常危险因为下游可能基于错误的结果继续执行。排查方法是在工具函数中显式检查权限如果权限不足主动抛出错误而不是依赖底层工具的返回值。另外在测试用例中专门覆盖权限不足的场景确认 Skill 的行为是报错而不是静默成功。如果 Skill 需要访问某个资源但权限配置可能因环境而异可以在 Skill 启动时做一次权限自检确认所有需要的权限都已具备。自检失败就拒绝启动避免运行到一半才发现问题。5.3 常见问题速查表问题现象可能原因排查方法解决方案输出格式不一致意图描述未强制格式检查 Skill 定义中的输出部分增加格式约束和示例静默失败权限不足但未报错检查工具函数的错误处理显式检查权限并抛错部分完成多步操作中途失败检查日志中的中间状态增加事务或补偿逻辑耗时过长工具调用阻塞检查各步骤耗时增加超时和异步处理误操作权限过大检查工具挂载的权限范围收敛到最小权限注入风险输入未校验检查输入处理逻辑增加校验和转义5.4 几个我踩过的坑第一个坑是过度依赖 Agent 的判断。我曾经写过一个 Skill在描述中说“如果文件超过 10MB 就跳过”。结果 Agent 有时候判断对了有时候判断错了因为它对“10MB”的理解不稳定。后来我改成在工具函数中硬编码这个阈值Agent 只负责传递文件路径判断逻辑由代码执行。这样就稳定了。第二个坑是忽略了并发场景。一个 Skill 在单次调用时没问题但多个调用并发执行时可能同时读写同一个文件导致数据不一致。解决办法是加锁或者使用原子操作。如果 Skill 本身不支持并发就在描述中明确说明“此 Skill 不支持并发调用”。第三个坑是回滚不彻底。有一次上线新版本后发现问题回滚到旧版本但旧版本依赖的一个配置已经被新版本修改了导致回滚后仍然异常。后来我养成了习惯每次上线前把相关配置也一起备份回滚时一并恢复。第四个坑是日志中泄露敏感信息。有一次排查问题时发现审计日志中记录了完整的 API 响应其中包含用户的令牌。虽然日志的访问有控制但仍然是不必要的风险。后来我在日志记录前增加了脱敏步骤把令牌、密码等字段替换为掩码。这些坑的共同点是它们都不是功能逻辑的问题而是工程实践的问题。功能逻辑可以通过测试发现但工程实践的问题往往要在真实环境中才会暴露。所以我的建议是在加固期就要考虑这些场景不要等到上线后才补。6. 从开发到上线的完整检查清单6.1 上线前的自检项在点击“发布”按钮之前我通常会过一遍这个清单。每一项都确认无误才敢上线。意图描述是否包含任务、约束、例外三个部分工具权限是否已经收敛到最小范围输出格式是否结构化且有明确定义测试用例是否覆盖正常、边界、异常三类路径自动化测试是否全部通过审计日志是否已配置且脱敏监控告警规则是否已设置回滚预案是否已准备并验证灰度计划是否已制定相关文档是否已更新这个清单看起来繁琐但每一条都对应着一种常见的线上问题。花半小时过一遍清单可能省下几小时的排查时间。6.2 上线后的观察要点上线不是终点而是另一个起点。新版本上线后的前几个小时是最关键的观察期。我通常会盯着几个指标错误率、耗时、调用量、异常日志。如果错误率突然升高或者出现未预期的错误类型就立即回滚。除了技术指标还要关注用户反馈。有时候技术指标正常但用户感知到了问题比如输出内容不符合预期、操作结果与预期不符。这些反馈往往能发现测试覆盖不到的盲区。观察期结束后如果一切正常就可以逐步扩大灰度范围。每次扩大范围后都要重新观察一段时间。不要一次性全量给自己留出反应时间。6.3 持续迭代的心态Skill 的上线不是一劳永逸的。随着使用场景的变化、依赖工具的更新、模型版本的升级Skill 的行为可能会发生变化。所以需要定期回顾和更新。我个人的习惯是每个月回顾一次线上 Skill 的运行情况看看有没有新的错误模式、有没有可以优化的地方、有没有需要补充的测试用例。另外每次模型版本升级后都要重新跑一遍回归测试确认行为没有变化。还有一点很重要记录每次变更的原因和影响。这样当出现问题时可以快速定位到是哪次变更引入的。变更记录不需要很复杂一句话说明改了什么、为什么改就行。但一定要记否则时间久了就忘了。说到底Skill 的质量保障是一个持续的过程而不是一次性的任务。写好、测好、安全上线每个环节都需要认真对待。但也不用追求完美先保证核心路径可靠、权限收敛、有回滚预案就已经超过了大多数人了。剩下的可以在迭代中逐步完善。