SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsonboard

onboard

Coding & development

View repository

Updated 10-15 11:02

About this skill

Project Context

Generate a project context summary to help AI tools or team members quickly understand the project and take over the work.

Quick Start

One-liner: Generate a project context summary for AI tool handover or new session startup.

Most Common Usage: /onboard(auto-detect read/update)

Not suitable? Refactor project →/retrofit, Requirements definition →/requirements

Run Modes

/onboard              → 智能检测（询问读或写）
/onboard --read       → 只读取现有文档，不修改
/onboard --update     → 强制重新扫描更新
/onboard --realign    → 规范升级回扫：00-context.md 按当前 `context.v1` 查漏补缺（不重扫项目）。复用 [共享契约](../pipeline/references/realign.md)；推荐用户入口 `/pipeline realign`
Mode Read Document Scan Project Write File Applicable Scenario
Smart Detection ✅ Depends Depends When uncertain
--read ✅ ❌ ❌ New AI takes over project
--update - ✅ ✅ After completing a phase of work

Smart Detection Flow

检测 00-context.md 是否存在
        │
        ├── 不存在 → 自动进入更新模式
        │
        └── 存在 → 询问用户
                    ├── "读取现有内容" → 展示文档，不修改
                    └── "重新扫描更新" → 扫描项目，覆盖文件

Language Rules

  • Supports questions in Chinese and English
  • Replies uniformly in Chinese
  • Generates documents in Chinese

Trigger Conditions

  • User switches AI tools and needs to pass context
  • User starts a new conversation session
  • Team members need to understand the project
  • User requests a project briefing

Core Philosophy

Context Transfer Problem

会话 A (Claude Code)          会话 B (新 AI 工具)
        │                            │
        ├── 了解项目结构              │ ← 需要重新了解
        ├── 读取设计文档              │ ← 需要重新读取
        ├── 理解当前进度              │ ← 需要重新理解
        └── 知道下一步任务            │ ← 需要重新确认
                                     │
                    ┌────────────────┘
                    ▼
             /onboard
                    │
                    ▼
            生成上下文摘要
                    │
                    ▼
             快速接手项目

Core Principles：

  • One document contains all key context
  • A new AI can start working immediately after reading it
  • Avoid repeated exploration and questioning

Workflow

--read mode: Only reads the existing 00-context.md for display, without performing any scanning or writing. If the file does not exist, prompts the user to first run --update。

--update / auto mode：

1. 扫描 keel 文档
   │
   ▼
2. 提取关键信息
   ├── 项目概述
   ├── 技术架构
   ├── 当前进度
   └── 待办任务
   │
   ▼
3. 读取代码库盘点 + 采集运行态信息
   │
   ├── 委托 codebase-insight 获取结构化信息（模块、接口、数据对象）
   └── 直接采集运行态信息（git status、git log、目录结构等）
   │
   ▼
4. 生成上下文摘要
   │
   ▼
5. 输出文件（可直接传递给新 AI）

Output Files

Main File：docs/devdocs/00-context.md

This file is designed to be directly copied to a new AI tool as initial context.

Document Structure

Required frontmatter in the file header(basis for realign scanning):

---
generated_by: onboard
spec_version: context.v1
generated_at: 2026-04-23T10:30:00+08:00
---

# 项目上下文：<项目名称>

**生成时间**：YYYY-MM-DD HH:mm
**生成工具**：/onboard

---

## 1. 项目概述

### 1.1 项目目标
<从 01-requirements.md 提取；不存在时从 00-baseline.md 的「项目目的与边界」提取，并保留其来源标注>

### 1.2 核心功能
| 编号 | 功能 | 状态 |
|------|------|------|
| F-001 | <功能名称> | ✅ 已完成 / 🔄 进行中 / ⏳ 待开发 |

### 1.3 技术栈
<从 02-system-design.md 提取>

---

## 2. 系统架构

### 2.1 架构概览
<从 02-system-design.md 提取架构图>

### 2.2 核心模块
| 模块 | 职责 | 关键文件 |
|------|------|----------|
| <模块名> | <职责> | `src/xxx/` |

