cs-onboard
GitHub将仓库接入CodeStable体系，自动判断空仓库或迁移场景。生成标准目录骨架或审计报告与映射方案，支持旧版兼容处理，确保文档规范统一。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill cs-onboard -g -y
SKILL.md
Frontmatter
{
"name": "cs-onboard",
"description": "把新仓库或有零散文档的仓库接入 CodeStable 体系，两条路径自动判断：空仓库从零搭骨架，已有文档走审计 + 迁移映射。触发：用户说\"在这个项目里用 CodeStable\"、\"搭 CodeStable 结构\"、\"初始化 CodeStable\"、\"迁移到 CodeStable\"。"
}
cs-onboard
把仓库接入 CodeStable 工作流体系——白纸或已有零散文档的都行。本技能只做两件事：搭骨架、归旧档。骨架搭好后子工作流（feature / issue / compound 等）即可直接运行。
两条路径
| 路径 | 适用 | 产出 |
|---|---|---|
| 空仓库 | 仓库内无 spec 类文档，也没有 .codestable/ |
完整骨架 + 必要骨架文件 |
| 迁移 | 仓库内有零散文档 / docs/ / 部分 .codestable/ 结构 |
审计报告 + 迁移映射方案（用户逐条确认）+ 落盘 |
启动后先扫一次自动判断，不要让用户选——TA 大概率不知道项目里现有哪些文档。扫描结果模糊（如只有 README）就明说判断依据并问用户。
标准骨架（目标状态）
共享路径与命名约定的权威版本是项目里的
.codestable/reference/shared-conventions.md——本技能从技能包复制过去。下面只列 onboard 创建 / 检查的骨架文件。
.codestable/
├── attention.md CodeStable 技能启动必读的项目注意事项
├── requirements/ 需求聚合根（空目录 .gitkeep）
├── architecture/
│ └── ARCHITECTURE.md 架构总入口（首次创建为占位模板）
├── roadmap/ 规划层聚合根
├── features/ feature 聚合根
├── issues/ issue 聚合根
├── refactors/ refactor 聚合根
├── doc-sweeps/ 手动文档熵维护报告
├── compound/ 沉淀类统一目录（learning / trick / decision / explore）
├── tools/ 跨工作流共享脚本（onboard 释放）
│ ├── search-yaml.py
│ └── validate-yaml.py
└── reference/ 跨子技能共享参考（onboard 释放）
├── shared-conventions.md
├── tools.md
└── maintainer-notes.md
启动检查
先检查一次现状：
-
检查
.codestable/：不存在 → 空仓库候选；存在但不完整 → 迁移（部分补齐） -
旧 CodeStable兼容 CodeStable 经过多次改名，从 easysdd 到 codestable 再到 .codestable，如果遇到旧版的codestable目录，提示用户：
检测到旧版codestable。建议直接
git mv easysdd .codestable，结构 / frontmatter 完全兼容，rename 后即用。要我执行吗？同意 →
git mv easysdd .codestable，按迁移路径走（这时只需补齐可能缺失的attention.md、tools/和reference/）。想保留旧目录 → 告诉他子技能只读.codestable/，旧目录不会被读；按空仓库路径走新骨架 -
Glob 全仓库
.md（排除node_modules/.git/）：根目录DESIGN.md/ARCHITECTURE.md/SPEC.md/README.md；docs/doc/design/spec/wiki/；现有.codestable/下文件 -
检查
.codestable/attention.md：缺失则列为骨架待补齐项 -
汇报扫描结论：找到的相关文档（列路径）+ 走哪条路径 + 判断依据 + 不确定项
空仓库路径
步骤 1：和用户确认范围
- 项目名 / 简介（用于填
ARCHITECTURE.md占位） - attention.md 只建最小骨架；用户已经给出的项目硬约束才写入，不凭空代填
步骤 2：创建目录骨架
按下面顺序执行，不等用户逐步确认——骨架是整体一次性的：
.codestable/{requirements,roadmap,features,issues,refactors,doc-sweeps,compound}/.gitkeep.codestable/attention.md（最小骨架模板见同目录reference.md）.codestable/architecture/ARCHITECTURE.md（占位模板见同目录reference.md）.codestable/tools/（用cp -rf/Copy-Item -Recurse -Force整目录拷贝技能包cs-onboard/tools/，不要 Read 再 Write）.codestable/reference/（同上）
落盘用 shell 整目录覆盖，不要 Read 再 Write——这两个目录是机器共享资产，Read+Write 会截断大文件、改缩进、吃空行，还慢费 token。具体命令见迁移路径步骤 4。
步骤 3：attention.md 提醒
attention.md 已创建但默认只有空骨架。汇报时提醒用户：有编译前置、测试命令、目录禁区、凭证规则这类"每次 CodeStable 技能启动都必须知道"的信息，后续用 cs-note 一条条追加。
步骤 4：验收汇报
列建了哪些文件：
CodeStable 骨架已就绪。现在可以：开始新功能
cs-feat/ 报告问题cs-issue/ 沉淀知识cs-learn
迁移路径
步骤 1：生成审计报告
| 现有文件 | 推测内容类型 | 建议归入 CodeStable | 置信度 |
|---|---|---|---|
docs/DESIGN.md |
项目架构 | .codestable/architecture/ARCHITECTURE.md |
高 |
docs/feature-auth.md |
功能设计稿 | .codestable/features/YYYY-MM-DD-auth/auth-design.md |
中 |
SPEC.md |
功能需求？ | 需用户确认 | 低 |
置信度：高 = 语义明确匹配；中 = 可推断有歧义；低 = 不明确或映射多个位置都合理。
步骤 2：逐条对齐
中 / 低置信度的用 AskUserQuestion 问：
- 中：给推断理由，问"按这个方式归位？"
- 低：描述文件内容，给 2-3 个候选位置 + "跳过"
高置信度不逐条问但要在汇报里列，给用户复审机会——逐条问会让节奏失控。
步骤 3：处理已部分存在的 .codestable/
- 命名不符规范（
YYYY-MM-DD-{slug}格式）但有内容 → 提示用户问是否重命名 - 空占位（
.gitkeep/ 空.md）→ 直接补齐不问
步骤 4：补齐缺失骨架
对照标准骨架补齐用户确认后仍缺失的目录 / 文件。已有内容不覆盖。
.codestable/tools/ 和 .codestable/reference/ 一律用技能包新版本覆盖——这两个目录是技能包维护的共享资产，权威源在 cs-onboard/tools/ 和 cs-onboard/reference/，项目里的只是落盘副本。技能包升级后再跑 onboard 的目的之一就是刷新副本，留旧版本会让子技能按过时口径工作。
覆盖前在汇报列出被覆盖文件让用户知道；用户明确说"我改过 tools/xxx.py 请保留"才例外保留并标红。这是迁移路径唯一强制覆盖的动作，其他已有文件遵守"不经确认不动"。
落盘命令：
# macOS / Linux
cp -rf <技能包路径>/cs-onboard/tools/. .codestable/tools/
cp -rf <技能包路径>/cs-onboard/reference/. .codestable/reference/
# Windows PowerShell
Copy-Item -Recurse -Force <技能包路径>\cs-onboard\tools\* .codestable\tools\
Copy-Item -Recurse -Force <技能包路径>\cs-onboard\reference\* .codestable\reference\
不要：Read+Write 手工搬（截断 / 改缩进）、一个个 cp（多步骤多出错）、先比 diff（规则就是无条件覆盖）。
技能包路径一般是 skill 安装目录（~/.claude/skills/cs-onboard/ 或插件目录）。不确定先 ls 定位。拷完 ls .codestable/tools/ .codestable/reference/ 验证。
步骤 5：处理不迁移的文件
用户选"跳过"的文件：不移动 / 不删除 / 不重命名，汇报标"保留原位（未纳入 CodeStable）"。绝不允许未经确认就动——onboard 只允许 AI 整理不允许替用户做删除决定。
步骤 6：attention.md 提醒（同空仓库路径步骤 3）
步骤 7：验收汇报
列：迁移文件清单（from → to）、新建骨架、未迁移文件（保留原位）、下一步建议。
骨架文件模板
ARCHITECTURE.md 占位模板和 attention.md 最小模板见同目录 reference.md。
退出条件
-
.codestable/标准子目录都存在 -
.codestable/attention.md已建 -
.codestable/tools/和.codestable/reference/已从技能包复制 -
.codestable/architecture/ARCHITECTURE.md已建 - 迁移路径：每条映射都有明确处理结果（迁移 / 保留原位）
- 迁移路径：没有未经确认就移动的文件
- 验收汇报已给出
容易踩的坑
- 未经确认就移动 / 删除已有文件——迁移核心原则是用户拍板
- 替用户填 attention.md 实质内容——必须项目 owner 来定，AI 只提供模板
- 重新引入
AGENTS.md/CLAUDE.md兼容路径——CodeStable 的启动注意事项入口固定为.codestable/attention.md - 建完骨架立刻开始 feature/issue——onboard 是"搭环境"不是"开始干活"
- 低置信度直接执行——低 = 必须问
.codestable/tools/和.codestable/reference/走"不覆盖"保守策略——这两个必须用技能包新版本覆盖，否则升级后用户停留在过时口径- 用 Read + Write 手工搬——必须
cp -rf/Copy-Item -Recurse -Force整目录覆盖 - Glob 时忘记排除
node_modules/.git/——会让扫描结果充斥噪声
相关文档
.codestable/reference/system-overview.md— CodeStable 体系总览.codestable/reference/shared-conventions.md— 目录结构和共享口径的权威版本.codestable/attention.md— CodeStable 技能启动必读的项目注意事项.codestable/architecture/ARCHITECTURE.md— 架构总入口骨架
Version History
- e0220ca Current 2026-07-05 23:28
