Content
92%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured, lean skill body: an explicit 7-step workflow with validation and feedback loops, concrete commands and template paths, and proper one-level-deep reference disclosure. The only weakness is that the validation and preview steps describe what to check without giving executable commands or section pointers, keeping actionability just short of fully copy-paste ready.
Suggestions
In step 5, make validation executable: give the concrete check commands (e.g. how to validate example HCL, such as `terraform fmt -check` on examples/ or re-running tfplugindocs and diffing docs/) instead of only describing what to verify.
In step 7, link the preview and troubleshooting detail the way the templates step does — e.g. "follow the Preview and Troubleshooting section in `references/hashicorp-provider-docs.md`" — so "Use the HashiCorp preview process" has an actionable pointer.
Consider moving the Terraform v1.14.0+ compatibility note for action docs into the referenced Action Pages section to keep version-sensitive details out of the overview body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The 72-line body is pure directive guidance — no explanation of concepts Claude already knows (no "Terraform is..." padding), no fluff; every line states a rule, path, or command. The one version mention ("tfplugindocs generates action docs with Terraform v1.14.0+") is a necessary compatibility constraint, not date-conditional instruction, so it does not warrant a penalty. Not 4: there is no over-explanation left to trim. | 5 / 5 |
Actionability | Core workflow is executable and copy-paste ready: exact template paths (docs/index.md.tmpl, docs/resources/<name>.md.tmpl, etc.), `go generate ./...`, and the full `go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>` invocation. Not 5: step 5's validations are descriptive rather than executable ("Verify examples are valid HCL" names no command such as a fmt/validate check), and "Use the HashiCorp preview process" points to a process without linking the reference section that explains it. Not 3: the generation and file-layout guidance is fully concrete, not pseudocode. | 4 / 5 |
Workflow Clarity | A clearly sequenced 7-step workflow with an explicit validation step (step 5 lists three concrete checks), a feedback loop ("Re-run generation after every schema or template edit"), and a recovery path (step 7 troubleshooting with a specific diagnostic checklist: tag format, tag source branch, manifest file, publication status). Matches the anchor-5 pattern of sequence + explicit validation + error-recovery loop. | 5 / 5 |
Progressive Disclosure | The body is a lean overview that defers source-backed detail to a single, clearly signaled, one-level-deep reference (`references/hashicorp-provider-docs.md`, verified to exist with the exact sections cited: "Example File Conventions" and "Action Pages"), and instructs loading only needed sections. Not 4: structure, signaling, and file split are all appropriate with no organization gaps. | 5 / 5 |
Total | 19 / 20 Passed |