系列：《把经验封装成能力：Agent Skills 设计与落地》

本文是系列第十六篇，也是正文部分的收束篇。前十五篇已经讲完 Skill 的概念、结构、触发、资源组织、脚本协作、测试评估、迭代方法，以及文档处理、开发工具、知识库三类真实案例。最后一篇我们把视角从“如何写一个 Skill”切到“团队如何长期使用 Skill”：版本怎么管，怎么分发，谁来审核，如何避免安全和合规风险，什么时候推广，什么时候废弃。

1. 为什么最后要讲团队治理

一个人写 Skill，问题通常是：

1. 这个 Skill 能不能触发？
2. 输出是否符合预期？
3. 脚本是否能运行？
4. 参考资料是否组织清楚？

团队使用 Skill，问题会变成：

1. 谁能新增 Skill？
2. 谁负责维护 Skill？
3. Skill 出问题后谁修？
4. 旧版本还能不能继续用？
5. 团队成员怎么安装和更新？
6. 是否经过测试和评审？
7. 是否会泄露敏感信息？
8. 是否包含危险命令？
9. 是否会误导 Agent 绕过权限？
10. 什么时候应该下线或归档？

这已经不是单纯写作问题，而是工程治理问题。

Skill 一旦进入团队，就不再只是个人提示词资产。

它会影响团队的工作方式、交付质量和安全边界。

所以系列最后必须讨论治理。

2. Skill 是团队资产，不是临时片段

如果只是临时提示词，写完用一次就结束。

但 Skill 的目标是复用。

复用意味着它会被不同人、不同 Agent、不同项目、不同时间反复使用。

这就要求它像其他工程资产一样被管理。

例如：

Skill 也需要类似管理。

否则它会变成一种新的隐性风险：

1. 看起来很方便，但没人知道是否可靠。
2. 看起来是团队规范，但没人维护。
3. 看起来能自动化，但内部藏了危险命令。
4. 看起来是最新知识，但其实资料已经过期。

治理不是为了增加流程负担，而是为了让可复用能力真正可信。

3. 团队 Skill 的五个治理对象

团队落地时，可以从五个对象入手。

这五个对象构成了团队 Skill 的基本治理框架。

接下来逐个展开。

4. Owner：每个 Skill 都应该有负责人

团队 Skill 必须有 owner。

owner 不是“唯一能修改的人”，而是“对质量和边界负责的人”。

owner 至少负责：

1. 判断这个 Skill 是否应该存在。
2. 维护 description 和主流程。
3. 审核资源和脚本变更。
4. 定期检查资料是否过期。
5. 处理使用反馈和失败案例。
6. 决定是否推广、冻结或废弃。

没有 owner 的 Skill 很容易变成无人维护的知识包。

尤其是知识库型 Skill 和工具型 Skill，过期风险更高。

例如：

1. API 文档更新了，但 Skill 没更新。
2. 团队规范改了，但 Skill 还按旧流程输出。
3. 脚本依赖升级了，但 Skill 里的命令不可用。
4. 原 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 字段支持可能不同。

更稳妥的做法是：

1. name和description保持标准。
2. 治理信息写在正文固定小节。
3. 如果团队有额外工具，可以再从正文或旁路 metadata 文件读取。

6. Status：Skill 应该有生命周期状态

团队 Skill 不应该只有“存在”和“不存在”两种状态。

建议至少有五种状态。

状态能帮助使用者判断风险。

例如一个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 行为。

比如：

1. 改 description，可能改变触发范围。
2. 改 Workflow，可能改变执行步骤。
3. 改 Output Format，可能影响下游脚本。
4. 改 references，可能改变知识依据。
5. 改 scripts，可能改变执行结果或副作用。

这些都应该记录。

简单做法是在 Skill 目录下维护：

CHANGELOG.md

或者在SKILL.md末尾维护简短变更记录。

推荐独立文件。

因为 Skill 主文件应该尽量服务运行时，不要承载过多历史信息。

8. 版本号怎么定

团队内部可以用语义化版本，但不必过度复杂。

建议：

例如：

1.2.3

含义：

