provider-actions

provider-actions 技能概览

provider-actions 的用途

provider-actions 技能帮助你使用 Plugin Framework 实现 Terraform Provider 的 action。它面向那些需要在 create、update 或 destroy 之前、之后等生命周期事件上执行命令式行为的 provider 作者。如果你正在判断是否要安装 provider-actions，关键问题就是：你的 provider 需要的是 action 风格的工作流，还是普通的 CRUD resource 流程。

谁应该使用这个技能

当你已经理解目标服务的行为，并且需要一种可靠模式把它接入 provider 代码时，可以在 Terraform provider 的 Backend Development 工作中使用 provider-actions 技能。它最适合那些希望少一点文件布局、schema 形状和测试上的试错，多一点关于 action 代码该放在 provider 树哪个位置的指引的人。

它为什么不同

这个技能不是泛泛的 Terraform 建议。它聚焦于 action 生命周期、标准 service package 结构、action 文档的放置位置，以及常见的 schema 问题。这让 provider-actions 在你需要交付一个既符合 HashiCorp 约定、又能被维护者审核的 provider 功能时，比宽泛的提示词更有决策价值。

如何使用 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 提示词应该写明 service、生命周期事件、action 行为和约束。例如：“为 <service> provider 实现一个 action，在 create 之后运行，校验 <input>，并记录 <result>。请包含 schema、测试、文档和 changelog 条目。” 这比只说“实现一个 action”更好，因为这个技能需要把你的意图映射到 schema、生命周期时机和 provider 约定上。

按顺序处理仓库

使用这套 provider-actions guide 顺序：先确认 action 是否应该放进 provider，再定义 schema，接着实现 action 逻辑，然后补测试，最后写文档和 changelog。如果 action 会影响共享的 service registration，先核对生成文件或 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，并且能清楚描述服务行为时，它才算对新手友好。这个技能能降低实现摩擦，但它不能替代你对 Terraform schema 设计、测试结构，以及 provider 文档组织方式的理解。

它比普通提示词好在哪里？

provider-actions 技能会给你一条针对具体仓库的实施路径，覆盖 action 实现、文档放置位置和常见 schema 陷阱。普通提示词可能也能生成可用代码，但往往会漏掉 provider 约定、文件布局或在审查和合并时很重要的 release-note 步骤。

如何改进 provider-actions 技能

先把 action 合约说清楚

提升 provider-actions 结果的最佳方式，是明确指定合约：action 何时运行、接受哪些输入、执行哪些副作用，以及返回或报告什么。也要把失败场景写进去。例如，说明无效输入是否应该阻止生命周期步骤，或者 action 是否应当对 no-op 安全。清晰的合约能避免 schema 含糊和测试脆弱。

加上仓库特定约束

如果你的 provider 有命名规范、生成代码规则，或者偏好的 package 布局，请在提示词里写明。这个技能只有在能贴合你的真实仓库时才最强，而不是替你发明一套新结构。也要说明你是否需要 website/docs/actions/ 下的文档、changelog 条目，或者针对边界情况和 acceptance 行为的测试覆盖。

基于第一版继续迭代

拿到第一版输出后，检查 schema 是否足够精简、action 是否放在正确的 service package 中，以及测试是否证明了你关心的生命周期行为。如果结果过于宽泛，就把提示词收窄到一个 action 和一个事件；如果内容太少，就明确补要缺失部分：同一次 provider-actions 变更所需的 schema、wiring、测试、文档和 changelog。