home / skills / hashicorp / agent-skills / new-terraform-provider

new-terraform-provider skill

safe

/terraform/provider-development/skills/new-terraform-provider

This skill scaffolds a new Terraform provider project using Plugin Framework, creating workspace, initializing modules, and validating with tests.

npx playbooks add skill hashicorp/agent-skills --skill new-terraform-provider

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

896 B

---
name: new-terraform-provider
description: Use this when scaffolding a new Terraform provider.
license: MPL-2.0
metadata:
  copyright: Copyright IBM Corp. 2026
  version: "0.0.1"
---

To scaffold a new Terraform provider with Plugin Framework:

1. If I am already in a Terraform provider workspace, then confirm that I want
   to create a new workspace. If I do not want to create a new workspace, then
   skip all remaining steps.
1. Create a new workspace root directory. The root directory name should be
   prefixed with "terraform-provider-". Perform all subsequent steps in this
   new workspace.
1. Initialize a new Go module..
1. Run `go get -u github.com/hashicorp/terraform-plugin-framework@latest`.
1. Write a main.go file that follows [the example](assets/main.go).
1. Remove TODO comments from `main.go`
1. Run `go mod tidy`
1. Run `go build -o /dev/null`
1. Run `go test ./...`

Overview

This skill scaffolds a new Terraform provider using the HashiCorp Plugin Framework. It creates a clean workspace, initializes a Go module, installs the framework dependency, generates a ready-to-build main.go, and validates the build and tests. The workflow ensures a consistent starting point for provider development.

How this skill works

It interacts with your current shell workspace and, if needed, creates a new directory prefixed with "terraform-provider-". The skill runs Go module initialization, installs the plugin framework, writes a canonical main.go based on the provided example, cleans up TODOs, tidies dependencies, builds, and runs tests to verify the scaffold. If you are already in a provider workspace, it prompts to confirm creating a separate workspace and skips all steps if you decline.

When to use it

Starting development of a new Terraform provider from scratch.
Onboarding a new provider repository with the official Plugin Framework.
Creating a reproducible scaffold for contributor-friendly development.
Verifying initial build and unit test setup for a provider template.

Best practices

Always use a new directory named with the terraform-provider- prefix to follow community conventions.
Confirm workspace creation when already inside an existing provider project to avoid accidental nesting.
Remove placeholder TODOs from main.go before committing to keep the codebase clean.
Run go mod tidy and go build locally to catch dependency and compiler issues early.
Run go test ./... to validate unit tests and ensure baseline stability.

Example use cases

Quickly scaffold a provider named terraform-provider-foo to start implementing resource and data source code.
Set up a standard provider template for an organization to enforce consistent structure across providers.
Create a disposable workspace to experiment with the Plugin Framework without modifying existing repositories.
Prepare a minimal, buildable provider sample to demonstrate plugin framework usage in documentation or training.

FAQ

Will this overwrite an existing directory?

No. The skill creates a new workspace directory and prompts if you are already inside a provider workspace. It avoids overwriting existing content by requiring confirmation.

Which Go version is required?

Use a recent Go version compatible with the latest terraform-plugin-framework; check the framework's release notes, but Go 1.18+ is typically required.