1. 1：主版本。
2. 2：能力新增或兼容扩展。
3. 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，未发现旧的健康检查场景回归。

这样的记录能回答：

1. 改了什么？
2. 为什么改？
3. 影响范围是什么？
4. 怎么验证？

这也是团队评审需要的信息。

10. 哪些变更需要重点评审

不是每个标点都需要重审。

但以下变更应该重点评审。

团队可以约定：

1. 文案小修一人 review。
2. description、脚本、安全相关变更至少两人 review。
3. 涉及生产系统、权限、密钥、外部 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

优点：

1. 和代码一样走 PR。
2. 方便审查变更。
3. 可以跑测试。
4. 可以记录版本。
5. 可以和团队文档放一起。

缺点：

1. 安装和更新需要额外说明。
2. 多团队共享时可能需要权限管理。
3. 不同项目可能需要不同 Skill 子集。

仓库分发适合早期和内部团队。

12. 分发方式二：插件市场或集合分发

当前仓库里有.claude-plugin/marketplace.json。

它把 Skill 分成几个集合。

例如：

1. document-skills：包含xlsx、docx、pptx、pdf。
2. example-skills：包含mcp-builder、webapp-testing、skill-creator等示例。
3. claude-api：单独作为 API/SDK 文档型 Skill。

这种方式有几个好处：

1. 用户可以按集合安装。
2. 不同能力可以分层发布。
3. 文档处理、开发工具、知识库可以拆成不同包。
4. 对外或跨团队分发更清晰。

团队内部也可以类似设计：

