给项目做一层可演进的 AI Skills 系统
最近我在一个持续迭代的项目里，慢慢遇到了一个很具体的问题：
AI 越来越懂这个项目，但这些理解大多停留在一次次对话里，不稳定，也不容易复用。
项目小的时候，这个问题并不明显。很多背景我自己记得住，AI 也能靠最近几轮对话接上。
但随着功能越来越多，这个问题开始反复出现：
- 同一块模块背景，要一遍遍重新解释
- 某些关键文件、关键入口、关键边界，这次知道，下次不一定优先想到
- 已经沉淀下来的经验散落在脑子里、对话里、零碎文档里，没有统一入口
也就是说，我真正遇到的问题不是"AI 不会写代码"，而是：
项目知识没有一个适合 AI 协作的组织方式。
我遇到的问题
我最先想到的办法其实很自然：
- 既然有些知识会重复讲
- 那就把它们写成 Skill
- 以后触发 Skill，不就能直接复用了吗
但这个方向很快暴露出几个问题：
- 项目知识变化快，全局 Skill 很容易过时
- 不是每一份项目经验都值得升级成真正的全局 Skill
- 模块一多，就很容易出现"全局 Skill 越建越多"的情况
- 一旦全局层变重，维护成本和触发噪音都会变高
所以我很快否掉了"把项目知识直接大量做成全局 Skill"这条路。
我怎么想到这套方案
后来我开始反过来想：
问题的关键，也许不是"缺少全局 Skill"，而是"项目内缺少统一入口"。
于是我先在仓库里整理出一套 docs/skills/：
- 每份文档对应一个问题域或模块
- 不追求大而全，只回答最关键的问题
- 遇到某类问题时，先读哪份文档、先看哪几个文件、先看哪类测试，都尽量说清楚
这样做之后，项目知识第一次有了一个稳定落点，而且它和代码天然放在同一个仓库里：
- 改代码的人可以顺手改文档
- 文档版本会跟着代码走
- AI 和协作者可以共用同一套入口
但新的问题也马上出现了：
项目里有了 docs/skills/，AI 怎么知道先去看它？
这时候我意识到，我真正需要的也许不是很多全局 Skill，而是一个很薄的全局 Skill。
于是我做了一个全局 router skill，名字叫 project-skill-finder。
它不存项目知识，只做一件事：
- 先去当前项目里找
docs/skills/INDEX.md - 再根据索引决定该读哪一两份项目文档
- 如果没有
INDEX.md，就退化到枚举docs/skills/*.md或skills/*.md - 如果整个项目都没有这些文档，就静默退化，不阻塞工作
这个设计一出来，我自己就觉得顺了很多。因为它把职责拆开了：
- 全局层只负责发现
- 项目层负责沉淀知识
而且上下文也不会一下子被塞满。先看索引，再按需读最相关的 1-2 份文档，比把一堆内容全塞进上下文稳得多。
这里还有一个很容易被问到的问题：
既然很多 Agent 已经有 memory，为什么还要做这个？
我现在的理解是：
memory更像"AI 记住了什么"project skills更像"项目知识如何被正式组织起来"
也就是说，memory 更适合记偏好、协作习惯和长期上下文；而项目 Skill 更适合承载：
- 这个问题域先看哪份文档
- 这块模块先读哪几个文件
- 关键测试入口在哪里
- 常见边界和坑是什么
两者不是替代关系，而是分工关系：
- memory 记住人和协作习惯
- project skills 承载项目知识
- 全局 router skill 负责把项目知识发现出来
最后落下来的结构
做到这里，我其实已经有了一套"能跑"的结构：
-
项目内
docs/skills/把项目知识收拢到仓库里，让它和代码一起演进。
-
一个全局的
project-skill-finder不负责背项目知识，只负责发现项目里的 Skill 文档。
-
一份 Skill 使用统计表
不只记录"有没有用过"，还记录"有没有帮助"和"没帮助的原因"。
统计表大概会长成这样：
| Skill | used_count | helpful_count | not_useful_count | not_useful_reasons | last_used_at | notes |
|---|---|---|---|---|---|---|
SSH_AND_EXECUTION.md |
8 | 6 | 2 | too_broad,outdated_content |
2026-04-11 13:09:50 | jump 和 deploy 入口有帮助，但 Windows 段落需要继续收紧。 |
COMMAND_SYSTEM.md |
5 | 5 | 0 | - | 2026-04-10 21:14:03 | 对路由、子命令和 suggestion 问题定位很快。 |
RENDERING_SYSTEM.md |
4 | 2 | 2 | too_shallow,missing_key_files |
2026-04-09 18:32:11 | 能提供背景，但对局部刷新问题的落点还不够直接。 |
这里我最看重的其实不是"用了多少次"，而是另外两个问题：
- 哪些 Skill 真正帮上了忙
- 哪些 Skill 被用了，但没帮上忙，为什么
比如 not_useful_reasons 里，可以记录：
description_unclearwrong_triggeroutdated_contentmissing_key_filestoo_shallowtoo_broadpoor_examples
有了这一层之后，Skill 就不再只是"写了放着"，而是开始变成一个可以持续观察、持续修正的系统。
为什么这套方法值得继续打磨
这套方法最让我满意的地方，不是"很完整"，而是"很能长"。
它不是一开始就要设计一个很重的系统，而是：
- 先从一两份项目文档开始
- 再补一个统一入口
- 再加一个很薄的全局发现器
- 最后再加上观察和优化机制
也就是说，这不是一次性大建设，而是一套可以随着项目慢慢长起来的结构。
我现在越来越觉得，很多 AI 协作方案之所以后面会失效，不是因为思路错了，而是因为一开始就太重、太理想化。
而这套方法相对稳的地方就在于：
- 全局层很薄
- 项目层可版本化
- 统计层可反馈
结语
我不是先想到要做一套 AI Skills 系统，而是在不断遇到"知识散、入口弱、效果不可见"这些问题之后，才一步步把它逼出来。到最后，它变成了一套我自己很愿意继续维护的结构：
- 全局 Skill 负责发现
- 项目文档负责沉淀
- 统计机制负责持续优化
对我来说，这比直接堆很多全局 Skill，或者单独维护一份大而全的文档，都更适合真实项目里长期协作的节奏。
源码
对应skill源码已经放到Gitcode和Github