@cloudai-design/skills

CloudAI UI 的 AI 语境内容。五个 skill 平铺，由 @cloudai-design/cli 装进业务仓的 .agents/skills/（并为探测到的工具建镜像）。本包只有 markdown，没有运行时代码。

| skill | 什么时候被触发 | | ------------------------------- | -------------------------------------------------- | | cloudai-design-system | 写任何 UI / 样式、取 token、确认配色与间距档位 | | cloudai-components | 选组件、查 props / 安装命令、确认不要手搓已有组件 | | cloudai-design-spec-generator | 做一个新页面 / 新功能，需要先出设计方案 | | cloudai-design-review | 已有页面要评审、找出违反设计体系的地方 | | cloudai-page-templates | 想直接套一个完整页面模板（当前尚未建设，会转路由） |

三种内容，三个编辑处

baseline 正文直接在本包对应 skill 目录中维护；不要手改 generated/ 和 brands/，它们是产物，下一次 pnpm tokens:emit 会覆盖。

| 内容 | 编辑处 | 说明 | | ------------------------------ | --------------------------------------------------------- | ----------------------------------------------------------- | | baseline 正文（各 skill 目录） | 本包内直接改 | 跨 brand 的判断规则，不承载某个 brand 的准确取值 | | generated/{brand}-tokens.md | brands/<brand>/tokens/figma/ + tokens/full-value.json | 由 token IR 生成；安装时写成 reference/tokens.md | | generated/component-index.md | apps/v3/registry.json + 组件源码 | 由 registry 生成；安装时写成 reference/component-index.md | | brands/<brand>/（overlay） | 仓库根 brands/<brand>/skills/ | 只放 delta，随包带走供 CLI 合并 |

手写的 token 名录与组件清单腐烂过：新增 brand 会拿到别人的取值，组件改名后索引指向不存在的文件。 所以这两类一律生成，baseline 里只留指针。一个文件要么全生成、要么全手写，不做混合。

cloudai-design-system 的 baseline 只维护入口和五篇按问题拆分的手写 reference：

cloudai-design-system/
├── SKILL.md
└── reference/
    ├── hierarchy.md
    ├── layout.md
    ├── states.md
    ├── color.md
    └── motion.md

安装时再按当前 brand 注入 generated reference/tokens.md；brand overlay 可以追加少量产品专属文件，例如 aidbs 的 reference/chat-composition.md。因此不要在 baseline 手写 tokens.md，也不要把产品页面配方补回通用 reference。

合并规则（CLI 安装时）

baseline + brands/<brand>/ overlay，文件级合并：

• 同名文件 → overlay 覆盖
• overlay 新增文件 → 追加
• SKILL.md → 取 overlay 的 <!-- BRAND:start --> … <!-- BRAND:end --> 块，注入 baseline 的同名空块
• overlay 里没出现的 skill → 取 baseline 原样，不需要占位空目录

禁止目录级替换：那会让 baseline 的后续更新在该 skill 上永久失效。 tools/emitters/skill-overlays.ts 在构建期就拦住写错的 overlay（目录名不匹配、 SKILL.md 被误写成整份文档、baseline 缺 BRAND 槽位）。

cloudai-design-system/SKILL.md 另有一对 <!-- ROOT:start --> / <!-- ROOT:end --> 标记， 划出的正文会被抽成业务仓根目录的 DESIGN.md——这是 skill 装不上时的兜底，与 BRAND 标记无关。

契约细节（skill 名单、旧名清理、生成物映射、标记字符串）都在 manifest.json， CLI 读它而不是自己硬编码一份名单。