Skill 用于向 IaC Code 注入专业知识、任务规范和可复用工作流。本文通过一个 ROS 模板审查示例说明 Skill 的发现范围、创建方式,以及在 REPL 和 Web 版中的验证方法。
前提条件
已完成安装和配置 IaC Code。
已进入需要使用 Skill 的项目目录。
能够在项目中创建
.iac-code/skills/目录和SKILL.md文件。
Skill 的发现范围
Skill 是包含 SKILL.md 的目录。IaC Code 会从以下位置发现 Skill;同名时,列表中越靠后的来源优先级越高:
范围 | 目录 | 适用场景 |
用户级 |
| 当前用户的多个项目共用。 |
项目级 |
| 与现有项目目录约定兼容。 |
项目配置级 |
| 与项目一起维护的 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 中验证和调用
在项目目录启动 IaC Code:
iac-code输入
/skills,在 Skill 管理器中确认ros-template-review已出现且处于启用状态。输入以下命令调用 Skill:
$ros-template-review template.yaml # 也可以使用等价的 /ros-template-review template.yaml
预期结果:IaC Code 按 SKILL.md 中定义的顺序读取并审查 template.yaml,以“阻断、警告、建议”三个级别输出结果,并且不会修改或部署资源。
修改 SKILL.md 后重新启动会话,或重新进入项目以刷新发现结果。需要引用较长的规范、模板或示例时,可以在 Skill 目录下增加 references/ 等文件,并在 SKILL.md 中按需引用,避免把全部内容重复写入主文件。
在 Web 版中验证和调用
启动
iac-code web,新建或打开使用该项目目录的会话。打开“设置 > 插件 > Skills”,选择项目并确认
ros-template-review已出现。您可以在此处搜索 Skill,并启用或停用非内置 Skill。返回会话,在输入框中输入
$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 中搜索,避免与普通斜杠命令混淆。