Skill

Official

Pass

Audit score 90

provider-docs

hashicorp/agent-skills

Create and validate Terraform provider documentation for Registry using tfplugindocs and HashiCorp patterns.

What is provider-docs?

Generates and maintains Terraform provider documentation for the Registry by combining schema descriptions with template files. Use this when adding or modifying provider resources, data sources, functions, guides, or validating that generated docs match implementation.

Write schema descriptions that auto-populate field documentation in Registry
Create and update template files for provider index, resources, data sources, ephemeral resources, list resources, functions, and guides
Generate markdown documentation using tfplugindocs from schema and templates
Validate generated docs against current provider implementation and HCL examples
Enforce semantic versioning and Registry publication requirements
Troubleshoot missing or incorrect documentation in Registry

How to install provider-docs

npx skills add https://github.com/hashicorp/agent-skills --skill provider-docs

Prerequisites

Terraform provider codebase with schema definitions
tfplugindocs installed or available via go run
docs/ directory structure for templates

Claude Code

Cursor

Windsurf

Cline

How to use provider-docs

1.Map your code changes to documentation targets (resources, data sources, functions, guides, etc.)
2.Write or update schema field descriptions to be precise and user-facing
3.Create or edit template files in docs/ using HashiCorp-recommended paths (docs/resources/<name>.md.tmpl, etc.)
4.Run tfplugindocs to generate markdown: go generate ./... or go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <name>
5.Validate generated markdown files match implementation, examples are valid HCL, and required/optional/computed semantics align with schema
6.Apply Registry publication rules: use semantic version tags (v1.2.3), tag from default branch, and include terraform-registry-manifest.json

Use cases

Good for

Adding a new resource or data source and generating its Registry documentation
Updating schema field descriptions to fix inaccurate or missing argument documentation
Creating provider guides and examples that appear in Registry
Validating that generated docs match the actual provider behavior before release
Troubleshooting why provider documentation is missing or outdated in Registry after publishing

Who it's for

Terraform provider developers
DevOps engineers maintaining provider documentation
Contributors adding resources or data sources to providers

provider-docs FAQ

When should I write schema descriptions vs. template files?

Write schema descriptions first for all field-level documentation (arguments, attributes, constraints, defaults). Use templates for overview, examples, and provider-level guidance. Generated sections auto-populate from schema; avoid duplicating them in templates.

How do I regenerate docs after schema changes?

Run go generate ./... if your repository has tfplugindocs configured, or run go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name> directly. Re-run after every schema or template edit.

Why is my provider documentation missing from Registry?

Check that you used semantic version tags prefixed with v (e.g., v1.2.3), tagged from the default branch, included terraform-registry-manifest.json in the repository root, and that the provider is published to Registry.

What template paths should I use?

Use HashiCorp-recommended paths: docs/index.md.tmpl for provider overview, docs/resources/<name>.md.tmpl for resources, docs/data-sources/<name>.md.tmpl for data sources, docs/ephemeral-resources/<name>.md.tmpl, docs/list-resources/<name>.md.tmpl, docs/functions/<name>.md.tmpl, and docs/guides/<name>.md.tmpl.

Should I include argument/attribute details in my templates?

No. Keep templates focused on overview and examples. Rely on tfplugindocs to generate field-by-field details from schema descriptions to avoid duplication and inconsistency.

Full instructions (SKILL.md)

Source of truth, from hashicorp/agent-skills.

name: provider-docs description: Create, update, and review Terraform provider documentation for Terraform Registry using HashiCorp-recommended patterns, tfplugindocs templates, and schema descriptions. Use when adding or changing provider configuration, resources, data sources, ephemeral resources, list resources, functions, or guides; when validating generated docs; and when troubleshooting missing or incorrect Registry documentation.

Terraform Provider Docs

Follow This Workflow

Confirm scope and documentation targets.

Map code changes to the exact doc targets: provider index, resources, data sources, ephemeral resources, list resources, functions, or guides.
Decide whether content should come from schema descriptions, templates, or both.

Write schema descriptions first.

Add precise user-facing descriptions to schema fields so generated docs stay aligned with behavior.
Keep wording specific to argument purpose, constraints, defaults, and computed behavior.

Add or update template files in docs/.

Create only files that map to implemented provider objects.
Use HashiCorp-recommended template paths:
- docs/index.md.tmpl
- docs/data-sources/<name>.md.tmpl
- docs/resources/<name>.md.tmpl
- docs/ephemeral-resources/<name>.md.tmpl
- docs/list-resources/<name>.md.tmpl
- docs/functions/<name>.md.tmpl
- docs/guides/<name>.md.tmpl
Keep templates focused on overview and examples; rely on generated sections for field-by-field details.

Generate documentation with tfplugindocs.

Prefer repository defaults when configured:

go generate ./...

Otherwise run the generator directly:

go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>

Re-run generation after every schema or template edit.

Validate the generated markdown.

Verify files in docs/ match the current provider implementation.
Verify examples are valid HCL and reflect current argument/attribute names.
Verify required/optional/computed semantics in docs match schema behavior.

Apply Registry publication rules before release.

Use semantic version tags prefixed with v (for example v1.2.3).
Create release tags from the default branch.
Keep terraform-registry-manifest.json in the repository root.
Expect docs to be versioned in Registry and switchable with the version selector.

Preview or troubleshoot publication when needed.

Use the HashiCorp preview process to inspect rendered docs before release when accuracy risk is high.
If docs are missing in Registry, check tag format, tag source branch, manifest file presence, and provider publication status.

Enforce Quality Bar

Keep documentation behaviorally accurate; never describe unsupported arguments or attributes.
Keep examples minimal, realistic, and runnable.
Keep terminology and naming consistent across provider, resources, and data sources.
Avoid duplicating generated argument/attribute blocks in manual templates.
Keep doc changes tied to the same PR as schema/API changes whenever possible.

Load References On Demand

Read references/hashicorp-provider-docs.md for source-backed rules and official links.
Load only the sections needed for the current change to keep context lean.