provider-docs

Name: provider-docs
Author: hashicorp

750stars110forks

How to install provider-docs?

hashicorp/agent-skills/provider-docs

$npx -y skills add hashicorp/agent-skills --skill provider-docs

Installs into the current project.

Summary

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 resourc

Files · 1

View on GitHub

SKILL.md

1	# Terraform Provider Docs
2
3	## Follow This Workflow
4
5	1. Confirm scope and documentation targets.
6	- Map code changes to the exact doc targets: provider index, resources, data sources, ephemeral resources, list resources, functions, or guides.
7	- Decide whether content should come from schema descriptions, templates, or both.
8
9	2. Write schema descriptions first.
10	- Add precise user-facing descriptions to schema fields so generated docs stay aligned with behavior.
11	- Keep wording specific to argument purpose, constraints, defaults, and computed behavior.
12
13	3. Add or update template files in `docs/`.
14	- Create only files that map to implemented provider objects.
15	- Use HashiCorp-recommended template paths:
16	- `docs/index.md.tmpl`
17	- `docs/data-sources/<name>.md.tmpl`
18	- `docs/resources/<name>.md.tmpl`
19	- `docs/ephemeral-resources/<name>.md.tmpl`
20	- `docs/list-resources/<name>.md.tmpl`
21	- `docs/functions/<name>.md.tmpl`
22	- `docs/guides/<name>.md.tmpl`
23	- Keep templates focused on overview and examples; rely on generated sections for field-by-field details.
24
25	4. Generate documentation with `tfplugindocs`.
26	- Prefer repository defaults when configured:
27	```bash
28	go generate ./...
29	```
30	- Otherwise run the generator directly:
31	```bash
32	go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>
33	```
34	- Re-run generation after every schema or template edit.
35
36	5. Validate the generated markdown.
37	- Verify files in `docs/` match the current provider implementation.
38	- Verify examples are valid HCL and reflect current argument/attribute names.
39	- Verify required/optional/computed semantics in docs match schema behavior.
40
41	6. Apply Registry publication rules before release.
42	- Use semantic version tags prefixed with `v` (for example `v1.2.3`).
43	- Create release tags from the default branch.
44	- Keep `terraform-registry-manifest.json` in the repository root.
45	- Expect docs to be versioned in Registry and switchable with the version selector.
46
47	7. Preview or troubleshoot publication when needed.
48	- Use the HashiCorp preview process to inspect rendered docs before release when accuracy risk is high.
49	- If docs are missing in Registry, check tag format, tag source branch, manifest file presence, and provider publication status.
50
51	## Enforce Quality Bar
52
53	- Keep documentation behaviorally accurate; never describe unsupported arguments or attributes.
54	- Keep examples minimal, realistic, and runnable.
55	- Keep terminology and naming consistent across provider, resources, and data sources.
56	- Avoid duplicating generated argument/attribute blocks in manual templates.
57	- Keep doc changes tied to the same PR as schema/API changes whenever possible.
58
59	## Load References On Demand
60
61	- Read `references/hashicorp-provider-docs.md` for source-backed rules and official links.
62	- Load only the sections needed for the current change to keep context lean.

People who liked this also viewed

6 picks

Type

provider-docs

750stars110forks

View on GitHub

How to install provider-docs?

hashicorp/agent-skills/provider-docs

$npx -y skills add hashicorp/agent-skills --skill provider-docs

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Terraform Provider Docs
2
3	## Follow This Workflow
4
5	1. Confirm scope and documentation targets.
6	- Map code changes to the exact doc targets: provider index, resources, data sources, ephemeral resources, list resources, functions, or guides.
7	- Decide whether content should come from schema descriptions, templates, or both.
8
9	2. Write schema descriptions first.
10	- Add precise user-facing descriptions to schema fields so generated docs stay aligned with behavior.
11	- Keep wording specific to argument purpose, constraints, defaults, and computed behavior.
12
13	3. Add or update template files in `docs/`.
14	- Create only files that map to implemented provider objects.
15	- Use HashiCorp-recommended template paths:
16	- `docs/index.md.tmpl`
17	- `docs/data-sources/<name>.md.tmpl`
18	- `docs/resources/<name>.md.tmpl`
19	- `docs/ephemeral-resources/<name>.md.tmpl`
20	- `docs/list-resources/<name>.md.tmpl`
21	- `docs/functions/<name>.md.tmpl`
22	- `docs/guides/<name>.md.tmpl`
23	- Keep templates focused on overview and examples; rely on generated sections for field-by-field details.
24
25	4. Generate documentation with `tfplugindocs`.
26	- Prefer repository defaults when configured:
27	```bash
28	go generate ./...
29	```
30	- Otherwise run the generator directly:
31	```bash
32	go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>
33	```
34	- Re-run generation after every schema or template edit.
35
36	5. Validate the generated markdown.
37	- Verify files in `docs/` match the current provider implementation.
38	- Verify examples are valid HCL and reflect current argument/attribute names.
39	- Verify required/optional/computed semantics in docs match schema behavior.
40
41	6. Apply Registry publication rules before release.
42	- Use semantic version tags prefixed with `v` (for example `v1.2.3`).
43	- Create release tags from the default branch.
44	- Keep `terraform-registry-manifest.json` in the repository root.
45	- Expect docs to be versioned in Registry and switchable with the version selector.
46
47	7. Preview or troubleshoot publication when needed.
48	- Use the HashiCorp preview process to inspect rendered docs before release when accuracy risk is high.
49	- If docs are missing in Registry, check tag format, tag source branch, manifest file presence, and provider publication status.
50
51	## Enforce Quality Bar
52
53	- Keep documentation behaviorally accurate; never describe unsupported arguments or attributes.
54	- Keep examples minimal, realistic, and runnable.
55	- Keep terminology and naming consistent across provider, resources, and data sources.
56	- Avoid duplicating generated argument/attribute blocks in manual templates.
57	- Keep doc changes tied to the same PR as schema/API changes whenever possible.
58
59	## Load References On Demand
60
61	- Read `references/hashicorp-provider-docs.md` for source-backed rules and official links.
62	- Load only the sections needed for the current change to keep context lean.

People who liked this also viewed

6 picks

Type