1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | provider-framework-migration-hashicorp-agent-skills |
| 作者/维护者 | HashiCorp（现为 IBM 旗下） |
| 来源链接 | https://github.com/hashicorp/agent-skills/tree/main/plugins/terraform/skills/provider-framework-migration |
| 许可证 | MPL-2.0（数据来自 GitHub API） |
| GitHub Stars | 802（数据来自 GitHub API；该数字属整个 hashicorp/agent-skills 合集仓库，不代表本技能自身热度） |
| Forks | 119（同上，合集整体数字，数据来自 GitHub API） |
| 最新版本 | 0.0.1（SKILL.md 内声明） |
| 安装方式 | npx skills add 单条命令，或 Claude Code / Codex 官方插件市场安装产品插件包 |
2. 功能介绍与亮点
provider-framework-migration 指导 Terraform Provider 开发者把资源与数据源从旧的 Plugin SDKv2 迁移到新一代 Plugin Framework，覆盖从“要不要迁”到“迁完怎么验证”的完整链路：
- 迁移前的取舍判断：明确指出“复杂或高频使用的资源没有驱动力就不要迁”——这是
terraform-provider-aws的既定策略，避免为迁移而迁移引入破坏性变更；无DiffSuppressFunc/CustomizeDiff/StateFunc、扁平 Schema 的简单资源才适合迁； - Mux 双协议桥接搭建：给出可运行的
main.go示例，用tf5to6server+tf6muxserver让 SDKv2 与 Framework 并存于同一 Provider，实现逐资源增量迁移而非一次性重写； - 完整的 SDKv2 → Framework 映射表（
references/schema-mapping.md）：覆盖 Schema 类型、ForceNew/ValidateFunc/Timeouts等行为字段、CRUD 函数签名、d.Get/d.Set/d.HasChange等数据访问模式的逐项对照； - null-vs-zero-value 行为陷阱专章：SDKv2 把“未设置”与空字符串/0/false 混为一谈，Framework 严格区分 null/unknown/zero，是迁移中最容易产生静默破坏性变更之处，技能给出逐属性核对三种取值场景的审计方法；
- 迁移后验证流程：验收测试须原样通过、
ImportStateVerify捕获状态不一致、用“旧版本应用 + 新版本 plan 应为空”的双步测试断言迁移不改变用户可见行为； - 附带一份 8 项迁移检查清单，可直接用作代码评审依据。
亮点：内容对齐 HashiCorp 官方迁移指南（developer.hashicorp.com/terraform/plugin/framework/migrating），把分散在多篇官方文档中的映射规则、行为陷阱、验证步骤整合为可直接被 Agent 调用的结构化参考；技能全程不涉及代码执行，纯粹是可审计的迁移方法论与映射表。
3. 适用场景
所属分类：工程效率与代码质量（该技能围绕“如何安全地改写 Terraform Provider 的 Go 源码”这一具体编码任务展开，产出是 Go 源码变更与迁移验证测试，属于技术栈编码指南范畴，不涉及部署或运维基础设施本身）。
适用于维护 Terraform Provider 的开发者：决定某个资源是否值得从 SDKv2 迁移到 Framework 时评估风险；搭建 Mux 双协议 Provider 时；把具体资源的 Schema 与 CRUD 代码翻译到 Framework 时；或迁移后出现 plan diff 异常、状态错误需要排查根因时。受益人群是 Terraform Provider 的开发者与维护者，而非普通编写 .tf 配置做基础设施部署的工程师。
4. 跨 Agent 兼容性
- Claude Code：原生支持 ✅——可通过 Claude Code 官方插件市场安装
terraform@hashicorp产品插件包，或用npx skills add单独安装该技能。 - Codex：原生支持 ✅——仓库自带专属
.agents/plugins/marketplace.json清单，可作为仓库市场添加后安装terraform插件，与 Claude Code 插件市场暴露相同的产品包与技能目录。 - OpenClaw：未验证 ❓——官方文档未点名支持，技能本体是标准 SKILL.md 格式。
- Hermes Agent：未验证 ❓——同上。
5. 推荐理由
SDKv2 到 Plugin Framework 的迁移是长期维护 Terraform Provider 的团队迟早要面对的任务，但风险点隐蔽——null-vs-zero 行为差异这类问题往往要到用户升级后才暴露为破坏性变更，且官方指南分散在多篇文档中，需要自行拼凑映射规则与验证步骤。这份技能把映射表、Mux 搭建代码、行为陷阱清单与验证流程整合成一份可直接被 Agent 调用的操作手册，能显著降低迁移中引入静默破坏性变更的概率。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | HashiCorp 是 Terraform 的官方所有者；合集仓库 802 stars 属整个 hashicorp/agent-skills 仓库，不代表本技能自身热度；该子技能于 2026-08-10 新增，尚无独立于官方身份之外的第三方证据（媒体报道、独立评测、采用数据） |
| 可用性 | 9 | npx skills add 单条命令即可安装，亦可通过 Claude Code / Codex 官方插件市场一键装入产品包；SKILL.md 含完整可运行代码示例、8 项检查清单与一份独立的映射参考文档；2026-08-10 创建并为仓库当次重组新增，维护活跃；无付费依赖 |
| 安全性 | 9 | 纯 Go 代码范例与迁移方法论指南，技能本体不执行任何 shell 命令、不联网外发数据；License 清晰（MPL-2.0）；由 Terraform 的官方所有者 HashiCorp 发布，完全开源可审计 |
安全检查清单逐项结果：
① Shell 命令执行：无，技能只提供代码范例与文字指导，不会自动执行任何命令 ② 联网外发：无 ③ API Key/凭据存储：不涉及，技能内容与凭据处理无关 ④ 可疑指令（Prompt Injection 迹象）：未发现 ⑤ 作者/组织信誉：HashiCorp，Terraform 生态的官方所有者 ⑥ License：MPL-2.0，明确 ⑦ 最近维护时间：2026-08-10（近期，随仓库结构重组新增）
7. 跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与本技能的差异 |
|---|---|---|
| HashiCorp 官方迁移文档（developer.hashicorp.com/terraform/plugin/framework/migrating） | 面向人类阅读的迁移指南，分 Provider 级与 Resource 级两篇 | 内容权威详尽，但以散文形式分布在多个页面，需自行提炼映射表、拼凑检查清单；本技能把同一套官方知识重组为可被 Agent 直接调用的结构化操作手册 |
| provider-actions / provider-resources（HashiCorp，同仓库） | Framework 下资源 CRUD、finder/waiter 等编码模式 | 服务于“用 Framework 写新代码”，不处理“如何把已有 SDKv2 代码安全翻译过去”这一迁移专属问题（Schema 映射、状态兼容性验证、null-vs-zero 陷阱） |
terraform-provider-aws 内部 tfsdk2fw 脚手架工具 |
少数大型 Provider（如 AWS）内部使用的半自动生成脚本，非公开可复用工具 | 只做机械代码转换草稿，不判断资源是否该迁、不覆盖验证与检查清单；本技能提供脚手架工具没有的判断框架与验证流程，并明确“生成代码只是待审查草稿” |
8. 用户评价
该技能于 2026-08-10 随仓库结构重组新增，目前在第三方平台尚无具名用户评价。所属 HashiCorp Agent Skills 合集本身已有官方博客文章介绍 Provider 开发相关技能的整体定位，但未点名介绍本技能。
9. 其他补充
SKILL.md 原文建议配合 provider-resources 技能使用（迁移后用 Framework 实现移植代码中的 CRUD、finder、waiter 模式），以及 provider-test-patterns 技能（用于迁移的回归测试与版本升级测试模式）。
10. 安装使用方式
方式一（单独安装该技能）：
npx skills add hashicorp/agent-skills/plugins/terraform/skills/provider-framework-migration方式二（Claude Code 插件市场，安装整个 Terraform 产品包）：
claude plugin marketplace add hashicorp/agent-skills
claude plugin install terraform@hashicorp方式三（Codex）：将仓库的 .agents/plugins/marketplace.json 添加为仓库市场，再安装其中的 terraform 插件。
安装后无需重启；在 Terraform Provider 项目中处理 SDKv2 到 Framework 的资源迁移、搭建 Mux Provider Server，或排查迁移后出现的 plan diff / 状态错误时，技能会按 SKILL.md 描述的场景自动触发。完整的 Schema 与行为映射表在 references/schema-mapping.md 中，按需加载。
11. 注意事项
- 服务对象是 Terraform Provider 开发者（用 Go 语言维护 Provider 本体），不是普通编写
.tf文件做基础设施部署的 Terraform 使用者。 - 技能明确建议“复杂或高频使用的资源没有明确驱动力不要迁移”——它不是鼓励无脑全量迁移的工具，而是先帮你判断该不该迁，再指导怎么迁。
- 示例代码基于虚构的
examplecloudProvider，实际接入需替换为自己 Provider 的 client 类型与 Schema 字段；安装时请使用当前的plugins/terraform/skills/路径前缀，仓库已于 2026-08-10 完成一次路径结构重组。