provider-docs

provider-docs skill の概要

provider-docs でできること

provider-docs skill は、Terraform Provider 向けの Terraform Registry ドキュメントを作成・更新・検証するための skill です。Provider の仕様を書いている著者やテクニカルライターが、schema の説明文と tfplugindocs テンプレートから正確なドキュメントを作るために設計されており、汎用的な文章リライト向けではありません。

どんな人に向いているか

Provider の挙動を変更していて、ドキュメントもそれに合わせて同期させたい場合に provider-docs skill を使います。たとえば、provider 設定、resources、data sources、ephemeral resources、list resources、functions、guides などです。コードと生成済みの Registry 出力が正本になる Technical Writing ワークフローでは、特に効果を発揮します。

何が違うのか

この skill は HashiCorp の構成に合わせて最適化されています。つまり、schema ベースの field 詳細、期待される docs/ レイアウトに置かれた template ファイル、そして release を見据えた Registry 公開です。コードに書くべき内容と template に書くべき内容を迷いにくくし、生成ドキュメントをそのまま公開可能な状態に保ちやすいのが大きな価値です。

provider-docs skill の使い方

必要なファイルをインストールして読み込む

npx skills add hashicorp/agent-skills --skill provider-docs でインストールします。最初の把握としては、SKILL.md、references/hashicorp-provider-docs.md、agents/openai.yaml を読みます。リポジトリの構成に自信がない場合は、編集を始める前に agents/ と references/ フォルダを確認してください。

漠然とした依頼を使えるプロンプトに変える

provider-docs install は出発点にすぎません。この skill は、対象の Terraform object 名と、期待するドキュメント出力をプロンプト内で具体的に指定したときに最も力を発揮します。たとえば、「新しい timeout argument を追加したので、foo resource と bar data source の provider-docs usage を更新し、schema descriptions と docs/*.md.tmpl の例が実装と一致するようにしてほしい」といった形です。「ドキュメントを書いて」よりもはるかに良いのは、コード変更を Registry の具体的な対象に結びつけられるからです。

repo 起点のワークフローに従う

まず schema descriptions を確認し、その後で docs/ 配下の対応する template ファイルを更新し、最後に tfplugindocs でドキュメントを生成します。リポジトリがその流れで生成処理を組んでいるなら、go generate ./... を優先してください。この順序が重要なのは、生成される Registry ページが、template を固める前に schema の文言が正確であることに依存しているからです。

公開前に確認すべきこと

各 template path が実在する provider object に対応しているかを確認します。対象は 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 skill の FAQ

provider-docs は生成ドキュメント専用ですか？

基本的にはそうです。provider-docs skill が最も強いのは、schema descriptions と template からドキュメントを生成する場面です。単発のマーケティングページや、一般向けの製品説明が必要なら、通常のプロンプトのほうが合っています。

Terraform の専門家である必要はありますか？

必須ではありませんが、少なくとも provider object 名と、ドキュメントを左右するコード変更は把握している必要があります。正しい resource、data source、function を指せるなら、ドキュメント更新の初心者でも使いやすい skill です。

どんなときに使わないほうがいいですか？

Terraform Registry の出力と関係ないドキュメントや、Provider 実装がまだ流動的で schema がすぐ変わる状況では使わないでください。そうした場合は、interface が安定してから、完成形に基づいて provider-docs のガイドを生成するほうが適切です。

一般的なプロンプトと比べてどう違いますか？

一般的なプロンプトでも文章の下書きはできますが、provider-docs は Registry のワークフロー、ファイル配置、release 制約を維持したまま provider ドキュメントを作れる点で優れています。そのため、下書きから tfplugindocs の出力へ移すときの手戻りが減ります。

provider-docs skill を改善するには

目的だけでなく実装情報を渡す

provider-docs をうまく使うには、具体的な入力が必要です。どの provider object が変わったのか、新しい argument や挙動は何か、default 値や computed 値が変わったか、どの example を更新すべきかを伝えてください。「retry_count field を default 3 で追加し、foo resource に記載する」のほうが、「ドキュメントを改善して」よりずっと役立ちます。

よくある失敗パターンに注意する

最大のリスクは、template の文章がそれらしく見えても schema の挙動と一致していないことです。field が required なのか optional なのか、computed なのか、条件付きで設定されるのかは、schema description と example の文脈の両方で明示してください。生成ドキュメントの信頼性は、その整合性で決まります。

生成結果を起点に反復する

最初の出力のあと、render された Registry preview を確認し、template ファイルだけでなく provider code とも照合してください。文言が曖昧なら、まず schema description を絞り込みます。example が誤解を招くなら template を調整します。セクションが足りないなら、書き直す前に docs/ の path と object 名を確認してください。