通过 Skill 扩展 IaC Code

更新时间:
复制 MD 格式

Skill 用于向 IaC Code 注入专业知识、任务规范和可复用工作流。本文通过一个 ROS 模板审查示例说明 Skill 的发现范围、创建方式,以及在 REPL 和 Web 版中的验证方法。

前提条件

  • 已完成安装和配置 IaC Code。

  • 已进入需要使用 Skill 的项目目录。

  • 能够在项目中创建 .iac-code/skills/ 目录和 SKILL.md 文件。

Skill 的发现范围

Skill 是包含 SKILL.md 的目录。IaC Code 会从以下位置发现 Skill;同名时,列表中越靠后的来源优先级越高:

范围

目录

适用场景

用户级

~/.iac-code/skills/

当前用户的多个项目共用。

项目级

<项目>/skills/

与现有项目目录约定兼容。

项目配置级

<项目>/.iac-code/skills/

与项目一起维护的 IaC Code 扩展。

内置

随 IaC Code 发布

官方能力,不能被同名用户或项目 Skill 覆盖。

项目目录会从 Git 仓库根目录向当前目录逐级发现,因此可以在仓库根目录定义通用 Skill,并在子目录增加更具体的 Skill。

创建最小 Skill

在项目根目录创建以下文件:

.iac-code/
└── skills/
    └── ros-template-review/
        └── SKILL.md

SKILL.md 内容如下:

---
name: ros-template-review
description: 按项目规范审查 ROS 模板并输出分级问题清单
when_to_use: 用户要求检查或审查 ROS 模板时
argument_hint: <模板路径>
user_invocable: true
---

审查 `$ARGUMENTS` 指定的 ROS 模板。只读取文件,不修改文件,也不部署资源。

按以下顺序检查:

1. 模板语法、参数类型、AllowedValues 和默认值是否一致。
2. Ref、Fn::GetAtt 和 DependsOn 等资源依赖是否有效。
3. 安全组、公开访问、长期密钥和过宽权限等安全风险。
4. 资源命名、Tag 和输出是否符合项目约定。

按“阻断、警告、建议”三个级别输出问题。每项包含文件位置、原因和修改建议;没有发现问题时也要明确说明已检查的范围。

在 REPL 中验证和调用

  1. 在项目目录启动 IaC Code:

    iac-code
  2. 输入 /skills,在 Skill 管理器中确认 ros-template-review 已出现且处于启用状态。

  3. 输入以下命令调用 Skill:

    $ros-template-review template.yaml
    # 也可以使用等价的
    /ros-template-review template.yaml

预期结果:IaC Code 按 SKILL.md 中定义的顺序读取并审查 template.yaml,以“阻断、警告、建议”三个级别输出结果,并且不会修改或部署资源。

修改 SKILL.md 后重新启动会话,或重新进入项目以刷新发现结果。需要引用较长的规范、模板或示例时,可以在 Skill 目录下增加 references/ 等文件,并在 SKILL.md 中按需引用,避免把全部内容重复写入主文件。

在 Web 版中验证和调用

  1. 启动 iac-code web,新建或打开使用该项目目录的会话。

  2. 打开“设置 > 插件 > Skills”,选择项目并确认 ros-template-review 已出现。您可以在此处搜索 Skill,并启用或停用非内置 Skill。

  3. 返回会话,在输入框中输入 $ros-template-review template.yaml。

预期结果与 REPL 相同。Web 版会在对话中显示 Skill 触发后的工具卡片、执行结果和权限请求。

典型用法

  • 固化云资源规划、创建、变更和清理的组织流程。

  • 固化 ROS 或 Terraform 模板的组织规范和审查清单。

  • 约定环境、地域、命名、Tag、网络和安全基线。

  • 封装部署前检查、成本复核或故障排查流程。

  • 统一输入参数和输出格式,供团队成员重复使用。

  • 使用参数占位符将模板路径、资源栈名称或地域传入工作流。

权限和安全

  • 只安装和启用可信来源的 Skill,使用前审查 SKILL.md 及其引用文件。

  • 项目仓库中的 Skill 会影响智能体行为,应像代码一样进行评审。

  • 不在 SKILL.md 或引用文件中保存 API Key、AccessKey 或其他 Secret。

  • Skill 不能绕过 IaC Code 的工具权限;对文件、命令和云上写操作保持最小授权。

常见问题

Skill 未被发现

确认目录名和文件名为 <skill-name>/SKILL.md,YAML Frontmatter 包含非空的 name 和description,并且当前目录位于预期项目中。再通过 /skills 检查 Skill 是否被禁用或被同名高优先级 Skill 覆盖。

Skill 没有按预期使用参数

在正文中使用 $ARGUMENTS 获取完整参数,或使用 $0、$1 和命名参数进行位置替换。调用时使用 $<skill-name> <参数> 可以只从 Skill 中搜索,避免与普通斜杠命令混淆。

相关文档