provider-docs

provider-docs 技能概覽

provider-docs 的用途

provider-docs 技能可協助你建立、更新並驗證 Terraform Provider 的 Terraform Registry 文件。它是為 provider 作者與技術寫作者設計的，重點是從 schema 描述與 tfplugindocs 範本產出準確文件，而不是做一般性的文案改寫。

最適合哪些情境

當你在調整 provider 行為，且文件也必須同步更新時，最適合使用 provider-docs 技能：provider 設定、resources、data sources、ephemeral resources、list resources、functions，或各類 guides 都包含在內。若你的工作流程是以程式碼與生成後的 Registry 輸出作為真實來源，這個技能對 Technical Writing 工作特別有用。

這個技能有什麼不同

這個技能是依照 HashiCorp 的結構來最佳化的：以 schema 驅動欄位細節、符合預期 docs/ 版型的 template 檔，以及考量發版節奏的 Registry 發佈流程。它的主要價值，在於減少你對「哪些內容應該寫在程式碼裡、哪些應該放在範本裡」的猜測，並讓生成後的文件更容易直接上線。

如何使用 provider-docs 技能

安裝並載入正確檔案

使用 npx skills add hashicorp/agent-skills --skill provider-docs 安裝。第一次取得背景脈絡時，請閱讀 SKILL.md、references/hashicorp-provider-docs.md 與 agents/openai.yaml。如果你不確定這個 repository 的結構，先查看 agents/ 和 references/ 資料夾，再開始修改任何內容。

把粗略任務轉成可執行的提示

provider-docs install 只是起點；這個技能最有效的用法，是在提示中明確寫出 Terraform 物件名稱與預期的文件輸出。例如：“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.” 這會比單純說 “write docs” 好得多，因為這個技能才能把程式碼變更對應到具體的 Registry 目標。

依照 repo 優先的工作流程進行

先從 schema 描述下手，再更新 docs/ 底下對應的 template 檔，最後用 tfplugindocs 產生文件。若這個 repository 本來就是用 go generate ./... 串接產生流程，優先採用那種方式。這個順序很重要，因為生成後的 Registry 頁面，取決於 schema 文字是否先寫得精準，再完成範本。

發佈前要先檢查什麼

確認每個 template 路徑都對應到真實的 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 tag 使用 v 的命名慣例，且 terraform-registry-manifest.json 是有效的，因為 Registry 的渲染同時依賴這兩者。

provider-docs 技能 FAQ

provider-docs 只適合生成文件嗎？

大致上是。provider-docs 技能最強的地方，就是把文件從 schema 描述與範本生成出來。如果你需要的是一次性的行銷頁或一般產品說明，通常用一般提示會更合適。

我一定要很懂 Terraform 嗎？

不一定，但你需要知道 provider 物件名稱，以及驅動文件變更的程式碼內容。只要你能把它對準正確的 resource、data source 或 function，這個技能對文件更新來說其實很容易上手。

什麼情況下不該用？

不要把 provider-docs 用在與 Terraform Registry 輸出無關的文件，或是 provider 實作還在大幅變動、schema 很快又會改的時候。這種情況下，先等介面穩定，再根據最終形態產出 provider-docs 指南。

跟一般提示相比差在哪裡？

一般提示可以草擬文字，但 provider-docs 更擅長保留真正決定 provider 文件能否順利發佈的 Registry 工作流程、檔案結構與發版限制。這能在你從草稿文字轉到 tfplugindocs 輸出時，減少返工。

如何改進 provider-docs 技能

提供實作事實，不要只給目標

最好的 provider-docs 用法，從具體輸入開始：哪個 provider 物件變了、new argument 或行為是什麼、預設值或 computed value 是否有變、哪個範例需要更新。“Add a 'retry_count' field with default 3 and document it in the 'foo' resource” 會比 “improve docs” 有用得多。

注意最常見的失敗模式

最大風險是把範本寫得很順，但與 schema 行為不符。如果某個欄位是 required、optional、computed，或只有在特定條件下才會被設定，請務必在 schema 描述與範例情境中明確寫出來。這種對齊，正是讓生成文件可信的關鍵。

從生成後的輸出持續迭代

第一次產出後，請檢視渲染後的 Registry 預覽，並對照 provider 程式碼，而不只是 template 檔。如果措辭太模糊，先把 schema 描述寫清楚；如果範例有誤導性，就調整 template；如果某個區塊不見了，先檢查 docs/ 路徑與物件命名，再回頭改內容。