### 2.3 核心接口
<从 02-system-design.md 提取关键接口签名>

---

## 3. 代码结构

### 3.1 目录结构

<Actual project directory structure, obtained via ls/tree>


### 3.2 关键文件说明
| 文件 | 用途 |
|------|------|
| `src/index.ts` | 入口文件 |
| `src/config.ts` | 配置管理 |

---

## 4. 当前进度

### 4.1 总体进度
| 类型 | 总数 | 已完成 | 进行中 | 完成率 |
|------|------|--------|--------|--------|
| 功能点 | X | X | X | XX% |
| 开发任务 | X | X | X | XX% |

### 4.2 最近完成
- T-05: <任务名称> (YYYY-MM-DD)
- T-04: <任务名称> (YYYY-MM-DD)

### 4.3 当前进行中
- T-06: <任务名称>
  - 状态：<进度描述>
  - 涉及文件：`src/xxx.ts`

### 4.4 未提交变更
<如有未提交的代码变更，列出>

---

## 5. 待办任务

### 5.1 下一步任务
| 优先级 | 任务 | 依赖 | 关联需求 |
|--------|------|------|----------|
| P0 | T-07: <任务名称> | T-06 | F-002, AC-005 |

### 5.2 阻塞项
<如有阻塞项，列出>

---

## 6. 重要约定

### 6.1 编码规范
<!-- 阈值摘录自 /code-quality 核心阈值表，变更需同步；按项目实际约定覆写 -->
- 遵循 MTE 原则（可维护、可测试、可扩展），详见 `/code-quality`
- 函数不超过 50 行
- 参数不超过 5 个

### 6.2 测试要求
<!-- 阈值摘录自 /testing-guide 核心阈值表，变更需同步；按项目实际约定覆写 -->
- 单元测试覆盖率 ≥ 80%（详见 `/testing-guide`）
- 禁止弱断言

### 6.3 提交规范
<从 git log 提取项目提交风格>

---

## 7. 快速开始

### 7.1 环境准备
```bash
<安装依赖命令>

7.2 Running the Project

<运行命令>

7.3 Running Tests

<测试命令>

8. keel Document Index

Document Path Producer Description
(This table is generated based on the documents actually produced by the project; the number of rows varies by project)

Handover Suggestions：

  1. First read this document to understand the overall picture
  2. Check the status of "Currently In Progress" tasks
  3. Continue development from "Next Tasks"
  4. Consult the corresponding keel document for detailed issues

## 信息提取规则

### 从 keel 提取

| 信息 | 来源文档 | 提取内容 |
|------|----------|----------|
| 项目目标 | `01-requirements.md` | 需求背景、目标用户 |
| 功能列表 | `01-requirements.md` | F-XXX 功能点及状态 |
| 技术栈 | `02-system-design.md` | 技术选型表 |
| 架构图 | `02-system-design.md` | 架构概览图 |
| 核心接口 | `02-system-design.md` | 接口签名表 |
| 当前进度 | `04-dev-tasks.md` | 执行检查清单 |
| 待办任务 | `04-dev-tasks.md` | 未完成的 T-XX |

### 从代码库盘点提取

> 结构化信息（模块、接口、数据对象）从 `docs/codebase-insight.md` 读取，不存在时委托 `codebase-insight` 生成。
> 运行态信息（目录树、git 状态）仍由 onboard 直接采集。

| 信息 | 来源 |
|------|------|
| 系统边界 | codebase-insight.md → 系统边界章节 |
| 核心模块 | codebase-insight.md → 核心模块章节 |
| 公开接口 | codebase-insight.md → 公开接口章节 |
| 技术栈 | codebase-insight.md → 技术栈与约束章节 |
| 目录结构 | `ls -la` 或 `tree`（onboard 直接执行） |
| 关键文件 | 分析 package.json、入口文件（onboard 直接执行） |
| 未提交变更 | `git status`（onboard 直接执行） |
| 提交风格 | `git log --oneline -5`（onboard 直接执行） |
| 运行命令 | 从 package.json scripts 或 Makefile 提取（onboard 直接执行） |

### 「8. keel 文档索引」生成规则

> 清单说「keel 允许产出什么」，本节索引说「这个项目现在有什么」，二者不可互替。
> 路径模式与 owner 权威见 [shared/devdocs-layout.md](../shared/devdocs-layout.md)。

1. 列出 `docs/devdocs/` 下全部文件（含子目录，含非 `.md`，如 `.yaml` / `.txt`）
2. 逐个匹配清单的路径模式，取其 owner 作「产出方」列
3. 清单中有主文件的，在「说明」列标注 `<主文件> 的分册`
4. 匹配不到任何模式的，「产出方」列填 `待分类`，⛔ 不得省略不列
5. 清单里有模式但项目中无对应文件的，⛔ 不列（本节是项目现状，不是规范）

## 使用场景

### 场景一：完成工作，准备交接（--update）

```text
用户: /onboard --update

