AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

provider-docs

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, actions, or guides; when validating generated docs; and when troubleshooting missing or incorrect Registry documentation.

Original source
hashicorp
License
MPL-2.0
Pinned revision
bc6b14b77481c3cbfbb06a0166be7245ed45798c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read hashicorp--provider-docs at revision bc6b14b77481c3cbfbb06a0166be7245ed45798c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 2

references/hashicorp-provider-docs.md

HashiCorp Provider Documentation Reference

Source of truth for this skill:

  • https://developer.hashicorp.com/terraform/registry/providers/docs

Core Rules

  • Publish provider docs through Terraform Registry using tfplugindocs.
  • Generate provider docs from schema descriptions and markdown templates.
  • Store templates under the repository docs/ directory with expected naming conventions.
  • Keep release tags and manifest metadata valid so Registry can render and display docs.

Template Paths

Use these template paths when the corresponding provider objects exist:

  • 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/actions/<name>.md.tmpl
  • docs/guides/<name>.md.tmpl

The Registry renders action pages from docs/actions/<action>.md, and tfplugindocs generates action documentation (including missing template scaffolds) with Terraform v1.14.0+. Action example files follow the convention examples/actions/<action_type>/action*.tf.

Example File Conventions

Keep example HCL in the examples/ directory and pull it into templates, instead of inlining HCL in .tmpl files:

examples/
├── provider/provider.tf                      # provider block for the index page only
├── resources/<type>/resource.tf              # picked up by generated templates
├── data-sources/<type>/data-source.tf
└── actions/<type>/action.tf
  • One example per file, referenced from templates with {{ tffile "examples/resources/examplecloud_widget/resource.tf" }} — named variants get their own files (resource-with-tags.tf), each behind its own heading in the template.
  • No terraform, provider, or output blocks in resource, data source, or action examples. Version constraints and provider configuration belong on the provider index page only; outputs distract from the object being documented. (The one exception is examples/provider/provider.tf, which exists to show provider configuration.)
  • Keep each example minimal, runnable, and formatted with terraform fmt — generated docs render the file verbatim.

Generation Workflow

HashiCorp recommends wiring generator execution through go generate:

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

Run from repository root:

go generate ./...

Alternative direct execution:

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

Action Pages

Structure modeled on the largest production example, terraform-provider-aws (website/docs/actions/ — hand-written there because that provider predates tfplugindocs action support; new providers should generate instead):

  • One page per action. H1 uses an Action: prefix — # Action: examplecloud_restart_widget — parallel to # Resource: / # Data Source: on sibling pages.

  • Intro paragraph states what the action does and whether it is synchronous or asynchronous, then links to the upstream service documentation for the operation it invokes.

  • ## Example Usage starts with ### Basic Usage and must show both halves of using an action: the action block and the resource-side lifecycle { action_trigger { ... } } wiring — an action example without a trigger is not runnable:

    action "examplecloud_restart_widget" "example" {
      config {
        widget_id = examplecloud_widget.example.id
      }
    }
    
    resource "terraform_data" "trigger" {
      lifecycle {
        action_trigger {
          events  = [after_create, after_update]
          actions = [action.examplecloud_restart_widget.example]
        }
      }
    }
    
  • ## Argument Reference lists config arguments (either flat, or split into required/optional groups). No attribute/output reference section — actions produce no state, and including one misleads readers.

  • Callout conventions (while actions remain experimental):

    • ~> **Note:** for the preview disclaimer, e.g. "<action> is in alpha. Its interface and behavior may change as the feature evolves, and breaking changes are possible."
    • !> **Warning:** when the action causes changes Terraform does not reconcile (e.g. it mutates a resource whose state attributes will be stale until the next refresh) — name the affected attribute and the consequence.
  • If the repo tracks release notes with go-changelog, new actions use the release-note:new-action entry type.

Release and Publication Constraints

  • Use semantic version tags prefixed with v.
  • Create tags from the default branch.
  • Keep terraform-registry-manifest.json in the repository root.
  • Understand docs appear by provider version in Registry once the provider release is published.

Preview and Troubleshooting

  • Use HashiCorp's preview process to verify rendering before release when needed.
  • If docs are missing or stale in Registry, verify:
    • tag naming and tag branch source
    • manifest file presence and validity
    • provider version publication state

Related Canonical Pages

  • Provider docs guidance:
    • https://developer.hashicorp.com/terraform/registry/providers/docs
  • Terraform Plugin Docs (tfplugindocs) source and usage:
    • https://github.com/hashicorp/terraform-plugin-docs