provider-docs
by hashicorpThe provider-docs skill helps you create, update, and verify Terraform Registry documentation for Terraform providers. Use it for provider-docs guide work, provider-docs for Technical Writing, and for keeping schema descriptions, tfplugindocs templates, and Registry output in sync when docs change.
This skill scores 84/100, which means it is a solid directory listing candidate for users who need Terraform provider documentation workflows. The repository gives enough operational detail to help an agent trigger the skill correctly, follow a HashiCorp-aligned process, and produce Registry-ready docs with less guesswork than a generic prompt.
- Strong triggerability: the description explicitly covers creating, updating, reviewing, and troubleshooting Terraform Registry provider docs for specific object types.
- Good operational clarity: the workflow names schema descriptions, `docs/` template locations, and `tfplugindocs` generation steps, plus a reference file with HashiCorp rules.
- Useful install decision value: the skill targets a real provider-docs workflow rather than a placeholder, with a companion `openai.yaml` prompt and source-of-truth reference.
- Workflow detail is useful but not exhaustive; the excerpted workflow truncates before some generation/troubleshooting guidance, so agents may still need repository context.
- No install command is included in `SKILL.md`, so adoption may require users to infer how to wire the skill into their environment.
Overview of provider-docs skill
What provider-docs does
The provider-docs skill helps you create, update, and verify Terraform Registry documentation for Terraform providers. It is built for provider authors and technical writers who need accurate docs from schema descriptions and tfplugindocs templates, not a generic prose rewrite.
Who it fits best
Use the provider-docs skill when you are changing provider behavior and need the docs to stay in sync: provider configuration, resources, data sources, ephemeral resources, list resources, functions, or guides. It is especially useful for Technical Writing workflows where the source of truth is code plus generated Registry output.
Why it is different
This skill is optimized for HashiCorp-aligned structure: schema-driven field details, template files in the expected docs/ layout, and release-aware Registry publication. The main value is reducing guesswork about what should be written in code versus templates, and how to keep generated docs publishable.
How to Use provider-docs skill
Install and load the right files
Install with npx skills add hashicorp/agent-skills --skill provider-docs. For first-pass context, read SKILL.md, references/hashicorp-provider-docs.md, and agents/openai.yaml. If you are unsure how the repository is organized, inspect the agents/ and references/ folders before editing anything.
Turn a rough task into a usable prompt
The provider-docs install step is only the start; the skill works best when your prompt names the exact Terraform objects and the expected doc output. For example: “Update provider-docs usage for the foo resource and bar data source after adding a new timeout argument; ensure the schema descriptions and docs/*.md.tmpl examples match the implementation.” That is better than “write docs,” because the skill can map code changes to specific Registry targets.
Follow the repo-first workflow
Start with schema descriptions, then update the matching template files under docs/, then generate docs with tfplugindocs. Prefer go generate ./... if the repository wires generation that way. This order matters because the generated Registry pages depend on the schema text being precise before the templates are finalized.
What to check before you publish
Verify that each template path matches a real provider object: docs/index.md.tmpl, docs/resources/<name>.md.tmpl, docs/data-sources/<name>.md.tmpl, docs/ephemeral-resources/<name>.md.tmpl, docs/list-resources/<name>.md.tmpl, docs/functions/<name>.md.tmpl, or docs/guides/<name>.md.tmpl. Also confirm release tags use v semantics and that terraform-registry-manifest.json is valid, since Registry rendering depends on both.
provider-docs skill FAQ
Is provider-docs only for generated docs?
Mostly yes. The provider-docs skill is strongest when docs are generated from schema descriptions and templates. If you need a one-off marketing page or a general product explainer, a normal prompt is usually a better fit.
Do I need to be a Terraform expert?
Not necessarily, but you do need the provider object names and the code changes that drive documentation. The skill is beginner-friendly for doc updates, as long as you can point it at the right resource, data source, or function.
When should I not use it?
Do not use provider-docs for docs that are unrelated to Terraform Registry output, or when the provider implementation is still in flux and the schema will change again immediately. In those cases, wait until the interface stabilizes, then generate the provider-docs guide from the final shape.
How does it compare with a generic prompt?
A generic prompt can draft text, but provider-docs is better at preserving the Registry workflow, file layout, and release constraints that make provider documentation actually ship. That reduces rework when you move from draft text to tfplugindocs output.
How to Improve provider-docs skill
Give it implementation facts, not just goals
The best provider-docs usage starts with concrete inputs: which provider object changed, what the new argument or behavior is, whether defaults or computed values changed, and which example should be updated. “Add a retry_count field with default 3 and document it in the foo resource” is far more useful than “improve docs.”
Watch for the common failure mode
The biggest risk is writing template prose that sounds right but does not match schema behavior. If a field is required, optional, computed, or conditionally set, say so explicitly in the schema description and in the example context. That alignment is what keeps generated docs trustworthy.
Iterate from generated output
After the first pass, review the rendered Registry preview and compare it to the provider code, not just the template file. If wording is vague, tighten the schema description first; if the example is misleading, adjust the template; if a section is missing, check the docs/ path and object naming before rewriting content.