provider-docs

Überblick über den Skill provider-docs

Was provider-docs macht

Der provider-docs-Skill hilft Ihnen dabei, Terraform-Registry-Dokumentation für Terraform-Provider zu erstellen, zu aktualisieren und zu prüfen. Er ist für Provider-Autor:innen und Technical Writer gedacht, die präzise Doku aus Schema-Beschreibungen und tfplugindocs-Templates benötigen – nicht für eine generische Umformulierung von Text.

Für wen der Skill am besten geeignet ist

Nutzen Sie den provider-docs-Skill, wenn Sie das Verhalten eines Providers ändern und die Dokumentation synchron halten müssen: Provider-Konfiguration, Ressourcen, Data Sources, ephemeral resources, list resources, Funktionen oder Guides. Besonders nützlich ist er für Technical-Writing-Workflows, bei denen die Codebasis plus generierte Registry-Ausgabe die einzige verlässliche Quelle sind.

Worin sich der Skill unterscheidet

Dieser Skill ist auf eine HashiCorp-konforme Struktur optimiert: feldgenaue Schema-Details, Template-Dateien im erwarteten docs/-Layout und Registry-Publishing mit Blick auf Releases. Der Hauptnutzen liegt darin, Unsicherheiten darüber zu reduzieren, was im Code und was in Templates stehen sollte, und wie sich generierte Doku veröffentlichen lässt.

So verwenden Sie den Skill provider-docs

Die richtigen Dateien installieren und laden

Installieren Sie mit npx skills add hashicorp/agent-skills --skill provider-docs. Lesen Sie für den ersten Kontextdurchgang SKILL.md, references/hashicorp-provider-docs.md und agents/openai.yaml. Wenn Sie nicht sicher sind, wie das Repository aufgebaut ist, schauen Sie sich vor jeder Änderung die Ordner agents/ und references/ an.

Eine grobe Aufgabe in einen brauchbaren Prompt übersetzen

Der Schritt provider-docs install ist nur der Anfang; am besten funktioniert der Skill, wenn Ihr Prompt die konkreten Terraform-Objekte und das erwartete Doku-Format nennt. Zum Beispiel: “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.” Das ist besser als “write docs”, weil der Skill Codeänderungen auf konkrete Registry-Ziele abbilden kann.

Dem Repo-first-Workflow folgen

Beginnen Sie mit den Schema-Beschreibungen, aktualisieren Sie dann die passenden Template-Dateien unter docs/, und erzeugen Sie anschließend die Doku mit tfplugindocs. Bevorzugen Sie go generate ./..., wenn das Repository die Generierung so verdrahtet. Diese Reihenfolge ist wichtig, weil die generierten Registry-Seiten davon abhängen, dass der Schema-Text präzise ist, bevor die Templates finalisiert werden.

Was Sie vor dem Veröffentlichen prüfen sollten

Prüfen Sie, ob jeder Template-Pfad zu einem realen Provider-Objekt passt: 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 oder docs/guides/<name>.md.tmpl. Stellen Sie außerdem sicher, dass Release-Tags v-Semantik verwenden und dass terraform-registry-manifest.json gültig ist, da das Registry-Rendering von beidem abhängt.

FAQ zum Skill provider-docs

Ist provider-docs nur für generierte Doku?

Weitgehend ja. Der provider-docs-Skill ist am stärksten, wenn Doku aus Schema-Beschreibungen und Templates generiert wird. Wenn Sie eine einmalige Marketing-Seite oder eine allgemeine Produkterklärung brauchen, ist ein normaler Prompt meist besser geeignet.

Muss ich Terraform-Expert:in sein?

Nicht unbedingt, aber Sie brauchen die Namen der Provider-Objekte und die Codeänderungen, die die Dokumentation antreiben. Der Skill ist für Doku-Updates einsteigerfreundlich, solange Sie ihn auf die richtige Resource, Data Source oder Funktion verweisen können.

Wann sollte ich ihn nicht verwenden?

Verwenden Sie provider-docs nicht für Doku, die nichts mit der Terraform-Registry-Ausgabe zu tun hat, oder wenn die Provider-Implementierung noch in Bewegung ist und sich das Schema sofort wieder ändern wird. Warten Sie in solchen Fällen, bis die Schnittstelle stabil ist, und erzeugen Sie dann den provider-docs-Leitfaden aus der finalen Form.

Wie unterscheidet er sich von einem generischen Prompt?

Ein generischer Prompt kann Text entwerfen, aber provider-docs ist besser darin, den Registry-Workflow, das Dateilayout und die Release-Restriktionen zu erhalten, die dafür sorgen, dass Provider-Dokumentation tatsächlich ausgeliefert werden kann. Das reduziert Nacharbeit, wenn Sie von einem Entwurf zu tfplugindocs-Output wechseln.

So verbessern Sie den Skill provider-docs

Geben Sie ihm Implementierungsdetails, nicht nur Ziele

Die beste Nutzung von provider-docs beginnt mit konkreten Eingaben: welches Provider-Objekt sich geändert hat, was das neue Argument oder Verhalten ist, ob sich Defaults oder berechnete Werte geändert haben und welches Beispiel aktualisiert werden soll. “Add a retry_count field with default 3 and document it in the foo resource” ist deutlich hilfreicher als “improve docs.”

Achten Sie auf den häufigsten Fehler

Das größte Risiko besteht darin, Template-Texte zu schreiben, die plausibel klingen, aber nicht zum Schema-Verhalten passen. Wenn ein Feld required, optional, computed oder bedingt gesetzt ist, nennen Sie das ausdrücklich in der Schema-Beschreibung und im Beispielkontext. Diese Abstimmung ist entscheidend dafür, dass generierte Doku vertrauenswürdig bleibt.

Iterieren Sie vom generierten Output aus

Prüfen Sie nach dem ersten Durchlauf die gerenderte Registry-Vorschau und vergleichen Sie sie mit dem Provider-Code, nicht nur mit der Template-Datei. Wenn die Formulierung zu vage ist, schärfen Sie zuerst die Schema-Beschreibung; wenn das Beispiel irreführend ist, passen Sie das Template an; wenn ein Abschnitt fehlt, prüfen Sie den docs/-Pfad und die Objektbenennung, bevor Sie Inhalte neu schreiben.