Agent: 正在扫描项目并生成上下文...
✅ 已更新 docs/devdocs/00-context.md

您可以将此文件内容复制给新的 AI 工具，它将快速了解项目并接手工作。

Scenario 2: New AI takes over the project (--read)

用户: /onboard --read

Agent: 正在读取项目上下文...

[展示 00-context.md 内容]

当前进度：8/12 任务已完成 (67%)
下一步：T-09 用户认证模块

建议从"待办任务"部分继续开发。

Scenario 3: When uncertain (smart detection)

用户: /onboard

Agent: 检测到 docs/devdocs/00-context.md 已存在（更新于 2 小时前）

请选择：
1. 读取现有内容（不修改）
2. 重新扫描更新

用户: 1

Agent: [展示现有文档内容]

Constraints

Generation Constraints

  • --read mode: only reads the existing 00-context.md for display, does not scan, write, or delegate the generation of any files
  • output files must be self-contained (not dependent on external links for understanding)
  • key information must be displayed directly (not just referencing document paths)

Content Constraints

  • Architecture diagram must be included (ASCII or Mermaid)
  • Must list actionable next steps
  • Sensitive information (keys, passwords) must not be included
  • File paths must be accurate and accessible

Update Constraints

  • Each generation overwrites the old file
  • Generation time must be recorded
  • If keel does not exist, prompt the user to run the relevant skill first

Skill Collaboration

Scenario Collaborating Skill Description
keel does not exist /retrofit Establish the project baseline first (00-baseline.md）
Progress information is outdated /sync Sync the document status first
Detailed tasks needed /dev-tasks View the complete task list
Memory file sync /agent-memory Update AGENTS.md; include the workflow routing section when syncing the keel project

Command Options

# 智能检测：根据文档存在状态询问用户
/onboard

# 只读模式：读取并展示现有文档，不做任何修改
/onboard --read

# 更新模式：强制重新扫描项目并更新文档
/onboard --update

Sub-Agent Summary Format

When this Skill runs as a sub-agent, return the following structured summary:

For envelope field definitions (reserved fields such as the status enum / blockers / output_files / new_ids), see shared/constraints.md §yaml-summary-v1; the example below focuses on the summary.details private fields.

skill: onboard
status: success | partial
summary:
  headline: "项目上下文已更新，进度 67%"
  details:
    mode: read | update | auto
    project_name: "<项目名>"
    progress: "X/Y tasks completed (XX%)"
    next_task: T-XX
    context_age: "<N hours/days since last update>"
blockers: []
output_files:                   # --update 模式
  - docs/devdocs/00-context.md
  # --read 模式：output_files: []（不写入文件）
new_ids: {}
next_recommended:
  skill: ""
  args: ""

output_files Rules：

  • --update / auto(write mode):[docs/devdocs/00-context.md]
  • --read：[](read-only, produces no files)

Next Steps

Handing-off party (Tool A)

  1. After completing the phased work, run /onboard --update
  2. to pass the 00-context.md content to the new AI tool

Taking-over party (Tool B)

  1. Run /onboard --read to understand the project
  2. Continue development from the "Pending Tasks" section
  3. After completing the work, run /onboard --update to update the context