系列《把经验封装成能力Agent Skills 设计与落地》本文是系列第十六篇也是正文部分的收束篇。前十五篇已经讲完 Skill 的概念、结构、触发、资源组织、脚本协作、测试评估、迭代方法以及文档处理、开发工具、知识库三类真实案例。最后一篇我们把视角从“如何写一个 Skill”切到“团队如何长期使用 Skill”版本怎么管怎么分发谁来审核如何避免安全和合规风险什么时候推广什么时候废弃。1. 为什么最后要讲团队治理一个人写 Skill问题通常是这个 Skill 能不能触发输出是否符合预期脚本是否能运行参考资料是否组织清楚团队使用 Skill问题会变成谁能新增 Skill谁负责维护 SkillSkill 出问题后谁修旧版本还能不能继续用团队成员怎么安装和更新是否经过测试和评审是否会泄露敏感信息是否包含危险命令是否会误导 Agent 绕过权限什么时候应该下线或归档这已经不是单纯写作问题而是工程治理问题。Skill 一旦进入团队就不再只是个人提示词资产。它会影响团队的工作方式、交付质量和安全边界。所以系列最后必须讨论治理。2. Skill 是团队资产不是临时片段如果只是临时提示词写完用一次就结束。但 Skill 的目标是复用。复用意味着它会被不同人、不同 Agent、不同项目、不同时间反复使用。这就要求它像其他工程资产一样被管理。例如资产类型团队会怎么管理代码库owner、版本、测试、评审、发布API文档、版本、权限、兼容性、废弃策略数据表schema、血缘、质量检查、权限CI 流水线配置、日志、失败处理、审批Skillowner、description、测试 prompt、资源、脚本、安全边界Skill 也需要类似管理。否则它会变成一种新的隐性风险看起来很方便但没人知道是否可靠。看起来是团队规范但没人维护。看起来能自动化但内部藏了危险命令。看起来是最新知识但其实资料已经过期。治理不是为了增加流程负担而是为了让可复用能力真正可信。3. 团队 Skill 的五个治理对象团队落地时可以从五个对象入手。对象需要治理什么Skill 本身目标、边界、触发、资源、脚本、输出版本变更记录、兼容性、回滚、废弃分发安装方式、更新方式、权限范围质量测试、评审、验收、监控反馈安全密钥、权限、命令副作用、敏感数据这五个对象构成了团队 Skill 的基本治理框架。接下来逐个展开。4. Owner每个 Skill 都应该有负责人团队 Skill 必须有 owner。owner 不是“唯一能修改的人”而是“对质量和边界负责的人”。owner 至少负责判断这个 Skill 是否应该存在。维护 description 和主流程。审核资源和脚本变更。定期检查资料是否过期。处理使用反馈和失败案例。决定是否推广、冻结或废弃。没有 owner 的 Skill 很容易变成无人维护的知识包。尤其是知识库型 Skill 和工具型 Skill过期风险更高。例如API 文档更新了但 Skill 没更新。团队规范改了但 Skill 还按旧流程输出。脚本依赖升级了但 Skill 里的命令不可用。原 owner 离开团队后没有人知道这个 Skill 的设计意图。所以 owner 是第一道治理线。5. Skill 元信息应该补充团队字段Agent Skills 的最小 frontmatter 只需要---name:my-skilldescription:A clear description of what this skill does and when to use it.---但团队内部可以在文档正文中补充治理信息。例如## Ownership - Owner: DevInfra Team - Backup Owner: Platform Productivity Team - Reviewers: frontend-leads, backend-leads - Slack Channel: #agent-skills-support - Last Reviewed: 2026-07-11 - Status: pilot这些字段不一定都要放进 YAML frontmatter。因为不同平台对 frontmatter 字段支持可能不同。更稳妥的做法是name和description保持标准。治理信息写在正文固定小节。如果团队有额外工具可以再从正文或旁路 metadata 文件读取。6. StatusSkill 应该有生命周期状态团队 Skill 不应该只有“存在”和“不存在”两种状态。建议至少有五种状态。状态含义draft草稿正在设计不建议团队使用pilot试用中允许小范围使用和反馈active正式可用团队推荐使用deprecated已废弃不建议新任务使用archived已归档仅保留历史参考状态能帮助使用者判断风险。例如一个draftSkill 可以快速迭代但不能当作团队标准。一个activeSkill 应该经过测试、评审和发布。一个deprecatedSkill 应该告诉用户替代方案。示例## Status Status: deprecated This skill is deprecated because the team has moved from API v1 to API v2. Use acme-api-platform-v2 for new integrations.这比直接删除更友好。删除会让依赖它的人突然失去上下文。废弃状态可以给迁移留出窗口。7. 版本管理Skill 也需要变更记录Skill 变更会影响 Agent 行为。比如改 description可能改变触发范围。改 Workflow可能改变执行步骤。改 Output Format可能影响下游脚本。改 references可能改变知识依据。改 scripts可能改变执行结果或副作用。这些都应该记录。简单做法是在 Skill 目录下维护CHANGELOG.md或者在SKILL.md末尾维护简短变更记录。推荐独立文件。因为 Skill 主文件应该尽量服务运行时不要承载过多历史信息。8. 版本号怎么定团队内部可以用语义化版本但不必过度复杂。建议版本变化适用情况patch修正文案、示例、轻微 bug不改变触发和输出契约minor新增能力、参考资料、测试用例保持兼容major改变触发范围、输出格式、脚本副作用或核心流程例如1.2.3含义1主版本。2能力新增或兼容扩展。3修复和小改动。不一定每个小团队都要严格语义化。但至少要区分安全小修。能力扩展。破坏性变更。9. 变更记录应该写什么一个好的 Skill 变更记录应该面向使用者。不要只写update skill更好的写法## 1.3.0 变更主题扩展本地 API 冒烟测试的错误处理 变更内容 1. 新增 references/failure-handling.md补充端口不可达、状态码不符和 JSON 解析失败的处理建议。 2. 更新 Workflow要求输出通过、失败和未验证项。 3. 新增 3 条负向测试 prompt覆盖生产写操作和压测误触发场景。 验证情况已运行 8 条测试 prompt未发现旧的健康检查场景回归。这样的记录能回答改了什么为什么改影响范围是什么怎么验证这也是团队评审需要的信息。10. 哪些变更需要重点评审不是每个标点都需要重审。但以下变更应该重点评审。变更类型风险description 修改可能导致欠触发或误触发skip 条件修改可能抢占其他 Skill 的任务Workflow 修改可能改变执行顺序和行为Output Format 修改可能破坏下游依赖scripts 修改可能引入副作用或安全问题references 更新可能引入过期、错误或敏感知识权限相关说明修改可能绕过团队安全边界默认模型、默认平台、默认环境修改可能影响成本、质量或合规团队可以约定文案小修一人 review。description、脚本、安全相关变更至少两人 review。涉及生产系统、权限、密钥、外部 API 写操作的 Skill 必须安全 review。11. 分发方式一仓库分发最简单的团队分发方式是仓库。例如team-agent-skills/ ├── skills/ │ ├── api-review/ │ ├── release-notes/ │ ├── local-api-smoke-test/ │ └── incident-summary/ ├── docs/ │ ├── contribution-guide.md │ └── review-checklist.md └── README.md优点和代码一样走 PR。方便审查变更。可以跑测试。可以记录版本。可以和团队文档放一起。缺点安装和更新需要额外说明。多团队共享时可能需要权限管理。不同项目可能需要不同 Skill 子集。仓库分发适合早期和内部团队。12. 分发方式二插件市场或集合分发当前仓库里有.claude-plugin/marketplace.json。它把 Skill 分成几个集合。例如document-skills包含xlsx、docx、pptx、pdf。example-skills包含mcp-builder、webapp-testing、skill-creator等示例。claude-api单独作为 API/SDK 文档型 Skill。这种方式有几个好处用户可以按集合安装。不同能力可以分层发布。文档处理、开发工具、知识库可以拆成不同包。对外或跨团队分发更清晰。团队内部也可以类似设计{name:company-agent-skills,metadata:{description:Company internal Agent Skills,version:1.0.0},plugins:[{name:engineering-skills,description:Skills for code review, local testing, release notes, and API integration,source:./,strict:false,skills:[./skills/code-review-guide,./skills/local-api-smoke-test,./skills/release-notes]},{name:document-skills,description:Skills for team docs, PRD, contracts, and meeting summaries,source:./,strict:false,skills:[./skills/prd-writer,./skills/meeting-summary,./skills/contract-summary]}]}这适合团队规模更大、Skill 数量更多的场景。13. 分发方式三项目内目录有些 Skill 只适合某个项目。比如某个服务的排障流程。某个业务线的 API 集成规范。某个仓库的发布流程。某个系统的值班复盘模板。这些 Skill 可以放在项目内。例如payment-service/ ├── src/ ├── tests/ ├── docs/ └── .agent-skills/ ├── payment-debugging/ ├── release-checklist/ └── incident-summary/优点和项目代码一起演进。更贴近项目上下文。修改流程可以和业务变更一起 review。缺点跨项目复用较弱。容易形成多个相似 Skill。需要定期抽象和合并。项目内 Skill 适合项目特有流程。通用 Skill 则更适合放团队级仓库。14. 分发方式四内部模板有些 Skill 不一定直接分发成可用能力而是作为模板。例如templates/ ├── api-knowledge-skill/ ├── local-testing-skill/ ├── document-processing-skill/ └── writing-style-skill/团队成员创建新 Skill 时从模板复制并填写owner。description。workflow。resource routing。test prompts。safety notes。changelog。模板的价值是统一质量底线。它不能替代评审但能减少遗漏。15. 推荐的分发策略可以按成熟度选择分发方式。阶段推荐方式草稿期个人目录或项目分支试用期项目内目录或团队仓库 pilot 区正式期团队仓库或插件集合跨团队推广插件市场、统一文档和版本发布废弃期保留归档目录和迁移说明不要一开始就追求复杂分发。先小范围验证再扩大。这和第十二篇讲的小步迭代是一致的。16. 安全边界一不要写入敏感密钥Skill 中不应该包含API key。OAuth token。Cookie。私钥。数据库密码。生产环境临时凭证。内部用户隐私数据样本。哪怕是示例也不要放真实值。示例应该写成ACME_API_TOKENyour-token-here或者export ACME_API_TOKENredacted更好的做法是告诉 Agent 从环境变量或安全凭证系统读取。例如Do not ask the user to paste secrets into chat. Use environment variables or the approved credential provider. Never write secrets into generated files.这类规则应该进入安全审查清单。17. 安全边界二不要隐藏危险命令Skill 可能包含脚本。脚本是高价值能力也可能带来风险。危险命令包括删除文件。清空数据库。修改生产配置。执行远程脚本。提交或推送代码。关闭服务。绕过权限检查。团队 Skill 中不能把危险操作藏在脚本里。如果确实需要支持高风险操作必须明确写在 description 或安全说明里。默认只读或 dry-run。要求用户显式确认。输出将执行的命令。记录执行结果。支持回滚或恢复方案。例如## Safety - Default to dry-run mode. - Do not execute destructive operations without explicit user confirmation. - Print the target environment, resource IDs, and planned operation before execution. - Refuse to run against production unless the user confirms the production environment by name.危险命令不是绝对不能做。但不能隐藏不能默认执行不能绕过确认。18. 安全边界三不要绕过权限Skill 不应该教 Agent 绕过团队权限。例如不应该写如果没有权限就尝试从其他路径读取配置。也不应该写如果接口拒绝访问就伪造管理员 header。正确做法是使用正式权限路径。如果权限不足提示用户申请权限。不尝试规避审计。不生成规避访问控制的脚本。Skill 是能力包不是权限提升工具。团队治理必须明确这一点。19. 安全边界四敏感数据最小化很多 Skill 会处理文档、日志、代码、用户数据。团队需要定义数据边界。例如数据类型处理建议公开文档可用于示例和测试内部文档只能在授权范围内使用客户数据默认脱敏避免写入 Skill生产日志截取必要片段去除 token 和个人信息密钥和凭证不进入 Skill、不进入测试样本、不进入日志Skill 中的示例、测试 prompt、fixtures 都要检查敏感信息。这是很多团队容易忽略的地方。测试 prompt 也可能泄密。20. 安全边界五外部依赖和网络访问如果 Skill 的脚本会访问外部网络需要写清楚访问哪些域名。是否会上传文件。是否会发送用户数据。是否需要认证。是否有日志记录。是否会改变外部系统状态。例如## Network Behavior - This skill may call the internal staging API at https://staging-api.example.com. - It must not call production endpoints unless the user explicitly confirms. - It must not upload local files to external services. - It must redact tokens from logs.网络行为越清楚团队越容易审核和信任。21. 质量门禁一description 审查description 是触发入口。团队评审时必须看它。审查重点是否覆盖真实触发表达是否写清能力边界是否过宽会误触发是否过窄会欠触发是否包含排除条件是否和其他 Skill 冲突是否会抢占不属于它的任务可以要求每个新 Skill 提交时附带## Trigger Examples Should trigger: 1. ... 2. ... 3. ... Should not trigger: 1. ... 2. ... 3. ...没有正负触发样例的 description很难审。22. 质量门禁二测试 prompt第十一篇讲过测试 prompt。团队级 Skill 至少要有一组基础测试。建议包含典型成功场景。模糊表达场景。输入不足场景。相邻任务负向场景。复合任务场景。安全边界场景。例如本地 API 冒烟测试 Skill可以有“帮我检查本地/health。”“服务在 3000 端口做个冒烟测试。”“帮我压测这个接口。”“调用生产接口删除测试用户。”“先看健康检查再总结失败原因。”测试 prompt 不需要一开始很多。但每个正式 Skill 至少应该有能覆盖核心风险的样本。23. 质量门禁三脚本校验有脚本的 Skill 必须审脚本。审查重点是否有--help。参数是否显式。默认是否安全。是否有 dry-run。是否有清晰退出码。错误信息是否可行动。是否会修改文件或外部系统。是否会记录敏感信息。是否有超时和资源清理。是否避免不必要的全量扫描。脚本不应该因为藏在 Skill 里就绕过代码审查。脚本就是代码。应该按代码标准评审。24. 质量门禁四参考资料审查references 也需要审查。尤其是知识库型 Skill。审查重点是否有来源。是否有更新时间。是否包含过期信息。是否和团队当前规范一致。是否包含敏感内容。是否指向已失效链接。是否有版本边界。是否和其他参考资料冲突。如果资料变化快应该要求标注缓存日期。提供 live source。定期复审。25. 质量门禁五人工 review自动测试很重要但不能替代人工 review。Skill review 至少应该看目标是否清楚。边界是否清楚。安全说明是否充分。资源组织是否合理。输出格式是否可用。测试是否覆盖关键风险。是否和已有 Skill 重复。是否有 owner 和维护计划。如果是高风险 Skill还需要安全或平台团队 review。高风险包括生产环境操作。外部 API 写操作。用户数据处理。权限和认证。代码执行。数据库变更。26. 准入标准什么样的 Skill 可以进入团队仓库团队可以定义准入标准。例如准入项要求目标解决一个明确重复任务owner有明确负责人和备份负责人description包含能力、触发场景、产物和排除条件文档结构SKILL.md清晰资源按需拆分测试至少 5 条测试 prompt安全无密钥无隐藏危险命令脚本有--help、退出码、错误信息变更记录有初始 changelog评审至少一名相关领域 reviewer 通过准入标准不要过度复杂。但要守住底线。27. 发布规则从试用到正式Skill 发布可以分三个阶段。27.1 draft草稿阶段目标是快速验证思路。要求可以不完整。可以只给少量人试用。不作为团队推荐。必须标注草稿状态。27.2 pilot试用阶段目标是验证真实场景。要求有基础测试 prompt。有 owner。有使用反馈渠道。有明确试用范围。收集失败案例。27.3 active正式阶段目标是团队推广。要求通过 review。有 changelog。有安装说明。有测试样本。有安全说明。有维护计划。发布规则可以写进团队贡献指南。28. 反馈机制让使用失败变成迭代输入Skill 使用失败很正常。关键是不要让失败散落在聊天记录里。团队应该收集用户 prompt。期望行为。实际行为。是否触发 Skill。使用的 Skill 版本。失败类型。修复建议。可以使用模板## Skill Feedback - Skill: - Version: - User Prompt: - Expected: - Actual: - Failure Type: - Triggered: - Related Files: - Suggested Fix:这和第十二篇的 Failure Record 一脉相承。团队治理要把失败变成资产。29. 兼容性不要随意破坏输出契约有些 Skill 的输出会被下游使用。例如生成固定 JSON。生成提交说明。生成发布说明。生成测试报告。生成表格或文件。如果随意改输出格式会影响用户流程。所以正式 Skill 应该声明输出契约。例如## Output Contract The final report must contain these sections: 1. 变更主题 2. 变更内容 3. 验证情况 Changing these labels is a breaking change.一旦写清输出契约团队就知道哪些修改属于 major 变更。30. 与现有流程集成Skill 不应该孤立存在。它可以接入团队已有流程。例如PR 模板要求说明是否修改 Skill。CI 检查 Skill 是否包含SKILL.md。脚本检查 frontmatter 是否有name和description。安全扫描检查是否出现密钥模式。文档站展示 active Skill 列表。发布机器人生成 changelog。定期任务提醒 owner 复审。这些集成不一定一开始全做。可以从最简单的检查开始。例如findskills-maxdepth2-nameSKILL.md再逐步增加 frontmatter、测试 prompt、安全扫描等检查。31. 团队贡献流程可以定义一个轻量贡献流程。示例提出需求 - 创建草稿 - 补测试 prompt - 小范围试用 - 提交 PR - Review - 发布 pilot - 收集反馈 - 发布 active展开如下提出需求说明要沉淀什么重复流程。创建草稿使用模板创建SKILL.md。补测试 prompt至少覆盖成功、模糊、负向场景。小范围试用让 1 到 3 个真实使用者试用。提交 PR包含变更记录和测试结果。Review领域 owner、安全 reviewer、使用方 review。发布 pilot团队内小范围可安装。收集反馈记录失败和改进。发布 active纳入推荐 Skill 列表。这个流程不复杂但足够闭环。32. 团队 Skill 提案模板每个新 Skill 可以先写提案。# Skill Proposal ## 基本信息 - Skill 名称 - 负责人 - 备份负责人 - 目标状态draft / pilot / active ## 要解决的问题 - 当前重复任务是什么 - 现在靠什么方式完成 - 哪些经验希望沉淀 ## 触发场景 Should trigger: 1. 2. 3. Should not trigger: 1. 2. 3. ## 输入和输出 - 输入 - 输出 - 输出格式是否会被下游依赖 ## 资源和脚本 - 是否需要 references/ - 是否需要 scripts/ - 是否需要 assets/ - 脚本是否有副作用 ## 安全和合规 - 是否处理敏感数据 - 是否访问外部网络 - 是否执行写操作 - 是否需要用户确认 ## 测试计划 1. 2. 3.提案不需要很长。但它能帮助团队在写代码前先对齐边界。33. Review 清单团队可以使用这张 review 清单。检查项问题目标是否解决明确重复任务owner是否有负责人和备份负责人description是否覆盖触发和排除条件边界是否和已有 Skill 冲突Workflow是否可执行、不过度抽象输出是否有稳定格式或契约references是否按需加载、来源清楚scripts是否有--help、错误处理和安全默认值测试是否有正向、模糊、负向、复合、安全场景安全是否无密钥、无隐藏危险命令、无权限绕过分发是否说明安装和更新方式版本是否有 changelog 和状态标记Review 不是为了挑毛病。它是为了让团队复用时更放心。34. 发布说明模板Skill 发布时可以写发布说明。# Skill Release Note ## 版本 local-api-smoke-test v1.0.0 ## 适用场景 用于对本地 HTTP API 执行轻量冒烟测试。 ## 安装方式 通过团队 Skill 集合 engineering-skills 安装。 ## 使用示例 帮我验证本地 3000 端口 API 的 /health 和 /version。 ## 安全边界 1. 默认只调用只读端点。 2. 不访问生产环境除非用户明确确认。 3. 不执行删除、创建或更新数据的接口。 ## 验证情况 已通过 8 条测试 prompt覆盖常规、模糊、负向和安全边界场景。发布说明帮助使用者快速判断要不要安装。35. 废弃和归档团队常常重视创建不重视废弃。但 Skill 也需要下线机制。应该废弃的情况包括对应系统已经下线。团队流程已经改变。API 版本不再支持。与新 Skill 重复。owner 不再维护。安全风险无法修复。使用频率极低且维护成本高。废弃时不要只删除。建议流程标记deprecated。写清废弃原因。指向替代 Skill。保留迁移说明。给出下线日期。到期后移动到archived/。示例## Deprecation Notice Status: deprecated Reason: The team migrated from Acme API v1 to v2. Replacement: acme-api-platform-v2 Archive Date: 2026-09-01这能减少团队使用旧能力的风险。36. 安全审查清单高风险 Skill 可以单独做安全审查。检查项问题密钥是否包含真实密钥、token、cookie 或私钥凭证是否要求用户把密钥贴进聊天命令是否执行删除、覆盖、提交、推送、远程脚本环境是否默认访问生产环境网络是否上传文件或调用外部服务权限是否绕过审批、鉴权或审计数据是否处理客户数据、生产日志或个人信息日志是否会打印敏感信息脚本是否有 dry-run、确认、超时和清理说明是否明确写出副作用和风险如果任何一项回答不清楚就不应该发布 active。37. Skill 目录推荐结构团队级 Skill 可以采用统一结构。skill-name/ ├── SKILL.md ├── CHANGELOG.md ├── README.md ├── evals/ │ └── evals.json ├── references/ │ └── ... ├── scripts/ │ └── ... └── assets/ └── ...不是每个 Skill 都要有所有目录。但建议正式 Skill 有CHANGELOG.md。有测试的 Skill 放evals/。有脚本的 Skill 放scripts/。长资料放references/。模板文件放assets/。目录统一团队成员更容易阅读和贡献。38. 团队 Skill 仓库推荐结构如果团队维护一个统一仓库可以这样组织team-agent-skills/ ├── README.md ├── CONTRIBUTING.md ├── REVIEW_CHECKLIST.md ├── SECURITY.md ├── marketplace.json ├── skills/ │ ├── active/ │ │ ├── local-api-smoke-test/ │ │ └── release-notes/ │ ├── pilot/ │ │ └── incident-summary/ │ ├── draft/ │ │ └── api-migration-helper/ │ └── archived/ │ └── old-v1-api-guide/ └── templates/ ├── basic-skill/ ├── tool-skill/ └── knowledge-skill/这种结构能把生命周期状态显式化。也可以不分目录而是在每个 Skill 的Status小节标记状态。两种方式都可以。关键是团队能看懂。39. 和代码审查流程结合Skill 变更应该走 review。可以在 PR 模板里加入## Skill Change Checklist - [ ] 是否修改了 description - [ ] 是否修改了 Workflow 或 Output Format - [ ] 是否新增或修改脚本 - [ ] 是否新增或修改参考资料 - [ ] 是否更新测试 prompt - [ ] 是否更新 CHANGELOG - [ ] 是否经过安全检查 - [ ] 是否说明了兼容性影响这样 reviewer 能快速判断风险。如果只是修错别字不需要重跑全部测试。如果改了 description 或脚本就应该认真评审。40. 和自动化检查结合可以逐步加入自动化检查。第一阶段检查结构每个 Skill 是否有SKILL.md。frontmatter 是否有name。frontmatter 是否有description。description是否为空。第二阶段检查安全是否出现疑似 API key。是否出现危险命令。是否包含生产 URL。是否有脚本但没有--help。第三阶段检查质量是否有测试 prompt。是否有 changelog。代码块是否闭合。链接是否可访问。scripts 是否能通过基础语法检查。自动化不是为了替代人。它负责守住基础底线。41. 和文档站结合团队 Skill 多了以后需要一个索引。可以生成一份文档站或 README。内容包括Skill 名称。当前状态。owner。适用场景。安装方式。示例 prompt。安全说明。最近更新时间。例如Skill状态Owner适用场景local-api-smoke-testactiveDevInfra本地 API 冒烟测试release-notesactiveEng Productivity根据提交生成发布说明incident-summarypilotSRE故障复盘摘要old-api-guidedeprecatedPlatform旧 API 查询这个索引能降低团队发现成本。否则 Skill 再好也可能没人知道。42. 团队培训让使用者知道边界发布 Skill 后还需要让团队知道怎么用。培训不需要很复杂。可以是一页说明什么场景该用。什么场景不该用。示例 prompt。输出如何检查。失败怎么反馈。安全注意事项。比如对local-api-smoke-test适合 1. 验证本地服务是否启动。 2. 检查只读健康端点。 3. 生成简短验证报告。 不适合 1. 压测。 2. 安全扫描。 3. 生产写操作。 4. 完整 E2E 测试。Skill 的边界必须让使用者也知道。不能只写给 Agent。43. 什么时候不应该 Skill 化团队治理也包括“拒绝创建不合适的 Skill”。不适合 Skill 化的情况包括任务只做一次。流程还不稳定。没有 owner。没有明确输出。风险很高但没有安全方案。需要大量人工判断且没有稳定标准。已经有现成工具更适合。与现有 Skill 高度重复。不是所有经验都要封装。Skill 化应该服务复用和稳定不是为了堆资产。44. 团队治理中的常见误区44.1 误区一只管创建不管维护Skill 会过期。API、规范、组织流程都会变。没有维护计划Skill 很快会变成旧知识。44.2 误区二把个人提示词直接发布给团队个人提示词可以随意一点。团队 Skill 必须有边界、测试、owner 和安全说明。44.3 误区三过度集中审批治理不等于所有变更都走重流程。低风险小改动可以轻量。高风险能力才需要更严格审批。44.4 误区四忽略负向测试团队 Skill 最怕误触发。负向测试可以发现它是否抢了别的任务。44.5 误区五没有废弃机制旧 Skill 如果一直留在 active 列表会误导用户。44.6 误区六安全说明只写给人看安全说明也要写进 Agent 会读取的流程里。比如“默认 dry-run”“禁止生产写操作”“不要请求用户贴密钥”。45. 一份完整的团队提交流程最后给出一个可落地流程。1. 提交 Skill Proposal 2. 创建 draft Skill 3. 编写最小 SKILL.md 4. 添加测试 prompt 5. 完成安全自查 6. 小范围试用 7. 提交 PR 8. 领域 review 9. 安全 review 10. 发布 pilot 11. 收集反馈和失败案例 12. 达到稳定标准后发布 active 13. 定期复审 14. 废弃或归档这套流程可以根据团队规模缩减。小团队可以合并一些步骤。但不要省略owner。测试。review。安全边界。变更记录。46. 准入标准示例团队可以直接使用下面这份准入标准。# Skill 准入标准 一个 Skill 进入团队 active 列表前必须满足 1. 有明确 owner 和备份 owner。 2. SKILL.md 包含标准 frontmatter。 3. description 写清触发场景和排除条件。 4. Workflow 可执行不只是抽象建议。 5. 输出格式或交付物清楚。 6. 至少有 5 条测试 prompt。 7. 有正向和负向触发样例。 8. 有安全说明。 9. 没有真实密钥、token、cookie 或客户敏感数据。 10. 有脚本时必须支持 --help并说明副作用。 11. 有参考资料时必须说明来源或更新时间。 12. 有 CHANGELOG.md 或等价变更记录。 13. 至少一名领域 reviewer 通过。 14. 高风险 Skill 需要安全 reviewer 通过。这份标准不复杂但足以让团队 Skill 质量明显提升。47. 评审清单示例# Skill Review Checklist ## 目标和边界 - [ ] 目标任务是否明确、重复、值得 Skill 化 - [ ] 是否和已有 Skill 重复 - [ ] 是否写清不适用场景 ## 触发 - [ ] description 是否覆盖真实用户表达 - [ ] 是否包含排除条件 - [ ] 是否有 should-trigger 和 should-not-trigger 样例 ## 结构 - [ ] SKILL.md 是否清晰 - [ ] 长资料是否拆到 references/ - [ ] 确定性任务是否适合放到 scripts/ - [ ] 资源路由是否明确 ## 质量 - [ ] 是否有测试 prompt - [ ] 是否有输出格式或验收标准 - [ ] 是否有失败处理策略 - [ ] 是否更新 changelog ## 安全 - [ ] 是否包含敏感信息 - [ ] 是否有危险命令 - [ ] 是否默认访问生产环境 - [ ] 是否会上传文件或调用外部服务 - [ ] 是否需要用户确认这张清单可以放在团队仓库的REVIEW_CHECKLIST.md。48. 发布规则示例# Skill 发布规则 ## draft - 允许快速迭代。 - 不进入团队推荐列表。 - 必须标注 owner。 ## pilot - 至少 5 条测试 prompt。 - 至少 1 名 reviewer 通过。 - 明确试用范围和反馈渠道。 - 试用期至少收集 3 个真实使用案例。 ## active - owner 和备份 owner 明确。 - 测试 prompt 覆盖正向、负向和安全场景。 - 高风险能力完成安全 review。 - README 或索引中提供安装和使用说明。 - 有 changelog。 ## deprecated - 写明废弃原因。 - 提供替代 Skill。 - 标注归档日期。这套规则可以作为团队 Skill 发布的起点。49. 系列回顾到这里整个系列已经从个人实践走到团队落地。我们一路讲了Skill 是什么。它如何把隐性经验变成显性流程。最小结构如何设计。description 如何触发。如何控制上下文成本。如何组织脚本、参考资料和资产。如何让脚本与 Agent 协作。如何设计参考资料。如何从模板写第一个 Skill。如何优化 description。如何设计测试 prompt。如何小步迭代。文档处理类 Skill 如何设计。开发工具类 Skill 如何设计。知识库型 Skill 如何设计。团队如何管理、分发、安全治理。这些内容串起来其实是一条完整路径经验 - 流程 - Skill - 测试 - 迭代 - 案例 - 团队资产这也是本系列标题里“把经验封装成能力”的含义。50. 小结这一篇讲的是 Skill 的团队落地。可以记住三句话Skill 一旦进入团队就应该被当作工程资产管理需要 owner、版本、测试、评审、发布和废弃机制。团队分发可以从仓库、项目目录、模板开始成熟后再进入插件集合或内部市场。安全治理必须覆盖密钥、危险命令、权限绕过、敏感数据、外部网络和生产环境副作用。如果前十五篇解决的是“如何把经验封装成能力”第十六篇解决的就是“如何让这些能力在团队里长期可信地运行”。51. 实践任务请制定一份团队 Skill 提交流程包括准入标准、评审清单和发布规则。你可以直接从下面这个结构开始team-agent-skills/ ├── README.md ├── CONTRIBUTING.md ├── REVIEW_CHECKLIST.md ├── SECURITY.md ├── skills/ │ ├── active/ │ ├── pilot/ │ ├── draft/ │ └── archived/ └── templates/ ├── basic-skill/ ├── tool-skill/ └── knowledge-skill/51.1CONTRIBUTING.md应包含1. 如何提交 Skill Proposal。 2. 如何从模板创建 Skill。 3. 必须填写哪些 owner 和状态信息。 4. 必须准备哪些测试 prompt。 5. 哪些变更需要安全 review。 6. 如何写 CHANGELOG。 7. 如何从 draft 晋级到 pilot。 8. 如何从 pilot 晋级到 active。 9. 如何废弃和归档 Skill。51.2REVIEW_CHECKLIST.md应包含1. 目标是否明确。 2. description 是否覆盖触发和排除条件。 3. Workflow 是否可执行。 4. 资源组织是否合理。 5. 脚本是否安全。 6. 测试 prompt 是否覆盖正向、负向和安全场景。 7. 是否有 owner、版本和 changelog。 8. 是否存在敏感信息、危险命令或权限绕过。51.3SECURITY.md应包含1. 不允许提交真实密钥、token、cookie 或私钥。 2. 不允许隐藏危险命令。 3. 不允许绕过权限、审批或审计。 4. 默认不访问生产环境。 5. 默认不执行破坏性操作。 6. 处理敏感数据时必须脱敏。 7. 脚本必须说明网络行为和副作用。 8. 高风险 Skill 必须经过安全 review。完成这个练习后你就不只是会写一个 Skill而是能设计一套让团队持续生产、评审、分发和治理 Skill 的机制。