把公司知识库做成 Skill 合集：42 人研发团队的 11 个月实战

先抛个反差数字。

我们公司 Confluence 里有 2,341 个页面。过去一年被点开过的只有 318 个（13.6%），被点开过 3 次以上的只有 91 个（3.9%）。剩下 96% 的内容写了就烂在那。

同一时期，我们做的 Skill 合集，67 个 Skill，过去 30 天被触发 13,408 次。平均每个 Skill 每月被用 6.2 次。

差距不止一个数量级。

为什么 wiki 没人看但 Skill 有人用

一句话：拉取 vs 嵌入。

wiki 是拉取模式。你写了文档放那，指望别人遇到问题时主动来翻。但实际上人遇到问题的第一反应不是去翻文档，是直接上手干——干着干着发现不对劲，还是懒得翻，就瞎猜一下或者问同事。wiki 的「有用时机」和「被访问时机」几乎永远对不上。

Skill 是嵌入模式。它不等着被翻，agent 在干活的过程中自动把相关的知识拉进 context。用户根本不需要知道这个 Skill 存在，就能受益。

这个差别决定了使用频次。即便内容质量不变，传递方式换一下，频次可以差 20 倍。

11 个月沉淀的 67 个 Skill 分类

我们团队 42 人，分布在后端、前端、SRE、数据、QA 五个方向。Skill 按用途分五类：

入职类（9 个）：「我们的 git 工作流」「本地环境怎么搭」「常用仓库清单及职责」「找谁问什么」等。
编码规范类（18 个）：「Python 命名和结构」「TypeScript 错误处理模式」「SQL 写法约束」「API 版本策略」等。
事故 runbook 类（14 个）：「支付网关超时排查」「Kafka 堆积处理」「数据库慢查询定位」等。典型的应急知识。
领域知识类（21 个）：「订单状态机」「用户权限模型」「结算流程」「风控规则」等。业务逻辑。
合规与安全类（5 个）：「PII 处理要求」「GDPR checklist」「密钥管理规范」等。

为什么是这五类？因为这覆盖了「新人需要、老人忘了、跨组不知道」三个痛点。

最早我们还写过「八卦类」——谁擅长什么、某个项目的历史背景。后来都删了，因为内容变化太快、又涉及人。这类东西还是放 wiki 或者直接问。

谁维护：owner 机制和季度 review

没人维护的 Skill 就像没人洗的碗，过几个月全烂了。

我们的做法：每个 Skill 有且只有一个 owner。分类划给 tech lead 级别的人，他们再分配到组员。入职类 owner 是 EM，编码规范是各方向资深工程师，runbook 是 SRE 团队，领域是对应业务组的 staff 工程师，合规是安全团队。

owner 的职责很具体：

• 新增 Skill 前先发到团队群讨论，避免重复。
• 每季度一次 review，每次 45 分钟。
• 看 Skill 的调用次数、用户反馈、报错率。

季度 review 会议的 agenda 是固定的：

1. 本季度新增的 Skill，简单介绍（各 2 分钟）。
2. 调用次数排行前 10，分析为什么高。
3. 调用次数倒数 10，讨论要不要砍。
4. 用户负反馈 > 20% 的 Skill，必须修或砍。

这个机制跑了三个季度，效果不错。前两个季度砍掉了 8 个 Skill，其中 3 个是「当时以为有用但实际没人用」，5 个是「过时了的规范」。

检索：用 MCP server 做 Skill 目录

67 个 Skill 之后，管理本身成了问题。用户偶尔会问「我有这个需求，有 Skill 能帮我吗」——但他们不知道有啥 Skill。

我们做了个 MCP server 叫 skill-catalog，暴露三个 tool：

• search_skills(query)：按关键词搜 Skill。
• list_skills_by_category(category)：列某类下所有 Skill。
• get_skill_details(name)：看某个 Skill 的完整信息（包括最近 30 天调用次数、满意度）。

这个 MCP 部署一份，全公司连。Claude Code 遇到不确定「有没有相关 Skill」时自动查。

具体做法跟 MCP server 搭建 那篇的思路一样，index 数据后端用 SQLite，全量 67 条记录，查询毫秒级。

副作用是：这个目录本身成了一个使用指南。新人入职时 onboarding 文档写「你可以通过 skill-catalog 问 ‘XX 相关的 Skill 有哪些’」，比列一个 67 项清单友好得多。

度量用什么数字

这部分我花了挺多时间想清楚，列一下我们盯的指标。

调用次数：每个 Skill 每月被触发多少次。低于 2 次/月的 Skill 进观察名单。不是说少就一定删，但要解释。

