AI Agent Skills 团队上线前怎么验收？2026 清单

Agent Skills 规范规定，name 最多 64 个字符，description 最多 1024 个字符；这类格式门槛是验收起点，不是上线证明。AI Agent Skills 团队验收不能停在确认 SKILL.md 存在：先限定支持的客户端与运行环境，再核查发现方式、触发边界、依赖权限和可重复任务结果，最后按证据决定发布、限制试用或退回修改。

谁该看：正把个人 Skill 推广给团队的开发者，可按清单补齐发布证据。维护 Claude Code Skills 或 Codex Skills 工作流的平台工程师，以及负责自动化权限审查的技术负责人，可用本文核对不同客户端的实际行为。

最后更新于 2026 年 10 月 9 日；文件格式与客户端支持范围按 Agent Skills 规范、Claude Code Skills 文档及Codex Skills 文档复核。以下内容区分规范要求与客户端行为，不包含本站实测成功率或耗时数据。

先限定验收对象与兼容范围

“遵循开放格式”不等于“所有客户端以相同方式加载和执行”。规范定义通用文件结构，但技能存放位置、发现范围、调用机制、脚本运行与权限策略仍取决于具体产品及其版本。把这两层混为一谈，容易让团队误以为同一个文件在每个环境都已通过验收。

发布记录先写清以下信息：

• [ ] 支持的客户端与版本范围：逐一列出团队实际使用的 Agent，以及验收时对应的版本或运行方式；没有验证过的客户端标为“未验收”，不写“兼容”。
• [ ] 技能存放与共享方式：注明技能来自项目仓库、用户目录、管理员目录、插件包还是 API 上传；把安装位置和权限责任写进发布说明。
• [ ] 运行环境：记录操作系统、工作目录、可用命令、网络访问与文件读写边界。若脚本依赖某个系统工具、解释器或环境变量，应写出依赖，而不是假设每位成员都有。
• [ ] 兼容性结论的范围：写成“在指定客户端、版本与环境中完成验证”，不把一次成功扩大为所有客户端、所有版本均可用。

例如，Claude Code 文档说明项目技能可放在仓库的 .claude/skills/；当前 Codex 文档列出的仓库技能发现位置则包括 .agents/skills。这意味着共享文件前要分别核对目标客户端的目录规则，不能只把 Skill 目录复制到一个自定位置，就据此认定客户端会发现它们。具体位置与行为应以各自的官方文档为准。

按指标完成 AI Agent Skills 团队验收

格式与可发现性：SKILL.md 是否合规并被客户端加载？

规范要求 SKILL.md 使用 YAML 前置元数据与 Markdown 正文，必需字段为 name 和 description；其中 name 还必须符合命名规则并匹配技能目录名。规范建议主文件少于 500 行，并允许配套 scripts/、references/ 与 assets/ 等资源目录。字段与目录要求应以 Agent Skills 规范为准。

• [ ] YAML 可解析，必需字段非空；字段拼写、类型及目录名符合规范。
• [ ] description 说明技能做什么、何时适用，并明确相邻但不适用的任务；“帮助处理代码”这类笼统描述难以作为有效触发信号。
• [ ] 被引用的文件确实存在，路径相对技能根目录可解析；大小写、空格和符号在目标环境中均已核对。
• [ ] 在每个目标客户端中确认技能出现在其技能列表或等效的发现界面，并尝试显式调用。

这一层要留两种证据：静态检查结果，以及客户端侧发现记录。浏览仓库看到文件，不等于运行中的 Agent 已加载它。Claude Code 和 Codex 的目录规则不同，不能依据一个客户端的发现结果推断另一个客户端也已通过验收。

触发边界：目标任务会触发，相邻任务会避开吗？

可发现只说明客户端找到了技能，不代表它会在恰当时机选择使用。触发验收应同时测试“该触发”和“不该触发”的任务，避免描述过宽导致误调用，也避免描述过窄造成漏调用。

• [ ] 准备真实目标请求，去掉显式技能名称，观察 Agent 是否会自然选择技能。
• [ ] 加入语境变化，例如不同措辞、已有项目文件或非空工作目录，观察触发是否依然符合预期。
• [ ] 准备相似但不适用的请求，记录是否误触发；若任务要求只在用户明确指定时执行，也要验证隐式调用是否被限制。
• [ ] 保存请求原文、客户端版本、是否触发和最终处理方式；根据误触发或漏触发的案例调整描述，再重跑同一组样例。

OpenAI 关于系统化评测 Agent Skills 的示例建议从小型、针对性的提示集开始，并将漏触发、误触发和环境假设变成可复核的测试案例。重点不是照抄固定样本数量，而是让每条样例对应一条明确判断：应该触发，还是不应该触发。

