provider-docs: add action documentation guidance

terraform/provider-development/skills/provider-docs/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: provider-docs
-description: 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, or guides; when validating generated docs; and when troubleshooting missing or incorrect Registry documentation.
+description: 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.
 ---
 
 # 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, or guides.
+- 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.
 
 2. Write schema descriptions first.
@@ -24,8 +24,11 @@ description: Create, update, and review Terraform provider documentation for Ter
   - `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.
 
 4. Generate documentation with `tfplugindocs`.
 - Prefer repository defaults when configured:

terraform/provider-development/skills/provider-docs/references/hashicorp-provider-docs.md

@@ -20,8 +20,40 @@ Use these template paths when the corresponding provider objects exist:
 - `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`:
@@ -42,6 +74,53 @@ 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:
+
+  ```terraform
+  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`.