1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | contentful-migration（contentful/skills 技能包内子技能） | GitHub API |
| 作者/维护者 | Contentful（官方仓库，contentful 组织维护） |
GitHub API |
| 来源链接 | https://github.com/contentful/skills/tree/main/skills/contentful-migration | — |
| 许可证 | MIT License | GitHub API |
| GitHub Stars / Forks | 37 ★ / 2 forks（仓库整体；子技能自身热度见第 7 章说明） | GitHub API |
| 最新版本 | 无独立语义化版本号；SKILL.md 最近一次实质性修订 2026-05-13 | GitHub API |
| 安装方式 | 插件市场一条命令或单技能安装（见第 10 章） | 仓库 README |
2. 功能介绍与亮点
contentful-migration 教 AI 编码助手用 contentful-migration 库与 Contentful CLI 编写并执行内容模型迁移脚本，覆盖：
- 内容类型与字段增删改：创建/编辑/删除 Content Type，字段的增加、改名、移动、类型变更
- 校验规则：范围、正则、关联类型限制、资源文件大小/尺寸等十余种字段校验的配置写法
- 条目转换：原地转换字段数据、从已有字段派生出新的关联条目、按类型批量迁移条目
- 编辑器界面配置：字段控件、侧边栏组件、编辑器布局的迁移写法
- 工程实践指导：迁移文件按序号命名、先在 sandbox 环境验证再上生产、schema 变更与数据转换分两步走、常见报错清单（如漏写 Array 的 items、对含条目的 Content Type 直接删除）
亮点：官方出品、MIT 开源、附带三份独立参考文档（API 参考、模式示例、运行方式），内容组织成“速查表 + 工作流 + 常见错误”结构，可直接照抄验证。
3. 适用场景
所属分类：集成与工作流自动化
需要给 Contentful 内容模型做结构性变更的开发者——新增字段、调整校验规则、批量转换历史条目、搭建编辑器控件——都可以让 Claude 直接生成并执行迁移脚本，不必逐条翻文档拼接 API 调用。受益人群：使用 Contentful 作为内容后端的前端/全栈工程师、负责内容架构演进的技术团队、需要频繁改动 Schema 的初创产品团队。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持——README 给出
/plugin marketplace add+/plugin install命令 - Codex：✅ 支持——README 明确列出 OpenAI Codex 为支持平台之一，并提供跨平台通用安装命令
npx skills add - OpenClaw：❓ 未验证——已抓取材料未提及
- Hermes Agent：❓ 未验证——已抓取材料未提及
5. 推荐理由
内容模型迁移是 Contentful 使用中容易出错、且缺乏统一范式的环节——字段类型选错、忘记处理已有条目、直接对生产环境跑未测试脚本，都是真实踩坑点。这个技能把官方推荐的“先 sandbox 验证、schema 与数据转换分离、迁移文件按序号命名”等实践直接固化进 AI 助手的输出里，配合结构化的字段类型与校验速查表，能让不熟悉 contentful-migration 库细节的开发者少走弯路。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Contentful 官方出品，仓库整体 star 数不高（37★），但作为知名 headless CMS 厂商的官方技能包，品牌可信度可观 |
| 可用性 | 8 | 文档结构清晰（速查表+工作流+常见错误），附三份参考文档；需配置 Contentful Management API Token；核心内容最近一次实质修订在近 6 个月内 |
| 安全性 | 8 | 见下方检查清单 |
安全检查清单：
① Shell 执行权限限定为 npx contentful-migration / npx contentful space migration 两类命令，范围明确、不可越界执行任意脚本；② 运行时仅与 Contentful 官方 API 通信，无隐蔽外发；③ 需要 Contentful Management API Token（CMA Token），SKILL.md 明确说明获取路径与本地环境变量存放方式；④ 未发现可疑指令或混淆代码；⑤ 官方组织仓库，无造假迹象；⑥ MIT 许可证明确；⑦ 核心文件近 6 个月内有实质性人工提交。扣分点：CMA Token 权限较高（可增删内容类型与字段，操作不当会造成数据丢失），虽有 sandbox 验证的工作流指导缓解风险，仍未到 9 分档。
7. 跟同类 Skills 相比的优势
| 技能 | 定位 | 与 contentful-migration 的差异 |
|---|---|---|
| contentful-migration（本技能） | Contentful 官方单一聚焦技能，专攻内容模型迁移脚本编写 | 范围窄但深——附带完整字段类型/校验速查表与常见错误清单 |
| contentstack-agent-skills（Contentstack 官方，21 技能合集） | 竞品 headless CMS Contentstack 的官方技能包，涵盖内容建模、Delivery SDK、迁移工作流、Developer Hub 应用等全流程 | 覆盖面远更广（21 个技能打包），但单个技能的迁移场景不如 contentful-migration 聚焦，仓库本身也更新（4★，社区反馈证据更薄） |
同一技能包内还搭配 contentful-guide（概念路由）与 contentful-api（语言无关 API 参考）等姊妹技能，三者分工明确：迁移改结构、guide answer概念问题、api 管 HTTP 调用细节。
8. 用户评价
该技能目前在 Reddit、Hacker News 等第三方平台尚无具名用户评价可查；仅有 Contentful 官方博客与一篇竞品公司（Cosmic）CEO 撰写的产品对比文章提及，后者未提供具体使用体验，不构成独立评价来源。
9. 其他补充
技能包同一仓库还提供 contentful-personalization（个性化/A-B 测试）、contentful-custom-app-from-scratch 与 contentful-custom-app-enhancement（App Framework 自定义应用开发）等技能，覆盖 Contentful 生态的不同环节。
10. 安装使用方式
- Claude Code（完整技能包）：
会同时注册 contentful-mcp 与 contentful-personalization 两个 MCP 连接/plugin marketplace add contentful/skills /plugin install contentful@contentful /reload-plugins - 仅安装本技能（通用 CLI，支持 Claude Code / Copilot / VS Code / Codex / Gemini CLI 等 35+ 平台）：
npx skills add contentful/skills --skill contentful-migration - Cursor：Settings → Rules → Add Rule → Remote Rule (GitHub)，填入
contentful/skills - Gemini CLI：
gemini skills install contentful/skills
安装后需在项目 .env 或 .env.local 中配置 CONTENTFUL_SPACE_ID 与 CONTENTFUL_MANAGEMENT_ACCESS_TOKEN（后者在 Contentful 后台 Account settings → CMA tokens 获取）；技能会先检查这两个变量是否存在，缺失时会提示用户补充。
11. 注意事项
- 需要有效的 Contentful 空间与 Management API Token，且该 Token 具备内容模型的完整读写权限，妥善保管
- 官方明确建议所有迁移先在 sandbox 环境（
contentful environment create --name sandbox）验证后再对生产环境执行，技能本身不会阻止直接对生产库操作 - 删除 Content Type 前必须清空该类型下的全部条目，否则迁移会失败
- 仅覆盖
contentful-migration库与 CLI 的使用；SDK 客户端配置、Next.js 集成、Contentful 基础概念分别由同仓库的 contentful-nextjs、contentful-guide 技能覆盖