我用了大半天时间把 Kiro CLI 从零到跑通完整过了一遍。期间踩了不少隐形的坑也把 Skill 这套抽象为什么好用、哪些地方容易失控想明白了一些。这篇不是什么官方指南就是一份个人上手实录尽量按当时操作的顺序记录凡是需要配置、写文件、跑命令的地方都会给出完整示例。如果你正准备在终端里直接调度模型能力又不想把提示词、参数、输出处理全部塞进临时脚本Kiro CLI Skill 这个组合值得照着做一遍。Kiro CLI 是一个面向 AI 工作流的命令行工具它的核心是 Skill。Skill 不是简单的提示词文件而是一个自带元数据、参数契约、执行说明的指令单元。你定义好自己的任务把这个单元交给 CLI它会负责参数校验、调用模型、结果返回这些固定动作。这套机制一旦跑顺后面加新任务就是复制一个 Skill 目录的事。接下来我会从安装开始一步步拆解。1. 为什么用 CLI Skill而不是继续写脚本1.1 我过去那种临时脚本的混乱先说我自己的情况。之前在项目里调模型习惯是放一个 Python 脚本里面用几十行代码拼请求体、读环境变量、打印结果。前期确实快但改到第三版就开始难受了请求体里的提示词跟业务代码耦合在一起结构化输出的字段名前后不统一参数一多连校验逻辑都没时间写。更让人头大的是我把几套场景的 few-shot 示例放在同一个文件里结果不同任务互相污染改一个引例另一个任务也会跟着飘。事后复盘这种混乱的根源在于“任务描述”和“执行环境”没有分离。在 CLI 调模型的场景里每一次模型调用都可以拆成两个部分一部分是相对稳定的说明、规则和输出标准另一部分是每次都不一样的输入数据。传统脚本写法把这两者搅在一锅导致每次需求变化都得动核心代码而且不敢轻易动——因为你不知道这一改动会让哪条不相关的链路也出问题。1.2 Skill 的三层结构Kiro 的 Skill 说白了就是把这个痛点制度化。一个 Skill 目录通常包含三件套描述文件、指令主体、示例资产。描述文件声明这个 Skill 的名称、用途、需要哪些参数指令主体是实际要喂给模型的任务说明示例资产则放一些可以参考的输入输出对。当你在命令行里执行某个 SkillKiro 会先读描述文件做参数解析再把指令主体和你的实际输入组合成请求发给模型最后把模型输出按约定交回给你。这带来一个直接的好处新技能可以像搭积木一样组装互不干扰。参数怎么做校验、输出怎么收敛都只需要治理一个目录而不用去翻堆满 if/else 的脚本。用一句大白话讲Skill 把“让模型干活”这件事封装成了“一个命令 一套参数”。这个设计对于工程化特别重要因为你开始把模型能力当成基础设施来用了而不是当成聊天窗口来供着。1.3 什么场景真正需要它我用下来觉得CLI Skill 的最大价值是让模型能力进入自动化链路。比如在 CI 里对代码提交做风格审查批量为一批文本生成结构化标签或者每天晚上定时跑一轮数据清洗——这些任务要的是可重复、可追踪、可回滚恰恰是聊天框界面很难提供的。反过来如果你只是临时问一个问题那 Kiro 反而重了直接开个交互式对话窗口更省事。所以我的建议是先判断任务是不是“反复发生、有明确输入输出”如果是再把它做成 Skill。不是所有需求都值得抽技能抽得太多反而制造维护负担。一个好的 Skill 应该像一把称手的工具而不是一个塞满了奇怪开关的瑞士军刀。2. 安装、初始化和模型服务配置2.1 环境准备安装前先确认本机有可用的语言运行时。我用的环境是 Node 的 LTS 版本安装命令很直接。每个人的包管理器不同具体以你自己下载渠道为准我只记录我这边实际成功的命令npm i -g kiro kiro --version如果kiro命令找不到多半是全局安装路径没加入 PATH。在 Linux 下可以检查 npm 的全局 bin 目录是否在 PATH 中确保这个目录可执行。安装这一步没太多坑唯一要注意的是安装源可能影响下载速度和依赖完整性建议装完先跑一次版本检查确认二进制确实被正确链接。2.2 初始化一个工作区Kiro 的工程概念是一个工作区里放多个 Skill。第一次使用我建议别直接全局跑命令而是先建一个独立目录把技能和配置都收拢进去mkdir my-ai-workspace cd my-ai-workspace kiro init跑完 init 之后目录下面会出现一个配置文件和一个预留的 skills 目录。配置文件是全局生效的地方一些默认参数、输出格式、模型服务地址都可以在这里声明。我习惯把这个文件当成项目配置提交到版本库只把私密内容放到环境变量里读取。这一步多做一点后面切换机器环境会省很多事。2.3 配置模型服务地址和密钥接下来要做的是把模型服务的地址和密钥接入 CLI。为了避免把敏感信息提交进版本库我始终推荐用环境变量配套export KIRO_API_KEY你的密钥 export KIRO_BASE_URLhttps://你的模型服务地址/v1然后在配置文件里引用这些环境变量而不是直接写字面量。模型服务地址可不可达直接决定后面所有命令能不能跑通。我在这个环节遇到过典型问题配置完成后反复报连接失败排查下来是地址末尾多写了斜杠还有一次是 SSL 校验没关导致证书链报错。所以你要是也碰到连接问题先检查这两点再看本机网络策略和访问控制。2.4 验证配置配置完成后可以跑一个非常轻量的命令验证链路是否通畅比如查询可用的模型列表或者直接跑内置的 example 命令。我一般先执行一次最简单的运行确认模型服务返回内容正常再进入 Skill 的编写。这一步虽然简单但非常值得做因为如果在这里就发现问题后面所有 Skill 调试都会顺手很多。3. 手把手写第一个 Skill一个 JSON 修复器3.1 确定任务目标我选的第一个练手 Skill 是“JSON 修复器”。这个名字看起来很不起眼但它五脏俱全数据结构不规范正是我们经常碰到的一种情况修复逻辑需要有明确的输出约定。学会这个 Skill你基本就掌握了写任何文本型技能的方法。任务定义输入一段可能夹杂解释文字、字段缺失或多逗号的“准 JSON”输出一份严格合法的 JSON。这个任务的难点在于模型如果自由发挥很容易在 JSON 外面再包一层代码块或者补上我们不想要的说明文字。所以输出约定必须写得像合同条款一样毫不含糊。3.2 Skill 目录结构在工作区里创建skills/ json-repair/ SKILL.md metadata.yaml examples/ input-1.json output-1.json先写 metadata.yaml它声明技能的基本信息和参数契约name: json-repair description: 将一段不完整的准 JSON 修复为标准 JSON 字符串 argument-schema: input: type: string required: true description: 待修复的原始文本 output: type: json参数校验是这里的关键。required: true的意思是如果你在命令行里漏了 inputCLI 会直接在本地报错压根不会把请求发到模型这比我过去脚本里手写 if 判断靠谱得多。3.3 SKILL.md 的写法接下来是最直接的指令主体 SKILL.md。我第一版只写了一句话“修复我提供的 JSON”效果很不稳定模型偶尔会答非所问。反复试了多次之后我改成结构化写法。这个模板可以直接套用# 任务 把用户提供的文本修复为合法 JSON禁止追加任何解释。 # 输入规则 - 如果输入中有 代码块只保留代码块内的内容。 - 如果存在缺失的字段值用 null 补齐。 - 移除多余的尾逗号。 # 输出约定 只输出 JSON 本身不要使用 markdown 代码块包裹不要在前后添加任何内容。这段看起来简单但我调了很久才想明白模型最怕的就是“自由度”。你想让它输出什么格式就要把格式边界说死。尤其最后一条输出约定直接决定你后面能不能用解析工具直接读取结果省掉手工清理。3.4 用示例资产辅助收敛除了提示词我还在 examples 目录放了一组输入输出对照。Kiro 的 CLI 不是每次启动都会自动读这些文件但把它们作为示例放在 Skill 文档附近既方便想把这技能分享给团队的人理解也便于在调试时手动喂样例数据快速发现提示词到底哪部分没约束住。我现在养成了一个习惯每次修改提示词前先把现有样例跑一遍做回归避免在优化 A 的同时把 B 搞坏。3.5 注册并运行保存好文件后回到工作区根目录注册kiro skill add ./skills/json-repair kiro skill list然后运行kiro run json-repair --input {name: 张三, age: 1,,}第一次跑如果输出不是合法 JSON先别急着改提示词。优先检查两件事其一你的模型服务是否支持 JSON 输出如果不支持输出约定就是一个软约束其二你给的输入是不是真的符合预期。只有在确定这两点无误后再回到 SKILL.md 补充“如果……那么……”的细化规则。注意别一口气加太多限制否则模型会变得畏手畏脚宁可选择默认不输出也不去尝试。4. 从 0 到跑通的全过程记录4.1 分步验证我把“跑通”拆成四个可以验证的阶段配置可用、Skill 可注册、命令行参数解析正确、模型输出符合约定。每个阶段都要有看得见的反馈中间任何一步断了都能很快定位。比如我在调试时用到--dry-run直接查看替换后的请求体能确认参数和提示词是不是按预期拼好了kiro run json-repair --input {a: 1,} --dry-rundry-run 不会真正调用模型它只是把即将发出的请求原样打印出来。这一步非常有用相当于拿到一张底牌如果请求体里根本没有你的 input那后面模型输出再怎么离谱都不奇怪。4.2 调试输出的三板斧真正跑起来以后我常用的调试手段有三个加详细日志、输出重定向、结果用解析工具校验。--verbose可以看到请求和响应摘要能快速判断是不是模型服务端返回了异常--output result.json把模型输出持久化拿到结果后我再用 jq 或本地的 JSON 解析器校验格式。只要结构不合法脚本直接中断不再往下游喂脏数据。这套流程也延伸出我处理文本任务的标准动作CLI 负责跑、文件负责存、解析工具负责验。三个动作必须形成一个闭环而不是只看着终端里的日志拍脑袋。大家经常忽略的是模型输出没有经过程序化校验就以为任务成功了其实后续的日志噪声多半就是这一步过早放过生成的。4.3 交互式会话与上下文管理单次运行适合无状态的自动任务但有些场景需要多轮对话比如希望模型先分析现有代码再根据分析结果改一个文件。Kiro 也提供交互式入口我会在调试阶段优先用交互模式因为能快速看到中间过程。跑通之后再回到单次调用模式把入参、出参固化成技能。这个环节有个非常容易踩的坑把交互模式下积累的对话上下文当成单次模式自然带有的能力。两者不一样单次运行每次都是全新的开始不会记住上次说了什么。如果你在流水线里发现模型表现不稳定先想一想是不是依赖了并不存在的上下文。想要跨运行保留背景资料就把必要信息放到 Skill 的说明文件里或者干脆以固定模板的方式传给输入参数不要赌模型的“记忆力”。4.4 接入流水线的最小例子真正让 Kiro 发挥价值的地方是把它接进自动化流程。比如我给一批文本做标签分类会在脚本里循环遍历文件把每个文件内容作为 input把输出写回一个汇总目录for file in ./raw/*.txt; do kiro run classify-skill --input $(cat $file) --output ./out/$(basename $file).json done命令本身没多神奇但它把“调用模型”变成了一个标准 shell 步骤下游再接什么脚本都不怕格式漂移。整个过程必须保证模型输出能被程序化消费。如果你的任务输出是自然语言描述也建议在技能里定义一个严格的 JSON 包装把关键判断放在结构字段里再附上一个可读性的字段供人查看。这样机器和人都能各取所需。5. 工程化落地时我积累的经验5.1 版本管理与变更纪律把 Skill 从“自己能用”推到“团队能用”第一件事是纳入版本控制。每一个 Skill 是一个目录metadata.yaml 里的参数 schema 是它的公开接口。说得直接一点修改参数 schema 属于破坏性变更会直接影响所有调用你的流程、任务、同事脚本。我习惯把每次 schema 变化记录在一个变更日志文件里并同步更新版本号。等你熟练了你会觉得 schema 的稳定性比提示词的“完美”更重要因为后者可以在运行中慢慢调前者一旦改了整条链路的调用方都要跟着变。5.2 密钥与配置分离只要涉及账号密钥我就坚定不移地走环境变量路线。CLI 配置里只保留环境变量符号不保留字面量。这样即使整个仓库被克隆敏感信息也不会外泄。再结合权限管理做到最小化授权。我的习惯是每台机器用一个独立的密钥可以单独吊销如果发现某台机器泄露只吊销这一份影响范围最小。有人嫌麻烦把密钥直接写进配置文件短期看是省事但等你需要轮换密钥的时候就知道什么是四处找硬编码的痛苦。5.3 结构性输出的价值如果任务依赖模型产出结构化数据尽量不要让模型输出自由文本再靠下游自然语言解析来挽回。自然语言解析就是给自己埋雷改一个正则就要排查整条链路。正确做法是在 SKILL.md 里明确规定输出 JSON 结构字段命名保持稳定然后再用解析工具做二次校验。让模型的不确定性收敛到一个最小的、可控的范围剩下的交给代码逻辑。字段命名这件事也要一开始就想好中途换字段名会导致所有历史输出全部失去可比性。5.4 批量场景要控制并发批量任务如果直接串行跑对上千条数据来说会很慢。我一般会在外面套一层任务队列脚本限制并发数和失败重试次数。并发太高的话模型服务会直接限流错误率反而上升。合理的做法是先做一次小规模压测找到模型服务的吞吐拐点再把这个值写到队列配置里。跑完后扫描输出文件数量和输入一一对应确保没有漏跑的任务。批量任务最怕的不是单条失败而是静默跳过所以校验环节一定要有输出计数。6. 常见问题与排查技巧实录6.1 排查速查表我把这大半天遇到的高频故障整理成一张表方便你直接对照现象可能原因处理办法命令找不到全局 bin 不在 PATH检查 PATH 环境变量定位全局安装目录连接请求超时模型服务地址不可达或网络策略限制先 curl 验证地址检查网络策略与访问控制再看地址是否写错握手失败SSL 校验问题检查证书链必要时在配置中关闭对自签证书的校验Skill 列表为空没注册或工作区路径不对回到工作区根目录重新执行 skill add 并确认 skills 路径正确参数提示必填metadata 的 required 没满足命令行补全参数或用交互模式确认参数名输出总是带代码块输出约定没禁止代码块在 SKILL.md 中强制追加“不要用代码块包裹”输出 JSON 解析失败模型生成多余文本或字段不一致开启 JSON 输出约束增加字段级校验记忆不生效单次运行不保留上下文改用交互式模式或显式传递历史摘要6.2 一次实际排查模型没有返回结果但状态码正常这里挑一个最有代表性的场景细说。我一度以为调用失败实际上请求根本没到达模型服务。我先检查配置文件里的地址再确认网络可以访问都正常。后来用--verbose打开日志才发现我加到环境变量里的密钥名没对上CLI 的读取逻辑要求环境变量名严格匹配。日志里只显示“未找到凭据”提示不明显。最终的排查技巧是一切以详细日志为准不要猜。任何“我以为”“应该不会”的怀疑都要靠日志证据来验证。6.3 Windows 环境下的字符集问题我有一台 Windows 开发机命令行默认编码不是 UTF-8直接把中文内容重定向到文件往往在终端里看是好的打开文件却是乱码。这个问题和 Skill 本身无关纯粹是环境设置的差异。提前把控制台编码设置成 UTF-8或者在调用时统一指定编码能少掉很多无谓的困惑。遇到这种问题时别急着怀疑 Kiro先用一个已知内容的文件做重定向测试很快就能定位是不是环境编码的锅。6.4 关于“过度优化”的提醒调试到后期我一度陷入了不断给提示词加限制的循环结果模型输出变得很干巴甚至漏字段。我得到的教训是提示词不是越细越好规则之间可能冲突。你想让模型既要“简洁”又要“全面”这两个要求本质上就是互斥的模型只能靠跳步来表面维持平衡。如果你想跑通的只是一个前期验证就不要追求一次成型的高阶抽象先让任务在最小范围内跑通稳定之后再慢慢加限制、加规则并且每次都做回归对比。这种克制的节奏比一口气写出一套“完美”的复杂技能靠谱得多。最后讲两句体会到这里Kiro CLI Skill 从 0 到跑通的主线过程就完整了。我个人最深的感受是这类工具考验的不是能不能敲命令而是是否愿意把任务拆成“稳定的描述”和“变化的输入”。Skill 机制会强制你做这种拆分短期会多花一点时间但长期省下的维护成本非常可观。最后再分享一个小技巧给每个 Skill 准备一个名为 smoke-test 的回归样例集合每次改完提示词先跑一遍。虽然只是多敲一条命令的事但能让你以后所有改动都有底气。希望这份实录能帮你早点把自己从“反复粘贴 prompt”的循环里解放出来。