Agent skill · hashicorp
provider-framework-migration
Migrate Terraform provider resources and data sources from Plugin SDKv2 to the Plugin Framework: muxing both plugins in one provider (terraform-plugin-mux, tf5to6server), per-resource migration workflow, SDKv2-to-Framework schema mapping (ForceNew, ValidateFunc, DiffSuppressFunc, Default, Timeouts, blocks), null-vs-zero-value behavioral traps, and state-compatibility verification. Use when converting or translating SDKv2 resources to the Framework, setting up a muxed provider server, deciding whether a resource should be migrated at all, or debugging plan diffs and state errors that appeared after a migration.
What it needs
About 5k tokens when loaded.
What this skill does
Migrating from Plugin SDKv2 to the Plugin Framework The Plugin Framework is required for net-new resources and data sources; SDKv2 is maintenance-only. Migration is per-resource and incremental: a muxed provider serves SDKv2 and Framework implementations side by side, so you never need a big-bang rewrite. This skill covers the mux setup, the per-resource workflow, and the behavioral traps that turn a mechanical translation into a silent breaking change. Reference (load when needed): references/schema-mapping.md — the full SDKv2 → Framework translation table with code pairs Official guide: Framework migration. Decide Whether to Migrate at All Migration has real risk and little user-visible payoff, so triage first: Do not migrate complex or heavily-used resources without a driving need (a Framework-only feature, a bug that SDKv2 cannot fix). The two SDKs differ behaviorally — most importantly around null versus zero values — and those differences surface as breaking changes for existing users. This is the standing policy in large providers like terraform-provider-aws. Simple resources migrate safely: flat schemas, no DiffSuppressFunc, no CustomizeDiff, no StateFunc, no complex nested blocks. New capabilities never require migrating old code — mux and write the new resource in the Framework alongside the old ones. To tell what mode a provider is in, check go.mod: terraform-plugin-mux present means it already serves both; only terraform-plugin-sdk/v2 means SDKv2-only (mux setup is your first step); only terraform-plugin-framework means the migration is done. Step 1: Mux the Provider Combine both plugin servers in main.go. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills hashicorp/provider-framework-migration