团队的 Skill 越写越长，怎样整理到真正好用？

把一次修正，变成团队下次还能用的方法

团队刚做完成员邀请功能。为了下次方便，大家陆续存了发布摘要、文档检查、代码评审三个 Skill。后来，问一句“发布说明是什么”，AI 也开始读版本文件；只想查一条链接，它先翻完销售记录；要求评审代码，它却动手修改。问题已经不是有没有 Skill，而是它到底该在什么时候做什么。

这篇练习的产物很具体：三个修订后的 Skill、一组不会随说法改变的验收要求，以及一份真实运行记录。所有项目、输入和缺陷都是原创虚构示例。我们提供人工可核对的答案，实际模型表现需要你在自己的 Onevium 会话中运行后确认。

OpenAI 在 9 月 11 日的文章里建议重新审视 Skill 描述、资料加载方式和长期积累的项目指令。文章针对 GPT-6 Astra；这里借用的是维护方法，不把该模型的表现或触发行为当作所有服务商的保证。我们的例子围绕同一个成员邀请项目展开。

先判断是哪种问题，再决定删什么

Skill 可以理解为一个可复用的工作说明：入口描述告诉助手什么时候用，正文说明怎样做，参考文件保存按需查阅的细节。维护时先找到失败对应的这一层。直接把字数砍半，可能连真正重要的规则也删掉。

这三个例子的目标不是让 AI 永远少读文件，而是让必要的资料容易找到，让无关资料不挤进每一次任务。已经证实有用的输入要求、输出格式和验收标准仍然保留。

准备两个可以丢弃的演示项目

下载并解压练习包，在 team-skills-maintenance-starter 目录打开终端。需要 Node.js 20 或以上；下面的命令不安装依赖，也不调用模型。check.mjs 检查包内文件、引用和用例是否完整。两个 prepare 命令分别创建新的 before、after 临时目录，并打印完整路径。

在 Onevium 左侧“项目”旁点击添加项目，选择“打开已有文件夹”，打开打印出的其中一个目录。每个目录只有对应版本的三个项目 Skill，放在 .claude/skills/名称/SKILL.md。不要复制到个人技能目录；临时目录可能被系统清理，需要长期保留时，先复制到一个空练习目录再打开。

包外的 cases.json 和观察表留给你核对，不要作为任务附件全部交给模型，否则它可能直接读到答案。每条真实用例重新运行 prepare，以同样的初始文件开始；新会话本身不会复制或重置目录。

node --version
node check.mjs
node prepare.mjs before
node prepare.mjs after

第一处：把“相关就用”改成清楚的任务入口

发布交接 Skill 的原描述包含“任何代码、产品、文档或团队问题”。这些词几乎能覆盖整个项目，助手很难判断什么时候不该用。我们把入口改为“根据发布记录整理已发布改动和客服交接”，并排除术语问题、实施任务。下面是中文对照，包内也提供可直接使用的英文原稿和修订稿。

正文同时保留事实约束：从 inputs/release.json 读取版本；invite-expiry 和 resend-invite 是已发布；bulk-invite 仍是计划。范围清楚之后，输出也必须正确。模型是否真的按描述选中了 Skill，要在后面的自然语言用例中观察，不能靠读描述就宣布通过。

改前描述：
任何发布、代码、产品、文档或团队问题都使用本技能。

改后描述：
根据本项目发布记录整理已发布改动或客服交接；
不用于术语解释或功能实施。

完成要求：
版本 → 已发布改动及 ID → 单独列出的计划。
不把计划写成已发布，不修改文件，不发布消息。

第二处：让资料跟着任务加载

检查 docs/invite.md 的相对链接，不需要先读销售记录和发布计划。修订版的入口文件只保留任务范围、输出要求和一条参考链接；真正的路径解析规则放到 references/local-links.md，需要检查本地链接时再读。文件变短只是副作用，关键是每一份资料都有明确用途。

在这个练习里，setup.md 应解析成 docs/setup.md，文件存在；account-deletion.md 应解析成 docs/account-deletion.md，文件缺失。输出两条证据就能检查结果。这个 Skill 不校验网页片段锚点，也不访问远程网址；需要这些能力时再增加相应流程和测试，不能把未检查项写成正常。

doc-link-review/
  SKILL.md
    入口：检查指定 Markdown 文件的本地相对链接
    按需读取：references/local-links.md
    输出：原链接、解析后的路径、存在或缺失的证据
  references/
    local-links.md
      从来源文档目录解析路径
      不把缺失文件自动创建出来
      说明未覆盖的锚点检查

第三处：给冲突的动作一个明确边界

invite-review 的原稿同时写着“绝不修改文件”和“立即修复所有问题”。两句话都强硬，合在一起却没有可执行的边界。修订版只负责评审：引用规则、指出位置、给出失败输入，并在回答里建议改法。实施属于另一项明确的修改任务。

本例规则要求 now >= expiresAt 时邀请已经到期，源码第 2 行却写成 now > expiresAt。让 now 和 expiresAt 都取 1000，就能说明实际 false 为什么不符合要求。合格评审应说清这个差异，并建议 >=，同时保持文件不变。

这不是让团队所有动作都重新等待批准。你可以在 Skill 里清楚授权可逆的本地步骤；关键是读者知道这次到底交给它评审还是实施。Skill 文字也不是沙箱，真实运行时仍要核对工具动作；尝试写入但被权限拦截，也不能直接算作过程合格。

改前：
这次评审只读，绝不修改文件。
发现问题后立即修复并更新实现。

改后：
对照邀请到期规则评审指定源码。
报告：文件与行号、违反的规则、具体失败输入、建议改法。
只在回答中提出修正；不要修改文件或宣称已修复。

在 Onevium 跑同一组任务，看真实变化

打开“插件 → 技能”，在范围选择器选中演示项目并刷新。打开某个 Skill，核对名称、来源路径与正文。点击“使用技能”后，输入框会放入该 Skill 的引用；补充输入并发送，才会开始执行。这适合先检查手动调用是否能用。若找不到，检查项目、范围设置和原生 Claude 技能是否允许。

接下来测自然语言选择：为每条用例新建会话，只粘贴 cases.json 里的 prompt.zh 或 prompt.en，不附 Skill 名称和预期答案。before、after 固定相同服务商、模型、权限、语言与输入。检查是否有同名个人或插件 Skill，避免它们干扰。下面六条里，三条负向任务均不应进入这三个 Skill 的流程。

把最终回答、可见的工具活动和文件变化保存在项目之外，用 observation-template.json 记录实际结果。没有足够证据判断是否加载 Skill，就填 unknown；仅仅提到某个文件名不算确认。先核对事实和操作边界，再比较读取是否多余。关键用例重复运行，把失败留下来。

把维护结论交给下一次任务

本教程验证了练习包的文件完整性、固定输入、相对引用和核对要点，也验证了 prepare 能生成互相独立的目录。没有执行真实模型评测，不能据此声称修订版已经减少误触发、节省 token 或提升速度。这些字段留给你的实际运行记录。

团队采用修订版前，给每个改动留四项内容：为什么改、改了哪一层、哪条用例能抓住旧问题、谁复核了这次结果。优先修正误用、错误事实和越界动作，再整理无关读取，最后才做字句美化。更换模型或发现新的失败时，重跑相关用例；无需每次把所有 Skill 重写一遍。

在这组团队实践教程中，先用 Team 把复杂需求拆成可交接任务，再用 CI 诊断找出验证瓶颈；本篇把已经跑通的方法整理成可维护的 Skill。下一步把人工检查、返工和运行费用一起记录，判断整条工作流是否值得继续投入。