开发项目可演进的 AI Skills 系统

[TOC](给项目做一层可演进的 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 负责把项目知识发现出来## 最后落下来的结构做到这里我其实已经有了一套“能跑”的结构1. 项目内 docs/skills/把项目知识收拢到仓库里让它和代码一起演进。2. 一个全局的 project-skill-finder不负责背项目知识只负责发现项目里的 Skill 文档。3. 一份 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_unclear- wrong_trigger- outdated_content- missing_key_files- too_shallow- too_broad- poor_examples有了这一层之后Skill 就不再只是“写了放着”而是开始变成一个可以持续观察、持续修正的系统。## 为什么这套方法值得继续打磨这套方法最让我满意的地方不是“很完整”而是“很能长”。它不是一开始就要设计一个很重的系统而是- 先从一两份项目文档开始- 再补一个统一入口- 再加一个很薄的全局发现器- 最后再加上观察和优化机制也就是说这不是一次性大建设而是一套可以随着项目慢慢长起来的结构。我现在越来越觉得很多 AI 协作方案之所以后面会失效不是因为思路错了而是因为一开始就太重、太理想化。而这套方法相对稳的地方就在于- 全局层很薄- 项目层可版本化- 统计层可反馈## 结语我不是先想到要做一套 AI Skills 系统而是在不断遇到“知识散、入口弱、效果不可见”这些问题之后才一步步把它逼出来。到最后它变成了一套我自己很愿意继续维护的结构- 全局 Skill 负责发现- 项目文档负责沉淀- 统计机制负责持续优化对我来说这比直接堆很多全局 Skill或者单独维护一份大而全的文档都更适合真实项目里长期协作的节奏。## 源码对应skill源码已经放到Gitcode和GithubGitcode: https://gitcode.com/arvinrong/agent-skillsGithub: https://github.com/ArvinRong/agent-skills