provider-docs

Visão geral da skill provider-docs

O que a provider-docs faz

A skill provider-docs ajuda você a criar, atualizar e validar documentação do Terraform Registry para providers do Terraform. Ela foi pensada para autores de providers e redatores técnicos que precisam de documentação precisa a partir de descrições de schema e templates do tfplugindocs, não para uma simples reescrita genérica de texto.

Para quem ela funciona melhor

Use a skill provider-docs quando você estiver mudando o comportamento do provider e precisar que a documentação acompanhe essas mudanças: configuração do provider, resources, data sources, ephemeral resources, list resources, functions ou guias. Ela é especialmente útil em fluxos de Technical Writing em que a fonte da verdade é o código somado à saída gerada do Registry.

O que a diferencia

Esta skill é otimizada para a estrutura alinhada ao HashiCorp: detalhes de campos dirigidos por schema, arquivos de template no layout esperado em docs/ e publicação no Registry com consciência de release. O principal valor está em reduzir a dúvida sobre o que deve ser escrito no código e o que deve ficar nos templates, além de como manter a documentação gerada pronta para publicação.

Como usar a skill provider-docs

Instale e carregue os arquivos certos

Instale com npx skills add hashicorp/agent-skills --skill provider-docs. Para obter contexto inicial, leia SKILL.md, references/hashicorp-provider-docs.md e agents/openai.yaml. Se você não tiver certeza de como o repositório está organizado, inspecione as pastas agents/ e references/ antes de editar qualquer coisa.

Transforme uma tarefa vaga em um prompt útil

A etapa provider-docs install é só o começo; a skill funciona melhor quando o prompt nomeia exatamente os objetos do Terraform e o formato de saída esperado da documentação. Por exemplo: “Atualize o uso de provider-docs para o resource foo e o data source bar depois de adicionar um novo argumento timeout; garanta que as descrições do schema e os exemplos em docs/*.md.tmpl correspondam à implementação.” Isso é melhor do que “escreva a documentação”, porque a skill consegue mapear as mudanças de código para alvos específicos do Registry.

Siga o fluxo repo-first

Comece pelas descrições do schema, depois atualize os arquivos de template correspondentes em docs/ e, por fim, gere a documentação com tfplugindocs. Prefira go generate ./... se o repositório já estiver configurado para gerar dessa forma. Essa ordem importa porque as páginas geradas do Registry dependem de um texto de schema preciso antes que os templates sejam finalizados.

O que verificar antes de publicar

Confirme que cada caminho de template corresponde a um objeto real do 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 ou docs/guides/<name>.md.tmpl. Também verifique se as tags de release usam semântica com v e se terraform-registry-manifest.json é válido, já que a renderização do Registry depende dos dois.

FAQ da skill provider-docs

A provider-docs serve só para documentação gerada?

Na maior parte, sim. A skill provider-docs brilha mesmo quando a documentação é gerada a partir de descrições de schema e templates. Se você precisa de uma página pontual de marketing ou de um texto explicativo geral do produto, um prompt normal costuma ser a melhor escolha.

Preciso ser especialista em Terraform?

Não necessariamente, mas você precisa conhecer os nomes dos objetos do provider e as mudanças no código que alimentam a documentação. A skill é amigável para iniciantes em atualizações de docs, desde que você consiga apontá-la para o resource, data source ou function certos.

Quando eu não devo usá-la?

Não use provider-docs para documentação que não tenha relação com a saída do Terraform Registry, ou quando a implementação do provider ainda estiver em fluxo e o schema for mudar de novo imediatamente. Nesses casos, espere a interface estabilizar e só então gere o guia de provider-docs a partir da forma final.

Como ela se compara a um prompt genérico?

Um prompt genérico consegue rascunhar texto, mas a provider-docs é melhor para preservar o fluxo do Registry, o layout dos arquivos e as restrições de release que fazem a documentação de provider realmente ser publicada. Isso reduz retrabalho quando você sai do rascunho e vai para a saída do tfplugindocs.

Como melhorar a skill provider-docs

Dê fatos de implementação, não só objetivos

O melhor uso de provider-docs começa com entradas concretas: qual objeto do provider mudou, qual é o novo argumento ou comportamento, se os defaults ou valores computed mudaram e qual exemplo deve ser atualizado. “Adicione um campo retry_count com default 3 e documente-o no resource foo” é muito mais útil do que “melhore a documentação”.

Fique atento ao modo de falha mais comum

O maior risco é escrever texto de template que parece correto, mas não bate com o comportamento do schema. Se um campo é required, optional, computed ou definido condicionalmente, diga isso explicitamente na descrição do schema e no contexto do exemplo. Esse alinhamento é o que mantém a documentação gerada confiável.

Itere a partir da saída gerada

Depois da primeira passada, revise a prévia renderizada do Registry e compare com o código do provider, não apenas com o arquivo de template. Se a redação estiver vaga, refine primeiro a descrição do schema; se o exemplo estiver enganoso, ajuste o template; se faltar uma seção, confira o caminho em docs/ e a nomenclatura do objeto antes de reescrever o conteúdo.