skilld
All skills
hashicorp avatar

/provider-docs

@4451cec official
by hashicorphashicorp/agent-skills880 stars
130

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.

Ask your Agent

Use this Skill: https://skilld.dev/gh/hashicorp/agent-skills/provider-docs

This session only. Nothing lands on disk.

SKILL.md

≈108 tokens always: the name and description. ≈882 when used: this file. ≈1.5k more on demand in 2 files.

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.

Source: SKILL.md on GitHub

Third-party checks

No alerts16d4 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    This skill facilitates the creation and maintenance of Terraform provider documentation using official tools and recommended workflows. It includes security considerations such as the execution of a remote documentation generator, which is a standard and expected part of the provider development process.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 4451cec. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 2 months ago

Capability

metadata
{
  "lifecycle-status": "active"
}

Topics

  • Documentation
  • terraform
  • provider
  • registry
  • tfplugindocs
  • schema
  • hashicorp
  • hcl

README badge

README badge for hashicorp/agent-skills/provider-docs

What it does

Generates and validates Terraform provider documentation for the Terraform Registry using tfplugindocs, schema descriptions, and HashiCorp-recommended template patterns. Use this skill when creating or updating provider resources, data sources, ephemeral resources, functions, guides, or validating generated docs against schema behavior.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with Terraform providers that don't use tfplugindocs?
No. The skill is built around tfplugindocs templates and the HashiCorp-recommended documentation workflow. Providers using other doc generation tools are not supported.
Can I use this skill to document custom Terraform modules?
No. This skill is specific to Terraform provider documentation for the Terraform Registry. It does not cover module documentation.
Does this skill validate HCL examples in the documentation?
The skill includes a validation step to verify examples are valid HCL and reflect current argument/attribute names, but does not execute or test the examples.
What happens if I skip writing schema descriptions?
Generated docs will lack field-by-field details since tfplugindocs pulls descriptions from the schema. The skill recommends writing schema descriptions first to keep documentation aligned with actual provider behavior.
Does this skill handle provider releases to the Registry?
No. The skill prepares and validates documentation but does not automate Registry publication. You must create semantic version tags and ensure the manifest file is present in the repository root.

Generated from the current SKILL.md. These answers refresh after source changes.