脚本与引用资源：团队共享 Skill 怎样审查依赖和权限？

纯指令型 Skill 通常只增加流程说明；附带脚本、访问文件或请求外部资源的 Skill，则可能引入可执行行为、数据暴露和供应链变更。两者不应套用同一套批准方式。规范也提醒 allowed-tools 字段仍属实验性能力，支持程度可能因实现而异，所以不能把它当作跨客户端一致生效的权限控制。审查技能内容及执行风险时，也可参照Claude Code 安全文档。

• [ ] 列出所有脚本、包管理文件、外部网址和间接依赖；检查实际执行命令与技能用途是否一致。
• [ ] 标明每个脚本需要读取、写入或删除的目录；若会访问网络，说明目标域名、传输数据与失败时的处理方式。
• [ ] 检查是否读取令牌、配置文件、密钥或用户数据；密钥不应写入技能目录、示例文件或调试输出。
• [ ] 在隔离环境中验证脚本与工作流；默认不给不必要的写权限、网络权限或凭据。
• [ ] 记录技能来源、审查人、固定版本或提交号，并核实更新后的依赖是否仍在允许范围内。

⚠️ “技能格式合规”只能说明文件符合格式门槛，不代表其中的指令、脚本或远程资源可信。只要技能能影响工具选择、命令执行或敏感文件访问，就应按团队的软件与权限变更流程审查。

任务结果：怎样证明 Skill 在真实工作流中有效？

先定义任务的输入、完成标准和失败时的安全行为，再执行测试。否则，即使最终文字看起来合理，也无法判断 Agent 是否真正调用技能、是否遵循关键步骤，或是否留下意外文件。Codex 的评测示例将运行轨迹、产物和检查规则作为记录对象；OpenAI 的 Agent 工作流评测指南也建议用可重复数据集比较工作流，而非只看单次运行。

• [ ] 选取代表性输入，并准备预期产物或明确的验收标准。
• [ ] 单独记录是否触发、关键命令或工具是否按预期使用、输出是否满足任务要求。
• [ ] 加入边界输入：缺少依赖、输入不完整、权限不足，或遇到目标目录已有文件时，验证技能会正确停止、提示或回退。
• [ ] 在每个受支持的客户端与环境中执行同一批代表性任务，留存日志、输出差异与失败原因。
• [ ] 把发现的问题转成回归样例，技能修改后重新执行，而不是用新样例替换旧失败记录。

输出评分可拆成确定性检查与人工或规则审查：前者检查文件、字段、命令或退出状态，后者评估表达质量、业务逻辑或是否遵循约定。记录所用数据集、技能版本、客户端版本与评测结果，才便于发现升级后的行为变化；OpenAI 的 Evals 指南提供了任务定义、测试输入与结果分析的评测流程参考。

按证据决定发布、试用或退回

若格式检查通过、目标客户端已发现技能、正反向触发样例符合预期、依赖与权限均有审查记录，且代表性任务达到预先写明的完成标准，则可按声明范围发布。
若核心流程正常，但某个客户端、环境或边界任务尚未验证，则限制在已验证范围内试用，并明确未覆盖条件。
若文件无法加载、出现不必要的网络或文件访问、触发边界不清，或任务产物未达到标准，则退回修改，不以一次成功运行覆盖失败证据。

发布记录至少包含技能版本或提交号、支持客户端及环境、检查结果、遗留限制、批准人和复验触发条件。新增脚本或依赖、调整文件路径、修改权限、更新技能内容，以及客户端升级，都可能改变发现或执行行为；发生这些变化时，应按影响范围重新验收。即使共享文件没有变化，也不应默认升级后的客户端仍保留原有行为。

如果当前验收依赖各成员自己的 Mac，常见隐性成本是环境版本不一致、权限设置分散，以及测试记录难以复现；若改用公共远程环境，又要先核对网络、凭据和数据边界。团队只有在需要 macOS 工作流或隔离的 Mac 测试环境时，才有理由把 Mac 纳入验收方案；以 Linux 或 Windows 为主要运行目标的团队，不必为了这份清单额外迁移。若要在可控环境中验证面向 Mac 的工作流，可先查看 nuvcloud 的 Mac 环境选项及环境使用说明，再用一项低风险、可回滚的真实任务跑完整张清单；临时测试适合按需租赁 nuvcloud 的 Mac 环境，长期稳定重负载或必须连接特定物理设备的工作，则应先比较自购设备与团队现有基础设施是否更合适。