给 AI 助手建一本技能手册：mattpocock/skills 破 7.6 万星背后的知识库思路

一个 Shell 语言的项目，没有编译产物，没有 Web 界面，单日新增 3867 星、总量冲到 76413——mattpocock/skills 做的事情听起来极其朴素：把个人经验写成结构化的 Markdown 文件，放进 .claude/ 目录，让 AI 编程助手在每次对话时自动加载。

但这个"朴素"的动作正在成为开发者与 AI 协作的新基础设施。同日榜单上，AI 智能体代码质检工具 react-doctor 也首次亮相，说明"给 AI 写规则、让 AI 执行规则"这条路径正在快速扩展。本文拆解 skills 仓库的核心思路，并给出一份可直接动手的技能文件模板。

skills 仓库到底装了什么

mattpocock 是 TypeScript 社区里高产的教程作者，他的 .claude/ 知识库本质上是一组指令文件（instruction files），每份文件针对一个具体工作场景：

• 代码风格偏好——命名约定、文件组织方式、错误处理模式
• 项目架构约定——某个 monorepo 的目录结构、模块边界规则
• 常见决策记录——遇到某类问题时优先选 A 而不是 B，附带理由
• 调试流程——出现特定报错时的排查步骤清单

这些文件用自然语言写成，格式是 Markdown，Claude Code 在启动时会读取 .claude/ 目录下的所有文件，把它们作为上下文注入到每次对话中。效果是：AI 不再每次从零猜测你的偏好，而是带着一本"员工手册"上岗。

为什么这比在对话里反复叮嘱更有效

传统做法是在每次对话开头写一段长提示词："我喜欢函数式风格、不要用 class、错误处理用 Result 模式……"问题很明显：

1. 每次都要写，遗漏一次 AI 就回到默认行为
2. 长度受限，对话上下文窗口被提示词挤占
3. 无法分层，所有规则堆在一起，AI 难以区分优先级

skills 方案的差异在于：规则持久化在文件系统中，按场景分文件组织，Claude Code 自动加载而非手动粘贴。这把"提示词工程"从一次性劳动变成了可维护的知识资产。

动手：为你的项目写一份技能文件

以下是一个可直接使用的最小示例。假设你有一个 Node.js + TypeScript 项目，希望 AI 助手遵循你的架构偏好。

第一步：创建目录和文件

# 在项目根目录下创建 .claude 目录
mkdir -p .claude

# 创建核心技能文件
touch .claude/project-architecture.md
touch .claude/code-style.md
touch .claude/debug-workflow.md

第二步：写入具体规则

<!-- .claude/project-architecture.md -->
# 项目架构约定

## 目录结构
- `src/modules/` 下每个子目录是一个独立业务模块
- 模块内部遵循: `index.ts`(导出) → `service.ts`(逻辑) → `types.ts`(类型定义)
- 跨模块引用只允许通过 `index.ts` 的公开接口，禁止直接 import 内部文件

## 数据层
- 所有数据库操作集中在模块的 `repository.ts` 中
- 禁止在 service 层直接写 SQL 或调用 ORM 的原始查询方法

## 新增模块 checklist
1. 在 `src/modules/` 下创建目录
2. 实现 `types.ts` → `repository.ts` → `service.ts` → `index.ts`
3. 在 `src/modules/index.ts` 中注册新模块导出
4. 补充对应的单元测试，测试文件放在模块内 `__tests__/` 目录

<!-- .claude/code-style.md -->
# 代码风格偏好

## 命名
- 函数: camelCase，动词开头 (getUserById, calculateTotal)
- 类型/接口: PascalCase，名词 (UserProfile, OrderItem)
- 文件名: kebab-case (user-profile.ts, order-item.ts)
- 常量: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)

## 错误处理
- 使用 neverthrow 的 Result 类型，禁止抛异常作为正常流程控制
- Result.err 的 error 类型必须是自定义的 DomainError 子类
- 只有在真正"不可恢复"的场景（如网络断连、磁盘故障）才用 throw

## 禁止事项
- 不要使用 class 和 this
- 不要使用 any，遇到无法避免的情况用 unknown + 类型守卫
- 不要引入新的 npm 包而不先说明理由

<!-- .claude/debug-workflow.md -->
# 调试流程

## TypeScript 编译错误
1. 先检查类型定义是否在 `types.ts` 中正确导出
2. 确认 `tsconfig.json` 的 paths 配置覆盖了相关模块
3. 如果是跨模块引用报错，检查是否绕过了 index.ts 公开接口

## 运行时错误
1. 查看错误栈，定位到具体模块的 service.ts
2. 检查输入是否经过 types.ts 中定义的类型守卫验证
3. 如果是数据库相关，先看 repository.ts 的查询参数是否匹配 schema

## 通用原则
- 修改代码前先写一个能复现问题的最小测试
- 每次只改一个地方，改完跑测试再继续

第三步：验证加载效果

# 在项目目录下启动 Claude Code
claude

# 在对话中直接问一个架构问题，观察是否遵循了你的规则
# 例如: "帮我新增一个订单模块"
# AI 应该按照 project-architecture.md 中的 checklist 流程操作

如果你不用 Claude Code，这套思路同样适用于其他支持"项目级上下文文件"的 AI 工具。Cursor 的 .cursorrules、Copilot 的 .github/copilot-instructions.md 都遵循类似模式，只需把文件放到对应目录、调整文件名即可。

react-doctor 信号：AI 执行规则，AI 检查规则

同日上榜的 react-doctor 代表了这条路径的下一步：不仅让 AI 读规则，还让 AI 主动检查代码是否违反规则。这是一个面向 React 项目的 AI 智能体代码质检工具——它读取项目约定后扫描代码库，输出违规报告。

这形成了一个闭环：

人写规则 → AI 读规则并遵循 → AI 检查产出是否合规 → 人修订规则

skills 仓库解决的是前半段"AI 读规则"；react-doctor 这类工具补上了后半段"AI 检查合规性"。两者结合，AI 协作就从"靠自觉"变成了"有审计"。

从个人技能库到团队知识基座

mattpocock/skills 目前是个人知识库，但 7.6 万星说明需求远超个人范畴。几个值得思考的演进方向：

如果你在团队中推行，建议从最小集开始：先写 3-5 条最常在代码评审中重复说的话，把它们变成技能文件。这比一次性写 50 条规则更实际——规则太多 AI 反而会忽略优先级。

上手清单

1. 今天就能做：在当前项目根目录创建 .claude/，写一份 code-style.md，把你最在意的那 3 条风格规则放进去
2. 本周可以做：补一份 project-architecture.md，把目录结构和模块边界约定写清楚，新同事和 AI 都能受益
3. 下个迭代考虑：引入 react-doctor 或类似工具，让 AI 定期扫描代码库产出合规报告，把"人审代码"中重复的部分交给 AI 初筛
4. 长期方向：把技能文件从项目目录抽到独立仓库，团队共同维护，通过 CI 同步到所有项目——这本质上是把隐性的团队文化变成了显性的、可版本控制的知识资产

7.6 万星不是给 Shell 语言的，是给"把人的经验变成 AI 可执行的知识"这个思路的。最值得抄的不是仓库本身，而是它背后的组织方式：一份文件管一个场景，自然语言写规则，文件系统做持久化，AI 自动加载。