前言¶
接手一個陌生倉庫時，最費時間的往往不是寫代碼，而是先搞清楚：項目用什麼框架、數據放在哪、接口怎麼暴露、登錄鑑權走哪條鏈路、本地怎麼跑起來、線上怎麼部署。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
