1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | migrate-radix-to-base-shadcn-ui-ui |
| 项目自述名称 | migrate-radix-to-base（SKILL.md front matter 内 name 字段原值） |
| 作者/维护者 | shadcn（shadcn/ui 项目创建者，个人身份，现于 Vercel 任职）；托管于 shadcn/ui 官方仓库 |
| 来源链接 | https://github.com/shadcn-ui/ui/tree/main/skills/migrate-radix-to-base |
| 许可证 | MIT（仓库级，GitHub API 实测） |
| GitHub Stars/Forks | 所属仓库 119,918 / 9,560（GitHub API 实测；注：该数字属整个仓库，是本技能所在项目的知名度参考，不代表这一个子技能自身的独立热度） |
| 最新版本 | 无独立版本号，随主仓库持续滚动更新；GitHub API 实测该子目录最近一次提交为 2026-07-03 |
| 安装方式 | 一键：npx skills add shadcn/ui --skill migrate-radix-to-base；或手动下载该子目录到本地 skills 目录 |
2. 功能介绍与亮点
这是 shadcn/ui 官方仓库自带的第二个 Agent Skill（与官方“shadcn”组件管理技能同仓库、不同子目录），专门指导 Agent 把项目中基于 Radix UI 的 shadcn 组件与手写代码，安全迁移到新的 Base UI 基座库。
核心能力：
- 双策略引擎：项目若是已知 shadcn 预设风格，优先走“黄金对照”策略——用 shadcn CLI 拉取官方 Radix 版与 Base 版源码逐文件三方合并（
git merge-file），自动保留用户自定义改动；无法对照时退化为基于映射表的手工转换引擎（asChild→render、Portal 结构、data-属性重命名等） - 两种迁移模式：渐进模式（逐组件迁移，用
<component>-base.tsx影子文件与消费者逐个切换 import，全程可中断续跑）与整项目模式（按依赖顺序批量迁移） - 安全护栏：强制在干净 Git 分支上工作、每个组件迁移前后跑一次 typecheck/build 建立基线、合并“零冲突”后仍强制 grep 扫描残留的
radix-ui引用，防止“合并显示无冲突但实际残留旧代码”的假阳性 - 专项参考文档：随 SKILL.md 附带 consumer-props、universal-patterns、class-mapping、wrapper-shapes 及按组件族拆分的 props 对照表（overlays/menus/form-controls/disclosure/display-misc），覆盖迁移中最容易出错的细节
亮点：随 shadcn/ui 主仓库同步维护、由项目创建者本人编写，针对性解决“Radix UI 停止新特性开发、Base UI 成为新默认选项”背景下真实存在的迁移刚需。
3. 适用场景
固定分类：前端与设计。
适合已用 shadcn/ui 搭建界面、想把底层无样式组件库从 Radix UI 切换到 Base UI 的前端开发者与团队；也适合只想迁移单个组件（如“迁移 accordion”）做渐进式验证的场景，以及需要一次性完成整个项目切换的场景。
4. 跨 Agent 兼容性
- Claude Code：✅ 兼容——本体是标准 SKILL.md 格式，官方社区安装工具
vercel-labs/skills（Vercel 出品，27,307 stars）文档明确列出 Claude Code 的技能目录映射 - Codex：✅ 兼容——同一安装工具文档明确列出 Codex 的技能目录映射
- OpenClaw：✅ 兼容——同一安装工具文档明确列出 OpenClaw 的技能目录映射
- Hermes Agent：✅ 兼容——同一安装工具文档明确列出 Hermes Agent 的技能目录映射
- 以上兼容性判断依据均为安装工具对目标目录的官方文档说明，未见针对本技能自身在 Codex/OpenClaw/Hermes Agent 上的实测使用反馈
5. 推荐理由
Radix UI 已停止新特性开发，Base UI（同一批核心作者打造的继任者）成为 shadcn/ui 的新默认选项，但两者 API 有实质差异（asChild vs render、Portal 结构、data-属性命名等），社区里关于“怎么从 Radix 迁移到 Base UI”的讨论热度不低，但此前长期没有自动化方案，只有第三方博客给出的人工分步指南。这个官方技能把“读官方对照源码三方合并 + 手工转换引擎兜底 + Git 分支隔离 + 强制回归检查”整套流程自动化，是目前少见的把这条迁移路径真正做成可执行工具的方案，而非停留在文档层面的建议。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 8 | shadcn/ui 官方出品，由项目创建者本人维护；所属仓库 119,918 stars 属 shadcn/ui 组件库整体，不代表本迁移技能自身热度；本技能自身暂未见具名第三方评测或独立采用数据 |
| 可用性 | 9.0 | 一条命令安装（npx skills add shadcn/ui --skill migrate-radix-to-base）；SKILL.md 正文与 9 份专项参考文档一起构成完整文档体系；最近一次提交距今约 3 周；无付费依赖 |
| 安全性 | 8.0 | 见下方安全检查清单 |
| 综合 | 8.67 | 三项均值，远超 7.0 达标线，安全性远超一票否决线 |
安全检查清单：
- Shell/权限范围：front matter 未声明
allowed-tools限制，理论上可使用 Agent 具备的通用 Shell 能力，但正文明确限定用途——仅用于npx shadcn@latest info/add、Git 分支/提交、git merge-file、项目自身的 typecheck/build 命令，且反复强调“先建干净分支”“一次一个组件”等安全约束 - 联网外发：仅从 shadcn 官方 registry 与包管理器仓库拉取代码/依赖，是迁移功能本身需要的公开行为，无隐蔽外发
- API Key/凭据：未见任何要求提供 API key 或凭据的指令
- 可疑指令/注入迹象：完整抓取 SKILL.md 全文核实，未发现要求执行流程外操作、访问敏感文件或篡改 Agent 行为的可疑指令
- 作者/组织信誉：shadcn 本人（shadcn/ui 创建者）维护，身份可验证、信誉高
- License：MIT，明确清晰
- 维护时间：该子目录最近一次提交 2026-07-03（约 3 周前），随主仓库持续滚动更新
7. 跟同类 Skills 相比的优势
| 方案 | 定位 | 与本技能的差异 |
|---|---|---|
| 手工分步迁移（第三方博客指南，如 shadcnstudio.com《Migrate from Radix UI to Base UI in 9 Easy Steps》） | 人工阅读文档、逐组件手改代码 | 只给出步骤说明，不含自动化对照合并或回归验证，全靠人工执行且容易漏改 |
shadcn add <component> --overwrite（裸 CLI，不配合本技能） |
直接用 Base 版源码覆盖本地文件 | 会抹掉用户对组件的自定义改动，且不处理消费者代码里的 API 差异（如 asChild→render）与残留引用排查 |
Base UI 官方 Issue #2970（mui/base-ui 仓库，社区提议做迁移 codemod） |
官方仍处于“讨论要不要做”阶段 | 尚无官方自动化工具落地，本技能是目前已实际可用的自动化方案 |
8. 用户评价
该技能目前在第三方技能目录站与 GitHub 上尚无具名用户评价；同名迁移话题本身在 shadcn/ui 官方 GitHub Discussions 中有过百余条历史讨论，反映真实社区需求，但均早于本技能发布、非针对本技能的评价。
9. 其他补充
本技能与 shadcn/ui 官方仓库内的另一个组件管理技能（shadcn）同属一个仓库、互相独立触发，安装其中一个不会自动带入另一个；两者可以同时安装，分别覆盖“日常组件开发”与“底层库迁移”两类不同场景。
10. 安装使用方式
- 通用安装（推荐）：
npx skills add shadcn/ui --skill migrate-radix-to-base，支持-a/--agent参数指定安装到 Claude Code / Codex / OpenClaw / Hermes Agent 等具体 Agent 目录 - 直接指定源路径安装：
npx skills add https://github.com/shadcn-ui/ui/tree/main/skills/migrate-radix-to-base - 手动安装：下载
skills/migrate-radix-to-base/整个目录（含 SKILL.md 与全部参考文档）到对应 Agent 的 skills 目录 - 安装后注意事项：技能通过 description 中的关键词（“migrate from radix”、“move to base-ui”等）触发，无需重启 Agent；使用前需在项目中已安装 shadcn CLI 且项目含
components.json
11. 注意事项
- 该子目录本身只有 1 次提交历史，是相对新的能力（2026-07-03 上线），尚未见到大规模实战反馈
- front matter 未声明
allowed-tools，实际权限范围取决于宿主 Agent 的通用工具授权，建议在独立分支中使用并人工复核每次提交 - 迁移前提是项目已在使用 shadcn CLI 管理组件（
components.json存在）；纯手写 Radix 代码或非 shadcn 项目会退化到手工转换引擎路径，覆盖度弱于“黄金对照”路径 - Base UI 本身仍在快速迭代，部分组件的 Base 版本 API 可能与文档中的对照表出现滞后