provider-actions

Visão geral da skill provider-actions

Para que serve o provider-actions

A skill provider-actions ajuda você a implementar actions de Terraform Provider com o Plugin Framework. Ela é voltada a autores de provider que precisam de comportamento imperativo em eventos de ciclo de vida, como antes ou depois de create, update ou destroy. Se você está decidindo se vale instalar provider-actions, a pergunta central é: o seu provider precisa de um fluxo em estilo action, em vez de um fluxo CRUD tradicional de resource?

Quem deve usar esta skill

Use a skill provider-actions para trabalho de Backend Development em um Terraform provider quando você já entende o comportamento do serviço de destino e precisa de um padrão confiável para encaixá-lo no código do provider. Ela é mais útil quando você quer menos tentativa e erro com layout de arquivos, formato de schema e testes, e mais orientação sobre onde o código da action deve ficar na árvore do provider.

Por que ela é diferente

Esta skill não é só mais uma orientação genérica de Terraform. Ela foca no ciclo de vida de actions, na estrutura padrão de pacotes de serviço, no posicionamento da documentação de actions e em problemas comuns de schema. Isso torna provider-actions mais útil para decisão do que um prompt amplo quando você precisa entregar uma funcionalidade de provider que siga as convenções da HashiCorp e possa ser revisada pelos maintainers.

Como usar a skill provider-actions

Instale a skill provider-actions

Instale provider-actions com npx skills add hashicorp/agent-skills --skill provider-actions. Depois da instalação, trate a skill como um guia de trabalho para implementação, não como uma fonte para copiar e colar. O melhor resultado de provider-actions install vem do uso combinado da skill com o repositório específico do provider que você está editando.

Comece pelos arquivos certos

Leia primeiro SKILL.md e depois inspecione README.md, AGENTS.md, metadata.json e quaisquer pastas rules/, resources/, references/ ou scripts/, se elas existirem no seu repositório. Nesta skill, o caminho de origem mais relevante costuma ser internal/service/<service>/, além de website/docs/actions/ para a documentação voltada ao usuário e .changelog/ para as entradas de release notes. Se você estiver fazendo uma leitura rápida, procure o arquivo de implementação da action, o arquivo de teste correspondente e o arquivo gerado de registro do service.

Estruture bem o prompt de entrada

Um bom prompt de provider-actions usage deve nomear o serviço, o evento de ciclo de vida, o comportamento da action e as restrições. Por exemplo: “Implemente uma action para o provider <service> que rode após o create, valide <input> e registre <result>. Inclua schema, testes, docs e entrada no changelog.” Isso é melhor do que pedir apenas “uma action”, porque a skill precisa mapear sua intenção para schema, timing do ciclo de vida e convenções do provider.

Trabalhe o repositório na ordem certa

Use esta sequência de provider-actions guide: confirme que a action pertence ao provider, defina o schema, implemente a lógica da action, adicione testes e então escreva a documentação e o changelog. Se a action tocar no registro compartilhado do service, verifique arquivos gerados ou o wiring do pacote antes de assumir que o código está completo. Essa ordem reduz retrabalho e pega cedo qualquer desalinhamento entre o desenho do schema e o comportamento do ciclo de vida.

FAQ da skill provider-actions

provider-actions é só para autores de Terraform Provider?

Sim. A skill provider-actions é voltada ao desenvolvimento de Terraform Provider, não a automação genérica de aplicações. Se sua tarefa não envolve código do Provider Framework, hooks de ciclo de vida de actions ou documentação de provider, normalmente um prompt comum é uma opção melhor.

Quando não devo usar provider-actions?

Não use provider-actions se a sua funcionalidade for um resource CRUD padrão, se o comportamento desejado não estiver ligado a eventos de ciclo de vida ou se o provider não oferecer suporte a experimental actions da forma de que você precisa. Se você só precisa de um script pontual ou de um schema básico de resource, esta skill adiciona estrutura desnecessária.

provider-actions é amigável para iniciantes?

Ela só é amigável para iniciantes se você já conhece o Terraform provider de destino e consegue descrever com clareza o comportamento do serviço. A skill reduz atrito de implementação, mas não substitui o entendimento de design de schema do Terraform, estrutura de testes ou organização da documentação do provider.

Em que ela é melhor do que um prompt comum?

A skill provider-actions oferece um caminho específico do repositório para implementação de action, posicionamento de docs e armadilhas comuns de schema. Um prompt comum pode gerar código funcional, mas muitas vezes deixa passar convenções do provider, layout de arquivos ou etapas de release note que importam na revisão e no merge.

Como melhorar a skill provider-actions

Forneça o contrato da action logo de início

A melhor forma de melhorar os resultados de provider-actions é especificar o contrato exato: quando a action roda, quais inputs ela aceita, quais efeitos colaterais ela executa e o que ela retorna ou reporta. Inclua também os casos de falha. Por exemplo, diga se a entrada inválida deve bloquear a etapa do ciclo de vida ou se a action deve ser segura para no-op. Contratos claros evitam schema vago e testes frágeis.

Adicione restrições específicas do repositório

Se o seu provider tem convenções de nomenclatura, regras de código gerado ou um layout de pacote preferencial, inclua isso no prompt. A skill funciona melhor quando consegue se alinhar ao seu repositório real, em vez de inventar uma estrutura nova. Mencione se você precisa de docs em website/docs/actions/, de uma entrada no changelog ou de cobertura de testes para casos de borda e comportamento de aceitação.

Itere em cima do primeiro rascunho

Depois da primeira saída, revise se o schema está mínimo, se a action está no pacote de service correto e se os testes provam o comportamento de ciclo de vida que importa. Se o resultado vier amplo demais, restrinja o prompt a uma action e um evento. Se vier raso demais, peça explicitamente o que faltou: schema, wiring, testes, docs e changelog para a mesma mudança de provider-actions.