IaC Code 提供可安装到外部智能体中的官方 Agent Skill。根据希望在本机运行 IaC Code，还是直接调用阿里云云端 ROS Agent，可以选择 iac-code 或 alibabacloud-ros-agent。本文介绍两种 Skill 的区别、安装方式和首次调用流程。
选择 Skill
Skill | 运行方式 | 适用场景 |
| 在本机下载并启动经过校验的 IaC Code Runtime | 希望复用本机 IaC Code 的模型、阿里云身份和工作目录，并直接处理项目文件。 |
| 通过 ROS | 希望由云端 ROS Agent 完成云资源规划、IaC 和资源栈任务，不在本机运行 IaC Code Runtime。 |
两种 Skill 都支持普通对话和包含方案选择、费用评估及部署确认的 Pipeline。iac-code 的执行环境位于本机，alibabacloud-ros-agent 的智能体执行环境位于云端。需要同时使用两种方式时可以都安装，并在提示词中明确指定 Skill。
“Agent Skill 集成”和“IaC Code Skill 扩展”用途不同：
通过 Agent Skill 集成 IaC Code：把本文介绍的官方 Skill 安装到其他 Agent，使其获得 IaC Code 或云端 ROS Agent 的云资源管理能力。
通过 Skill 扩展 IaC Code：为 IaC Code 自身添加专业知识、模板规范和组织工作流。具体方法请参见通过 Skill 扩展 IaC Code。
如果需要自行部署远程智能体服务，或者由平台直接管理任务和上下文，请使用通过 A2A 集成 IaC Code。
前提条件
宿主 Agent 支持由
SKILL.md定义的本地 Skill。宿主可以运行 Python 3.8 或更高版本。macOS 或 Linux 使用
python3，Windows 优先使用py -3。可以访问对应的官方下载地址或阿里云 Agent Skills 门户。
已确定 Skill 可以访问的项目目录，并了解即将执行的文件或云资源操作。
如果使用 npx skills 安装，需要 Node.js 18 或更高版本。
安装和使用 iac-code Skill
下载并安装
下载最新稳定版：
该固定地址始终指向 stable 频道的最新版本，不需要在每次发布后修改下载链接。
将 ZIP 解压到宿主 Agent 的 Skill 根目录。具体位置以宿主文档为准，最终结构应为：
<Agent Skill 根目录>/
└── iac-code/
├── SKILL.md
├── agents/
└── scripts/
└── iac_code.py
ZIP 已包含顶层 iac-code/ 目录，不要再增加一层同名目录。
重启宿主 Agent 或新建会话，使其重新发现 Skill。
在
iac-code目录中验证 Runtime。macOS 或 Linux 运行：
python3 scripts/iac_code.py ensure-runtime
Windows PowerShell 运行：
py -3 scripts\iac_code.py ensure-runtime
预期结果：首次运行时下载并校验当前平台对应的 IaC Code Runtime，后续调用会直接复用缓存。
配置运行环境
iac-code Skill 与 REPL、Web 版和桌面版使用相同的配置目录，默认为 ~/.iac-code/。已经配置过模型服务和阿里云身份时可以直接复用；使用其他配置目录时，设置 IAC_CODE_CONFIG_DIR。
模型配置是本地 Runtime 运行的必要条件。任务需要查询或管理云资源时，还需配置具有最小必要权限的阿里云身份。自动化环境可以通过 Secret 管理方案注入模型和阿里云凭据，不要把真实密钥写入 SKILL.md、提示词或项目文件。
完成第一次调用
在宿主 Agent 中打开项目并输入：
$iac-code 检查当前项目中的 ROS 模板，列出安全风险和修改建议，不要修改文件，也不要部署资源。
如果宿主不支持显式 Skill 语法，可以直接要求它使用 iac-code Skill 完成同一任务。
预期结果：宿主将任务委派给本地 IaC Code Runtime，并展示执行过程和审查结果。第一次调用可能需要下载 Runtime，耗时会比后续调用更长。
安装和使用 alibabacloud-ros-agent Skill
下载并安装
可以在阿里云 Agent Skills 门户中搜索 alibabacloud-ros-agent，也可以通过官方仓库安装：
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-ros-agent
也可以直接下载 ZIP，并将其中的顶层 alibabacloud-ros-agent/ 目录解压到宿主 Agent 的用户级或项目级 Skill 目录。安装完成后，重启宿主 Agent 或新建会话。
该 Skill 的默认传输需要使用随包提供的 Python 依赖。如果首次检查提示依赖尚未安装，请在 Skill 目录中运行：
python3 -m pip install -r scripts/requirements.txt
python3 scripts/ros_agent.py check
Windows PowerShell 运行：
py -3 -m pip install -r scripts\requirements.txt
py -3 scripts\ros_agent.py check
预期结果：检查输出当前传输、ROS 服务端点和非敏感的身份就绪信息。不要读取或输出凭据值来验证配置。
配置阿里云身份
alibabacloud-ros-agent 使用宿主进程可用的阿里云默认凭据链或指定的阿里云 CLI Profile，不需要下载本地 IaC Code Runtime，也不需要配置本地模型服务。
调用云端 ROS Agent 的身份必须具有 ros:StartChat 权限。只有显式取消正在运行的远程任务时才需要 ros:StopChat 权限。建议使用 STS、RAM Role 或 ECS RAM Role 等临时身份，并只授予任务实际需要的权限。
完成第一次调用
在宿主 Agent 中输入：
$alibabacloud-ros-agent 查询 cn-hangzhou 地域中的 ROS 资源栈，汇总异常状态，不要执行写操作。
如果宿主不支持显式 Skill 语法，可以要求它“使用阿里云 ROS Agent”完成任务。
预期结果：Skill 通过 ROS StartChat API 建立云端会话，宿主持续展示进度和最终结果。需要补充参数、选择方案或批准操作时，继续在同一宿主会话中回答。
处理交互和权限请求
两种 Skill 都可能因为以下情况暂停任务：
需要补充地域、资源规格、模板路径等信息。
需要从多个架构或资源候选方案中选择。
需要批准文件修改、命令执行、云 API 或部署操作。
请直接在当前宿主会话中回答或选择。批准前检查目标文件、地域、资源、预计费用和影响范围。拒绝操作后，宿主不能绕过该决定继续执行同一写操作。
更新和卸载
更新
iac-code时，重新下载固定稳定版地址中的 ZIP，并完整替换iac-code/目录。更新
alibabacloud-ros-agent时，重新运行npx skills add，或从 Skills 门户重新下载并完整替换对应目录。卸载时删除宿主 Skill 根目录下对应的 Skill 目录，然后重启宿主或新建会话。
不要只替换单个桥接脚本，也不要手工修改 Runtime 地址、校验信息或 Skill 自带的服务配置。
安全说明
只从 IaC Code 官方稳定版地址、阿里云 Agent Skills 门户或官方 Skills 仓库安装 Skill。
不在 Skill、项目文件、提示词、日志或聊天内容中粘贴 API Key、AccessKey Secret 等敏感信息。
iac-code的本地 Runtime 只监听本机回环地址并使用独立认证信息；不要将其作为公开服务暴露。alibabacloud-ros-agent的服务调用受阿里云身份和 RAM 权限约束；不要用主账号 AccessKey 绕过授权问题。部署或变更云资源前，始终检查目标资源、地域、费用和影响范围。
常见问题
应该选择哪个 Skill
希望本地处理项目文件、复用本机 IaC Code 配置或控制 Runtime 版本时，选择 iac-code。希望直接使用阿里云云端 ROS Agent，并由阿里云身份控制访问时，选择 alibabacloud-ros-agent。
宿主 Agent 没有发现 Skill
确认 SKILL.md 位于 <Agent Skill 根目录>/<Skill 名称>/SKILL.md，没有多嵌套一层目录。安装或更新后重启宿主 Agent 或新建会话，并检查宿主产品的 Skill 发现规则。
iac-code 首次运行无法下载 Runtime
确认当前平台和架构受支持，并检查官方 OSS 地址的网络连接、代理、证书和磁盘空间。不要通过修改脚本或关闭校验绕过下载错误。
alibabacloud-ros-agent 返回身份或权限错误
先运行随 Skill 提供的 check，确认默认凭据链或指定 Profile 已就绪。出现无权限错误时，为运行身份补充 ros:StartChat；需要取消远程任务时再补充 ros:StopChat。不要在命令行或对话中打印 AccessKey。
任务执行过程中暂停
检查当前会话中是否存在待回答的问题、候选方案或权限请求。完成本次交互后，宿主会继续同一个任务，无需重新提交完整请求。