provider-docs

Descripción general de la skill provider-docs

Qué hace provider-docs

La skill provider-docs te ayuda a crear, actualizar y verificar la documentación de Terraform Registry para providers de Terraform. Está pensada para autores de providers y redactores técnicos que necesitan documentación precisa a partir de descripciones de schema y plantillas tfplugindocs, no para una reescritura genérica de texto.

Para quién encaja mejor

Usa la skill provider-docs cuando estés cambiando el comportamiento de un provider y necesites que la documentación se mantenga alineada: configuración del provider, resources, data sources, ephemeral resources, list resources, functions o guías. Resulta especialmente útil en flujos de trabajo de Technical Writing donde la fuente de verdad es el código junto con la salida generada para Registry.

En qué se diferencia

Esta skill está optimizada para la estructura alineada con HashiCorp: detalles de campos guiados por schema, archivos de plantilla en el layout esperado de docs/ y publicación en Registry con criterio de release. Su valor principal es reducir la duda sobre qué se escribe en el código y qué va en las plantillas, y cómo mantener la documentación generada lista para publicar.

Cómo usar la skill provider-docs

Instala y carga los archivos correctos

Instala con npx skills add hashicorp/agent-skills --skill provider-docs. Para tener contexto inicial, lee SKILL.md, references/hashicorp-provider-docs.md y agents/openai.yaml. Si no tienes claro cómo está organizado el repositorio, inspecciona las carpetas agents/ y references/ antes de editar nada.

Convierte una tarea vaga en un prompt útil

El paso provider-docs install es solo el comienzo; la skill funciona mejor cuando tu prompt nombra los objetos exactos de Terraform y el resultado de documentación esperado. Por ejemplo: “Actualiza el uso de provider-docs para el resource foo y el data source bar después de añadir un nuevo argumento timeout; asegúrate de que las descripciones del schema y los ejemplos en docs/*.md.tmpl coincidan con la implementación.” Eso es mejor que “escribe documentación”, porque la skill puede mapear los cambios de código a destinos concretos de Registry.

Sigue un flujo de trabajo primero en el repo

Empieza por las descripciones del schema, luego actualiza los archivos de plantilla correspondientes en docs/ y después genera la documentación con tfplugindocs. Si el repositorio ya conecta la generación de esa manera, preferiblemente usa go generate ./.... Este orden importa porque las páginas generadas de Registry dependen de que el texto del schema sea preciso antes de cerrar las plantillas.

Qué revisar antes de publicar

Verifica que cada ruta de plantilla corresponda a un objeto real del 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 o docs/guides/<name>.md.tmpl. También confirma que las etiquetas de release usen semántica v y que terraform-registry-manifest.json sea válido, porque el renderizado de Registry depende de ambas cosas.

Preguntas frecuentes sobre la skill provider-docs

¿provider-docs es solo para documentación generada?

En su mayoría, sí. La skill provider-docs rinde mejor cuando la documentación se genera a partir de descripciones de schema y plantillas. Si necesitas una página de marketing puntual o un texto general que explique el producto, normalmente te conviene más un prompt estándar.

¿Necesito ser experto en Terraform?

No necesariamente, pero sí necesitas los nombres de los objetos del provider y los cambios de código que impulsan la documentación. La skill es fácil de usar para actualizaciones de documentación, siempre que puedas señalar el resource, data source o function correctos.

¿Cuándo no debería usarla?

No uses provider-docs para documentación que no esté relacionada con la salida de Terraform Registry, ni cuando la implementación del provider aún esté cambiando y el schema vaya a modificarse otra vez de inmediato. En esos casos, espera a que la interfaz se estabilice y luego genera la guía de provider-docs a partir de la forma final.

¿Cómo se compara con un prompt genérico?

Un prompt genérico puede redactar texto, pero provider-docs preserva mejor el flujo de trabajo de Registry, el layout de archivos y las restricciones de release que hacen que la documentación del provider realmente llegue a publicarse. Eso reduce retrabajo cuando pasas del borrador al output de tfplugindocs.

Cómo mejorar la skill provider-docs

Dale hechos de implementación, no solo objetivos

El mejor uso de provider-docs empieza con entradas concretas: qué objeto del provider cambió, cuál es el nuevo argumento o comportamiento, si cambiaron los defaults o los valores computed y qué ejemplo debe actualizarse. “Agrega un campo retry_count con valor predeterminado 3 y documéntalo en el resource foo” es mucho más útil que “mejora la documentación”.

Vigila el fallo más común

El mayor riesgo es escribir una prosa para la plantilla que suena correcta pero no coincide con el comportamiento del schema. Si un campo es required, optional, computed o se establece de forma condicional, dilo explícitamente en la descripción del schema y en el contexto del ejemplo. Esa alineación es lo que mantiene confiable la documentación generada.

Itera a partir de la salida generada

Después del primer intento, revisa la vista previa renderizada de Registry y compárala con el código del provider, no solo con el archivo de plantilla. Si la redacción es ambigua, ajusta primero la descripción del schema; si el ejemplo induce a error, corrige la plantilla; si falta una sección, revisa la ruta docs/ y el nombre del objeto antes de reescribir contenido.