用户满意度：Claude Code 结束 session 时有个简单评分（我们自己加的 hook），关联到本次用到的 Skill。某 Skill 的满意度连续两个季度低于 3.5/5，必须 owner 出面优化。

触发准确率：用 Skill frontmatter 那篇 讲过的 llm-as-judge 方法，每月跑一次。低于 85% 的 Skill 需要 owner 调 description。

降本数字：我们选了一个很直接的业务指标——客服新人从入职到独立接单的平均天数。

这是最戏剧化的一个：在没有 Skill 之前，客服新人平均需要 14.2 天（跟师傅一周、自己磕绊一周）。把客服相关的知识做成 18 个 Skill（我们内部把客服算”半个研发”，所以也上 Claude Code）之后，降到 3.4 天。

这个数字我是有数据支持的——去年 H2 总共上了 23 个客服新人，实测分布从 2-6 天不等，中位数 3 天。不是均匀分布，但足以说明问题。

省下来的时间折算成人力成本，一年大概 80 多万人民币。而我们做这套 Skill 合集的总投入，大约是 2 个人各 20% 时间干了 11 个月——远低于这个数。

低质量 Skill 怎么淘汰

不是所有 Skill 都能活下来。一个 Skill 被砍的典型信号：

信号一：调用次数极低且没有显著上升趋势。比如某个月只被调了 1 次、连续三个月都这样，大概率这个 Skill 要么定位不准，要么根本没需求。

信号二：负面反馈集中。用户多次反馈「这个 Skill 给我的建议是错的」。这比低调用次数还危险——有人用但用得不爽，说明它误导人。

信号三：内容严重过期。比如「事故 runbook」里提到的服务已经下线了，但 Skill 没更新。过时的 runbook 比没 runbook 还糟。

信号四：跟别的 Skill 高度重复。季度 review 时 owner 之间对话，经常发现「我这 Skill 跟你那个有 60% 重合」。这种合并或者其中一个砍掉。

砍 Skill 不是删文件那么简单。我们走 deprecate 流程：

1. 标 deprecated，description 前面加 [DEPRECATED]，写明替代方案。
2. 过一个月，下游没反馈，挪到 archive 目录。
3. 再过一个月，从 Skill 目录里移除。

前前后后砍过 14 个 Skill，从 67 的总数里减（我们也新增了 25 个）。健康的 Skill 合集应该是一直在动态调整的，不是只增不减。

新人入职用 Skill 合集是什么体验

给个具体例子。上个月一个叫李（化名）的后端工程师入职。

第一天，给他装好 Claude Code 和公司 skill repo 的连接。
第二天下午他开始改第一个 bug。原来需要 EM 或者 buddy 陪坐半天解释环境、讲 CI 流程、教他怎么提 PR——现在大部分通过 Claude Code 自然承接了。他需要什么，agent 自动拉起相关 Skill 喂进 context。

第四天他独立开了一个 PR，被审阅者评价「格式和提交规范都对得上我们的风格」。这要是放一年前，没两周基本做不到。

李本人后来跟我反馈：「我没感觉在用什么知识库，就是 Claude Code 偶尔在回答里带一点明显是公司内部的细节，我就知道它在调 Skill 了。」

无感，但有效。这是 Skill 合集最理想的状态。

治理的几条硬规则

最后列几条我们踩过坑总结出来的硬规则：

1. Skill 写作遵循公司统一模板。frontmatter 格式、正文结构、示例格式都一致，避免风格漂移。
2. 敏感信息不进 Skill。密钥、私密业务指标、未公开的路线图，一律不放。Skill 会被 agent 随时加载，泄漏风险高。
3. Skill 不覆盖别的 Skill 职责。owner 之间要对齐，季度 review 时必查重叠。
4. 业务变更必须同步更新 Skill。这条写进我们的 definition of done：涉及文档的需求，Skill 相关部分也要更。没更的不给 merge。
5. 保留历史版本但不推荐用。Skill 变更走 git log，想回看历史版本是可以的，但线上只用 latest。

小结

把知识做成 Skill 合集，本质上是把「文档」从被动变主动。它不解决所有知识管理问题，但能解决最大的那个——让正确的知识在正确的时间出现在正确的位置。

这事儿不是一个人能搞定的，需要组织层面的承诺：owner 机制、季度 review、度量指标、治理规则。搭起来不容易，但一旦转起来，回报非常可观。

如果你们团队也在挣扎于「文档没人看」这件事，可以考虑走这条路。从最痛的一类知识（一般是事故 runbook 或新人入职）开始做起，两三个月就能看到明显效果。