前言¶
接手一个陌生仓库时，最费时间的往往不是写代码，而是先搞清楚：项目用什么框架、数据放在哪、接口怎么暴露、登录鉴权走哪条链路、本地怎么跑起来、线上怎么部署。README 可能过时，口头交接容易遗漏，on-call 临时顶上时更是只能边搜边猜。
Agent Skills 是一套可移植的说明包，用 SKILL.md 把领域流程教给 AI Agent。codebase-onboarding 正是针对「快速理解陌生代码库」这个场景：并行拉起多个只读的 explore 子 Agent，分别调研架构、数据模型、API、认证与部署，再合成一份可落盘的入职文档。
这是什么¶
codebase-onboarding 收录在 spencerpauly/awesome-cursor-skills 仓库的 resources/codebase-onboarding/ 目录，归类在 Cursor-Native 技能列表中。官方一句话定位是：
Launch multiple explore subagents in parallel to investigate architecture, data models, auth, APIs, and deployment. Synthesize into an onboarding document.
也就是说，它不是让你手写一遍架构说明，而是规定 Agent 按固定工作流去「并行探查 → 汇总 → 写出 ONBOARDING.md」。技能文件本身是通用的 SKILL.md 格式；在 Cursor 中会自动被发现，也可在对话里用 / 手动调用。同类名称在其他仓库也有不同实现，本文只介绍 spencerpauly 这份原文。
核心流程与能力¶
官方 SKILL.md 把流程拆成三步。
1. 并行启动 5 个 explore 子 Agent¶
每个子 Agent 只负责一块，提示词在技能里写死，职责边界清晰：
| 子 Agent | 调研范围 |
|---|---|
| Architecture & Structure | 顶层目录、框架（如 Next.js / Express / Django）、monorepo 工具（turbo / nx）、关键配置、各 app/package 职责 |
| Data Models & Database | schema、ORM 模型、migration、seed；实体字段与关系；数据库与 ORM 类型 |
| API Routes & Endpoints | 路由定义；方法、路径、鉴权要求与用途；REST / GraphQL / tRPC 等风格 |
| Authentication & Authorization | 认证方案（Auth.js、Clerk、Supabase Auth 或自研）、会话、受保护路由、角色权限与中间件 |
| Deployment & Infrastructure | Dockerfile、Vercel / fly.toml / terraform 等、CI/CD、环境变量、本地启动方式 |
explore 子 Agent 是只读、偏搜索与阅读的类型，适合大范围摸底而不改代码。技能 Tip 写明：整段流程通常很快；若是 monorepo，还可按 app/package 再加额外探查 Agent。
2. 汇总成结构化入职文档¶
五个结果要合成一份文档，模板大致如下（命令与路径由探查结果填实）：
# Codebase Onboarding
## Quick Start
1. Clone the repo
2. Install dependencies: `<command>`
3. Set up environment: copy `.env.example` to `.env`
4. Run database migrations: `<command>`
5. Start dev server: `<command>`
## Architecture
...
## Data Models
...
## API Reference
...
## Authentication
...
## Deployment
...
## Key Files to Know
- `<file>` — <why it matters>
技能还要求文档「有观点」：突出应该先看的文件，而不是把目录树整份贴出来；并写入常见坑——易漏的环境变量、系统依赖、安装踩坑等。
3. 落盘保存¶
默认写到项目根目录的 ONBOARDING.md；若你指定了其他路径，按指定位置保存。这样新人、轮值同学和后续 Agent 会话都能直接引用同一份材料。
安装与启用¶
方式一：手动放入技能目录（仓库 README 推荐）¶
awesome-cursor-skills 的说明是：把现成的 SKILL.md 拷进 .cursor/skills/，Agent 会自动发现。对应本技能可整理为：
mkdir -p .cursor/skills/codebase-onboarding
# 从仓库下载或复制 SKILL.md 到该目录
# 源文件：
# https://github.com/spencerpauly/awesome-cursor-skills/blob/main/resources/codebase-onboarding/SKILL.md
目录结构应类似：
.cursor/
└── skills/
└── codebase-onboarding/
└── SKILL.md
按 Cursor Skills 文档，技能还会从这些位置加载：
| 位置 | 作用域 |
|---|---|
.agents/skills/、.cursor/skills/ |
项目级 |
~/.agents/skills/、~/.cursor/skills/ |
用户级（全局） |
为兼容其他工具，Cursor 也会加载 .claude/skills/、.codex/skills/ 以及对应的用户目录。name 须与文件夹名一致；本技能 frontmatter 中 name 为 codebase-onboarding，并设置了 user-invocable: true，适合在对话里显式调用。
方式二：用 npx skills 安装¶
vercel-labs/skills 提供跨 Agent 的技能安装 CLI。按该 CLI 的参数约定，可从该仓库按名称安装：
npx skills add spencerpauly/awesome-cursor-skills --skill codebase-onboarding
需要装到指定 Agent 时，可加 -a（例如 cursor、claude-code、codex）；加 -g 则装到用户目录。具体目标目录以 CLI 当前版本说明为准。
方式三：在 Cursor 里从 GitHub 导入¶
官方文档还支持：打开侧边栏 Customize → Rules → Add Rule → 选择 Remote Rule (Github)，填入仓库地址导入。适合不想手动拷贝文件的场景。
典型用法¶
安装后，在 Agent 对话中输入 /，搜索并选择 codebase-onboarding，或直接说明意图，例如：
/codebase-onboarding
请按技能流程并行调研本仓库，生成 ONBOARDING.md。
也可以指定输出位置：
帮我做 codebase onboarding，结果写到 docs/ONBOARDING.md，
并在 Key Files 里标出新人第一天该看的文件。
若仓库是 monorepo，可按官方 Tip 补充约束：
这是 turbo monorepo，除默认 5 路探查外，
请为 apps/web 和 packages/api 各加一路 explore，再汇总成一份文档。
Agent 应按技能执行：并行 spawn 五类 explore → 按模板合成 → 写入 ONBOARDING.md。生成后建议人工扫一眼 Quick Start 命令与环境变量是否和真实脚本一致，再提交到仓库供团队复用。
适用场景与注意点¶
适合这些情况：
- 新人入职或跨组支援，需要一份「能跑起来 + 知道去哪改」的地图
- on-call / 临时接手，先快速建立架构、鉴权与部署心智模型
- 仓库缺少有效 onboarding 文档，或 README 与现状脱节，需要从代码重新归纳
- 希望把探查结果固化成
ONBOARDING.md，减少重复口头讲解
使用时注意：
- 依赖 Cursor 的并行 explore 能力。 该技能列在 Cursor-Native 分类下，核心是同时拉起多个
explore子 Agent；在其他只支持通用SKILL.md、但不具备同类子 Agent 编排的环境里，效果可能打折，需按实际工具能力调整。 - 产出要复核。 自动汇总可能漏掉冷门脚本、私有部署细节或未入库的运维约定；关键启动命令、密钥来源、权限模型应以人工确认为准。
- 文档要有取舍。 官方要求突出「从这里开始」的文件与 gotchas，而不是无差别罗列；生成后可再删冗余、补业务语境。
- 同名技能勿混用。 其他作者仓库里也有叫
codebase-onboarding的技能，流程与产物（例如是否生成CLAUDE.md）可能不同；安装时认准 spencerpauly/awesome-cursor-skills 这一份。
小结¶
codebase-onboarding 把「摸清陌生仓库」固化成可复用的 Agent 工作流：五路并行探查架构、数据、API、认证与部署，再合成可提交的 ONBOARDING.md。对新人上手和临时接手都很实用。源码与说明见：
https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/codebase-onboarding
Agent Skills 通用说明见：
https://cursor.com/docs/skills
