provider-docs

provider-docs 技能概览

provider-docs 是做什么的

provider-docs 技能帮助你为 Terraform providers 创建、更新并校验 Terraform Registry 文档。它面向 provider 作者和技术写作者，目标是根据 schema 描述和 tfplugindocs 模板产出准确文档，而不是把一段通用文本简单改写一遍。

最适合谁使用

当你在修改 provider 行为，并且需要文档保持同步时，使用 provider-docs 技能：包括 provider 配置、resources、data sources、ephemeral resources、list resources、functions 或 guides。它尤其适合 Technical Writing 工作流——也就是把代码和生成出来的 Registry 输出当作唯一事实来源。

它的不同之处

这个技能针对 HashiCorp 风格的结构做了优化：基于 schema 的字段说明、位于预期 docs/ 目录布局中的模板文件，以及考虑发布节奏的 Registry 发布流程。它的核心价值，在于减少“哪些内容应该写进代码、哪些内容应该放进模板”的猜测成本，并帮助你把生成文档维持在可发布状态。

如何使用 provider-docs 技能

安装并加载正确的文件

使用 npx skills add hashicorp/agent-skills --skill provider-docs 安装。获取第一轮上下文时，请阅读 SKILL.md、references/hashicorp-provider-docs.md 和 agents/openai.yaml。如果你不确定仓库结构，先查看 agents/ 和 references/ 文件夹，再开始修改任何内容。

把模糊任务转成可执行提示词

provider-docs install 只是起点；这个技能真正发挥作用时，提示词需要明确指出具体的 Terraform 对象以及预期的文档输出。比如：“在新增 timeout 参数后，更新 foo resource 和 bar data source 的 provider-docs 用法说明；确保 schema 描述和 docs/*.md.tmpl 示例与实现一致。”这比“写文档”更有效，因为技能可以把代码变更映射到具体的 Registry 目标。

按照 repo 优先的工作流推进

先更新 schema descriptions，再修改 docs/ 下对应的模板文件，最后使用 tfplugindocs 生成文档。如果仓库已经把生成流程接到了别处，优先使用 go generate ./...。这个顺序很重要，因为生成出来的 Registry 页面依赖于 schema 文本先足够准确，然后模板才能定稿。

发布前需要检查什么

确认每个模板路径都对应真实的 provider 对象：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 或 docs/guides/<name>.md.tmpl。同时确认 release tags 使用 v 语义，并且 terraform-registry-manifest.json 是有效的，因为 Registry 渲染依赖这两者同时正确。

provider-docs 技能 FAQ

provider-docs 只适合生成式文档吗？

大体上是的。provider-docs 技能在基于 schema descriptions 和模板生成文档时最强。如果你需要的是一次性的营销页面，或者通用的产品说明页，普通提示词通常更合适。

我需要是 Terraform 专家吗？

不一定，但你需要知道 provider 对象名称，以及驱动文档变化的代码修改。只要你能把它指向正确的 resource、data source 或 function，这个技能对文档更新来说就很友好。

什么时候不该用它？

如果文档与 Terraform Registry 输出无关，就不要使用 provider-docs；如果 provider 实现还在快速变化、schema 很快还会再改，也不建议用。此时应等接口稳定后，再基于最终形态生成 provider-docs 指南。

它和通用提示词相比有什么区别？

通用提示词可以起草文本，但 provider-docs 更擅长保留 Registry 的工作流、文件布局和发布约束，而这些正是 provider 文档能否真正上线的关键。这样从草稿文本切换到 tfplugindocs 输出时，需要返工的地方会更少。

如何改进 provider-docs 技能

给它实现事实，而不只是目标

最好的 provider-docs 用法，是一开始就提供具体输入：哪个 provider 对象变了、新增了什么参数或行为、默认值或 computed values 是否变化、以及该更新哪个示例。比起“改进文档”，“为 foo resource 增加 retry_count 字段，默认值为 3，并在文档中说明”要有价值得多。

留意最常见的失败模式

最大风险是写出看起来正确、但与 schema 行为不一致的模板文案。如果某个字段是 required、optional、computed，或者是条件性设置的，就必须在 schema description 和示例上下文里明确写出来。只有这种对齐，才能让生成文档保持可信。

从生成结果开始迭代

第一轮生成后，先查看渲染出来的 Registry 预览，再对照 provider 代码，而不只是对照模板文件。如果措辞含糊，先收紧 schema description；如果示例会误导人，调整模板；如果某个 section 缺失，先检查 docs/ 路径和对象命名，再去重写内容。