mcpField
P
provider-docs

provider-docs

github.com/hashicorpDevelopment9093.2k installsUpdated today
Repository

About provider-docs

A workflow guide for documenting Terraform providers using schema descriptions, templates, and tfplugindocs. It helps maintain accurate generated docs, examples, validation, and Registry publication readiness.

Key features

  1. 01Map code changes to documentation targets
  2. 02Write schema descriptions and templates
  3. 03Generate docs with tfplugindocs
  4. 04Validate generated Markdown and HCL examples
  5. 05Check Registry publication requirements

Use cases

  1. 01Documenting a provider resource or data source
  2. 02Updating docs after schema changes
  3. 03Preparing provider documentation for Registry publication

Install

Copy the command and run it in a terminal.

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

After installing, type/provider-docsin Claude Code to confirm it loaded.

Bundled filesagents/openai.yamlreferences/hashicorp-provider-docs.md

Details

From the project README

Terraform Provider Docs

Follow This Workflow

  1. Confirm scope and documentation targets.
  • Map code changes to the exact doc targets: provider index, resources, data sources, ephemeral resources, list resources, functions, actions, or guides.
  • Decide whether content should come from schema descriptions, templates, or both.
  1. 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.
  1. 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/actions/<name>.md.tmpl (tfplugindocs generates action docs with Terraform v1.14.0+)
    • docs/guides/<name>.md.tmpl
  • Keep templates focused on overview and examples; rely on generated sections for field-by-field details.
  • Keep HCL examples in the examples/ directory — one example per file, pulled into templates with tffile — rather than inlined in templates (see Example File Conventions in references/hashicorp-provider-docs.md). Examples must not contain terraform, provider, or output blocks.
  • For action pages, follow the structure in references/hashicorp-provider-docs.md (Action Pages section): examples must show both the action block and the action_trigger lifecycle wiring, and actions get no attribute/output section.
  1. 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.
  1. 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.
  1. 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.
  1. 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.

Comments

Markdown supported