{"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 只适合某个项目。

比如：

1. 某个服务的排障流程。
2. 某个业务线的 API 集成规范。
3. 某个仓库的发布流程。
4. 某个系统的值班复盘模板。

这些 Skill 可以放在项目内。

例如：

payment-service/ ├── src/ ├── tests/ ├── docs/ └── .agent-skills/ ├── payment-debugging/ ├── release-checklist/ └── incident-summary/

优点：

1. 和项目代码一起演进。
2. 更贴近项目上下文。
3. 修改流程可以和业务变更一起 review。

缺点：

1. 跨项目复用较弱。
2. 容易形成多个相似 Skill。
3. 需要定期抽象和合并。

项目内 Skill 适合项目特有流程。

通用 Skill 则更适合放团队级仓库。

14. 分发方式四：内部模板

有些 Skill 不一定直接分发成可用能力，而是作为模板。

例如：

templates/ ├── api-knowledge-skill/ ├── local-testing-skill/ ├── document-processing-skill/ └── writing-style-skill/

团队成员创建新 Skill 时，从模板复制并填写：

1. owner。
2. description。
3. workflow。
4. resource routing。
5. test prompts。
6. safety notes。
7. changelog。

模板的价值是统一质量底线。

它不能替代评审，但能减少遗漏。

15. 推荐的分发策略

可以按成熟度选择分发方式。

不要一开始就追求复杂分发。

先小范围验证，再扩大。

这和第十二篇讲的小步迭代是一致的。

16. 安全边界一：不要写入敏感密钥

Skill 中不应该包含：

1. API key。
2. OAuth token。
3. Cookie。
4. 私钥。
5. 数据库密码。
6. 生产环境临时凭证。
7. 内部用户隐私数据样本。

哪怕是示例，也不要放真实值。

示例应该写成：

ACME_API_TOKEN=your-token-here

或者：

export ACME_API_TOKEN="<redacted>"

更好的做法是告诉 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 可能包含脚本。

脚本是高价值能力，也可能带来风险。

危险命令包括：

1. 删除文件。
2. 清空数据库。
3. 修改生产配置。
4. 执行远程脚本。
5. 提交或推送代码。
6. 关闭服务。
7. 绕过权限检查。

团队 Skill 中不能把危险操作藏在脚本里。

如果确实需要支持高风险操作，必须：

1. 明确写在 description 或安全说明里。
2. 默认只读或 dry-run。
3. 要求用户显式确认。
4. 输出将执行的命令。
5. 记录执行结果。
6. 支持回滚或恢复方案。

例如：

## 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。

正确做法是：

1. 使用正式权限路径。
2. 如果权限不足，提示用户申请权限。
3. 不尝试规避审计。
4. 不生成规避访问控制的脚本。

Skill 是能力包，不是权限提升工具。

团队治理必须明确这一点。

19. 安全边界四：敏感数据最小化

很多 Skill 会处理文档、日志、代码、用户数据。

团队需要定义数据边界。

例如：

Skill 中的示例、测试 prompt、fixtures 都要检查敏感信息。

这是很多团队容易忽略的地方。

测试 prompt 也可能泄密。

20. 安全边界五：外部依赖和网络访问

如果 Skill 的脚本会访问外部网络，需要写清楚：

1. 访问哪些域名。
2. 是否会上传文件。
3. 是否会发送用户数据。
4. 是否需要认证。
5. 是否有日志记录。
6. 是否会改变外部系统状态。

例如：

## 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 是触发入口。

团队评审时必须看它。

审查重点：

1. 是否覆盖真实触发表达？
2. 是否写清能力边界？
3. 是否过宽，会误触发？
4. 是否过窄，会欠触发？
5. 是否包含排除条件？
6. 是否和其他 Skill 冲突？
7. 是否会抢占不属于它的任务？

可以要求每个新 Skill 提交时附带：

## Trigger Examples Should trigger: 1. ... 2. ... 3. ... Should not trigger: 1. ... 2. ... 3. ...

没有正负触发样例的 description，很难审。

22. 质量门禁二：测试 prompt

第十一篇讲过测试 prompt。

团队级 Skill 至少要有一组基础测试。

建议包含：

1. 典型成功场景。
2. 模糊表达场景。
3. 输入不足场景。
4. 相邻任务负向场景。
5. 复合任务场景。
6. 安全边界场景。

例如本地 API 冒烟测试 Skill，可以有：

1. “帮我检查本地/health。”
2. “服务在 3000 端口，做个冒烟测试。”
3. “帮我压测这个接口。”
4. “调用生产接口删除测试用户。”
5. “先看健康检查，再总结失败原因。”

测试 prompt 不需要一开始很多。

但每个正式 Skill 至少应该有能覆盖核心风险的样本。

23. 质量门禁三：脚本校验

有脚本的 Skill 必须审脚本。

审查重点：

1. 是否有--help。
2. 参数是否显式。
3. 默认是否安全。
4. 是否有 dry-run。
5. 是否有清晰退出码。
6. 错误信息是否可行动。
7. 是否会修改文件或外部系统。
8. 是否会记录敏感信息。
9. 是否有超时和资源清理。
10. 是否避免不必要的全量扫描。

脚本不应该因为藏在 Skill 里就绕过代码审查。

脚本就是代码。

应该按代码标准评审。

24. 质量门禁四：参考资料审查

references 也需要审查。

尤其是知识库型 Skill。

审查重点：

1. 是否有来源。
2. 是否有更新时间。
3. 是否包含过期信息。
4. 是否和团队当前规范一致。
5. 是否包含敏感内容。
6. 是否指向已失效链接。
7. 是否有版本边界。
8. 是否和其他参考资料冲突。

如果资料变化快，应该要求：

1. 标注缓存日期。
2. 提供 live source。
3. 定期复审。

25. 质量门禁五：人工 review

自动测试很重要，但不能替代人工 review。

Skill review 至少应该看：

1. 目标是否清楚。
2. 边界是否清楚。
3. 安全说明是否充分。
4. 资源组织是否合理。
5. 输出格式是否可用。
6. 测试是否覆盖关键风险。
7. 是否和已有 Skill 重复。
8. 是否有 owner 和维护计划。

如果是高风险 Skill，还需要安全或平台团队 review。

高风险包括：

1. 生产环境操作。
2. 外部 API 写操作。
3. 用户数据处理。
4. 权限和认证。
5. 代码执行。
6. 数据库变更。

26. 准入标准：什么样的 Skill 可以进入团队仓库

团队可以定义准入标准。

例如：

准入标准不要过度复杂。

但要守住底线。

27. 发布规则：从试用到正式

Skill 发布可以分三个阶段。

27.1 draft

草稿阶段目标是快速验证思路。

要求：

1. 可以不完整。
2. 可以只给少量人试用。
3. 不作为团队推荐。
4. 必须标注草稿状态。

27.2 pilot

试用阶段目标是验证真实场景。

要求：

1. 有基础测试 prompt。
2. 有 owner。
3. 有使用反馈渠道。
4. 有明确试用范围。
5. 收集失败案例。

27.3 active

正式阶段目标是团队推广。

要求：

1. 通过 review。
2. 有 changelog。
3. 有安装说明。
4. 有测试样本。
5. 有安全说明。
6. 有维护计划。

发布规则可以写进团队贡献指南。

28. 反馈机制：让使用失败变成迭代输入

Skill 使用失败很正常。

关键是不要让失败散落在聊天记录里。

团队应该收集：

1. 用户 prompt。
2. 期望行为。
3. 实际行为。
4. 是否触发 Skill。
5. 使用的 Skill 版本。
6. 失败类型。
7. 修复建议。

可以使用模板：

## Skill Feedback - Skill: - Version: - User Prompt: - Expected: - Actual: - Failure Type: - Triggered: - Related Files: - Suggested Fix:

这和第十二篇的 Failure Record 一脉相承。

团队治理要把失败变成资产。

29. 兼容性：不要随意破坏输出契约

有些 Skill 的输出会被下游使用。

例如：

1. 生成固定 JSON。
2. 生成提交说明。
3. 生成发布说明。
4. 生成测试报告。
5. 生成表格或文件。

如果随意改输出格式，会影响用户流程。

所以正式 Skill 应该声明输出契约。

例如：

## Output Contract The final report must contain these sections: 1. `变更主题` 2. `变更内容` 3. `验证情况` Changing these labels is a breaking change.

一旦写清输出契约，团队就知道哪些修改属于 major 变更。

30. 与现有流程集成

Skill 不应该孤立存在。

它可以接入团队已有流程。

例如：

1. PR 模板要求说明是否修改 Skill。
2. CI 检查 Skill 是否包含SKILL.md。
3. 脚本检查 frontmatter 是否有name和description。
4. 安全扫描检查是否出现密钥模式。
5. 文档站展示 active Skill 列表。
6. 发布机器人生成 changelog。
7. 定期任务提醒 owner 复审。

这些集成不一定一开始全做。

可以从最简单的检查开始。

例如：

findskills-maxdepth2-nameSKILL.md

再逐步增加 frontmatter、测试 prompt、安全扫描等检查。

31. 团队贡献流程

可以定义一个轻量贡献流程。

示例：

提出需求 -> 创建草稿 -> 补测试 prompt -> 小范围试用 -> 提交 PR -> Review -> 发布 pilot -> 收集反馈 -> 发布 active

展开如下：

1. 提出需求：说明要沉淀什么重复流程。
2. 创建草稿：使用模板创建SKILL.md。
3. 补测试 prompt：至少覆盖成功、模糊、负向场景。
4. 小范围试用：让 1 到 3 个真实使用者试用。
5. 提交 PR：包含变更记录和测试结果。
6. Review：领域 owner、安全 reviewer、使用方 review。
7. 发布 pilot：团队内小范围可安装。
8. 收集反馈：记录失败和改进。
9. 发布 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 清单。

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 也需要下线机制。

应该废弃的情况包括：

1. 对应系统已经下线。
2. 团队流程已经改变。
3. API 版本不再支持。
4. 与新 Skill 重复。
5. owner 不再维护。
6. 安全风险无法修复。
7. 使用频率极低且维护成本高。

废弃时不要只删除。

建议流程：

1. 标记deprecated。
2. 写清废弃原因。
3. 指向替代 Skill。
4. 保留迁移说明。
5. 给出下线日期。
6. 到期后移动到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 可以单独做安全审查。

如果任何一项回答不清楚，就不应该发布 active。

37. Skill 目录推荐结构

团队级 Skill 可以采用统一结构。

skill-name/ ├── SKILL.md ├── CHANGELOG.md ├── README.md ├── evals/ │ └── evals.json ├── references/ │ └── ... ├── scripts/ │ └── ... └── assets/ └── ...

不是每个 Skill 都要有所有目录。

但建议：

1. 正式 Skill 有CHANGELOG.md。
2. 有测试的 Skill 放evals/。
3. 有脚本的 Skill 放scripts/。
4. 长资料放references/。
5. 模板文件放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. 和自动化检查结合

可以逐步加入自动化检查。

第一阶段检查结构：

1. 每个 Skill 是否有SKILL.md。
2. frontmatter 是否有name。
3. frontmatter 是否有description。
4. description是否为空。

第二阶段检查安全：

1. 是否出现疑似 API key。
2. 是否出现危险命令。
3. 是否包含生产 URL。
4. 是否有脚本但没有--help。

第三阶段检查质量：

1. 是否有测试 prompt。
2. 是否有 changelog。
3. 代码块是否闭合。
4. 链接是否可访问。
5. scripts 是否能通过基础语法检查。

自动化不是为了替代人。

它负责守住基础底线。

41. 和文档站结合

团队 Skill 多了以后，需要一个索引。

可以生成一份文档站或 README。

内容包括：

1. Skill 名称。
2. 当前状态。
3. owner。
4. 适用场景。
5. 安装方式。
6. 示例 prompt。
7. 安全说明。
8. 最近更新时间。

例如：

这个索引能降低团队发现成本。

否则 Skill 再好，也可能没人知道。

42. 团队培训：让使用者知道边界

发布 Skill 后，还需要让团队知道怎么用。

培训不需要很复杂。

可以是一页说明：

1. 什么场景该用。
2. 什么场景不该用。
3. 示例 prompt。
4. 输出如何检查。
5. 失败怎么反馈。
6. 安全注意事项。

比如对local-api-smoke-test：

适合： 1. 验证本地服务是否启动。 2. 检查只读健康端点。 3. 生成简短验证报告。 不适合： 1. 压测。 2. 安全扫描。 3. 生产写操作。 4. 完整 E2E 测试。

Skill 的边界必须让使用者也知道。

不能只写给 Agent。

43. 什么时候不应该 Skill 化

团队治理也包括“拒绝创建不合适的 Skill”。

不适合 Skill 化的情况包括：

1. 任务只做一次。
2. 流程还不稳定。
3. 没有 owner。
4. 没有明确输出。
5. 风险很高但没有安全方案。
6. 需要大量人工判断且没有稳定标准。
7. 已经有现成工具更适合。
8. 与现有 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. 废弃或归档

这套流程可以根据团队规模缩减。

小团队可以合并一些步骤。

但不要省略：

1. owner。
2. 测试。
3. review。
4. 安全边界。
5. 变更记录。

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. 系列回顾

到这里，整个系列已经从个人实践走到团队落地。

我们一路讲了：

1. Skill 是什么。
2. 它如何把隐性经验变成显性流程。
3. 最小结构如何设计。
4. description 如何触发。
5. 如何控制上下文成本。
6. 如何组织脚本、参考资料和资产。
7. 如何让脚本与 Agent 协作。
8. 如何设计参考资料。
9. 如何从模板写第一个 Skill。
10. 如何优化 description。
11. 如何设计测试 prompt。
12. 如何小步迭代。
13. 文档处理类 Skill 如何设计。
14. 开发工具类 Skill 如何设计。
15. 知识库型 Skill 如何设计。
16. 团队如何管理、分发、安全治理。

这些内容串起来，其实是一条完整路径：

经验 -> 流程 -> Skill -> 测试 -> 迭代 -> 案例 -> 团队资产

这也是本系列标题里“把经验封装成能力”的含义。

50. 小结

这一篇讲的是 Skill 的团队落地。

可以记住三句话：

1. Skill 一旦进入团队，就应该被当作工程资产管理，需要 owner、版本、测试、评审、发布和废弃机制。
2. 团队分发可以从仓库、项目目录、模板开始，成熟后再进入插件集合或内部市场。
3. 安全治理必须覆盖密钥、危险命令、权限绕过、敏感数据、外部网络和生产环境副作用。

如果前十五篇解决的是“如何把经验封装成能力”，第十六篇解决的就是“如何让这些能力在团队里长期可信地运行”。

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 的机制。