provider-actions

provider-actions スキルの概要

provider-actions は何のためのものか

provider-actions スキルは、Plugin Framework を使って Terraform Provider の action を実装するためのものです。create、update、destroy の前後といったライフサイクルイベントで、命令的な挙動が必要な provider 作成者を対象としています。provider-actions を導入すべきか判断するうえでの重要な問いは、通常の CRUD resource フローではなく action 型のワークフローが必要かどうかです。

どんな人に向いているか

すでに対象サービスの挙動を理解していて、それを provider コードへ確実に組み込むためのパターンがほしい場合に、Terraform provider の Backend Development で provider-actions スキルを使います。ファイル配置、schema の形、テストまわりで迷いを減らしつつ、action コードを provider ツリーのどこに置くべきかをより具体的に示してほしいときに特に役立ちます。

何が違うのか

このスキルは、単なる一般的な Terraform の助言ではありません。action のライフサイクル、標準的な service package 構成、action ドキュメントの配置、よくある schema の問題にフォーカスしています。そのため、HashiCorp の規約に沿い、メンテナからレビューしやすい形で provider 機能を出したいときには、広い範囲をぼんやり扱うプロンプトよりも provider-actions のほうが判断材料として有用です。

provider-actions スキルの使い方

provider-actions スキルをインストールする

npx skills add hashicorp/agent-skills --skill provider-actions で provider-actions をインストールします。インストール後は、スキルをコピペ元ではなく、実装のための作業ガイドとして扱ってください。最良の provider-actions install 結果は、このスキルと、実際に編集している provider リポジトリを組み合わせることで得られます。

まず見るべきファイルを押さえる

最初に SKILL.md を読み、続いてリポジトリ内にあれば README.md、AGENTS.md、metadata.json、および rules/、resources/、references/、scripts/ フォルダを確認します。このスキルでは、最も関係が深いソースパスは通常 internal/service/<service>/ で、ユーザー向けドキュメントは website/docs/actions/、リリースノート項目は .changelog/ です。手早く確認するなら、action 実装ファイル、そのテストファイル、生成済みの service registration ファイルを探してください。

よい入力プロンプトの作り方

強い provider-actions usage プロンプトでは、サービス名、ライフサイクルイベント、action の挙動、制約を明記します。たとえば、「<service> provider に対して、create の後に実行され、<input> を検証し、<result> を記録する action を実装してください。schema、tests、docs、changelog entry も含めてください。」のように書くのが有効です。単に「action を作って」と頼むよりよいのは、スキルが意図を schema、ライフサイクルのタイミング、provider の規約へ正確に写し込む必要があるからです。

リポジトリはこの順番で進める

provider-actions guide の進め方は、まずその action が provider に置くべきものかを確認し、次に schema を定義し、action ロジックを実装し、そのあとテストを追加してから docs と changelog を書く、という順序です。action が共有の service registration に触れるなら、コードが揃ったと思う前に generated file や package wiring を確認してください。この順番にすると手戻りを減らせるうえ、schema 設計とライフサイクル挙動の不一致も早い段階で見つけられます。

provider-actions スキルの FAQ

provider-actions は Terraform provider 作成者専用ですか？

はい。provider-actions スキルは、一般的なアプリケーション自動化ではなく、Terraform Provider 開発向けです。Provider Framework のコード、action のライフサイクルフック、provider ドキュメントに関わらないなら、通常のプロンプトのほうが適しています。

どんなときに provider-actions を使わないべきですか？

機能が標準的な CRUD resource である場合、望む挙動がライフサイクルイベントに結びついていない場合、あるいは使いたい形で provider が experimental actions をサポートしていない場合は、provider-actions を使わないでください。一度きりのスクリプトや基本的な resource schema だけで済むなら、このスキルは余計な構造を持ち込みます。

provider-actions は初心者向けですか？

対象の Terraform provider をすでに理解していて、service の挙動をはっきり説明できるなら、初心者でも使いやすいです。実装の摩擦は下げますが、Terraform の schema 設計、テスト構成、provider ドキュメントの整理方法まで代わりにはしてくれません。

普通のプロンプトより何が優れていますか？

provider-actions スキルは、action 実装、docs の配置、ありがちな schema の落とし穴について、リポジトリに即した道筋を示します。通常のプロンプトでも動くコードは出せますが、レビューやマージで重要になる provider の規約、ファイル配置、リリースノート手順が抜け落ちがちです。

provider-actions スキルの改善方法

action の契約を最初に明確にする

provider-actions の結果をよくする一番の方法は、契約を具体的に指定することです。つまり、action がいつ実行されるのか、どの入力を受け付けるのか、どんな副作用を起こすのか、何を返すのか、何を報告するのかを明示します。失敗ケースも含めてください。たとえば、無効な入力でライフサイクルのステップを止めるべきか、それとも no-op として安全に扱うべきかを指定します。契約が明確だと、曖昧な schema や壊れやすい test を防げます。

リポジトリ固有の制約を足す

provider に命名規則、生成コードのルール、好ましい package layout があるなら、プロンプトに含めてください。このスキルは、新しい構造を勝手に作るのではなく、実際のリポジトリに合わせられるときに最も強くなります。website/docs/actions/ 配下の docs が必要か、changelog entry が必要か、エッジケースや acceptance behavior の test coverage が必要かも明記してください。

初稿を見て反復する

最初の出力を受け取ったら、schema が最小限か、action が適切な service package に置かれているか、そしてテストで関心のあるライフサイクル挙動が証明されているかを確認してください。結果が広すぎるなら、1 つの action と 1 つの event に絞ってプロンプトを狭めます。薄すぎるなら、同じ provider-actions の変更に対して不足している要素、つまり schema、wiring、tests、docs、changelog を明示して追加で求めてください。