技能介绍

要解决的问题

当 agent 去调用一个 CLI 时，它读到的往往是文档，真正跑起来的是二进制，这两者经常各说各话：文档描述了新版本才有的命令，二进制却是旧的；升级时只把新文件复制进去，旧文档永远留在磁盘上被一起读到；调用方看到 stdout 里出现了 JSON，就以为执行成功了。这个技能是一个最小但完整的示例：一个 helloworld CLI 被打成单文件二进制（内嵌 Node 运行时），skill 与它同版本发布，两者靠 latest.json 一起升级。它重点演示的不是命令本身，而是周边那套分发机制。

核心能力

自检命令：helloworld info 打印版本、内嵌的 Node 运行时版本、平台架构与本地路径。packaged: true 表示正跑在单文件二进制里；runtime.node 是打进二进制的那个 Node，与目标机器上装没装 Node 无关，机器上完全没有 Node 时这条命令照样出结果。
业务命令：helloworld greet [name] 支持 -l, --locale（zh/en/ja）、-n, --repeat（1~100）、--ndjson（逐行 NDJSON，供流式管道使用）、--plain（只输出纯文本，不带 JSON 包装）。
输出契约：调用方主要是 agent 而不是人，因此两条流严格分工——stdout 只放结构化数据（JSON / NDJSON），stderr 放给人看的进度、警告与错误；失败时 stdout 不输出成功结构，刻意与一部分同类 CLI 相反，免得调用方「见到 JSON 就以为成功」。退出码分为 0（成功）、1（通用失败）、2（用法错误，如参数缺失或取值非法）、3（环境不满足）。

分发链路的四条关键约束

CLI 与 skill 必须同版本。 skill 是 CLI 的操作手册，版本漂移时文档会描述二进制里根本不存在的命令，而 agent 读不出「CLI 旧了」这层意思。因此有 install-*-all 脚本：版本只解析一次再分发给两半。
版本从 latest.json 现取，不自己拼 URL。 旧版本目录不会被清理，拼错版本段会稳定下载到旧包，还打印「更新完成」。
升级是整目录替换，不是 cp 叠加。 叠加只加不删，上个版本删掉的文件会永远留下，新旧两套文档同时被读到，而旧的那份不带任何「我已过期」标记。
不留备份，尤其别放进 skills 目录。 宿主按 /* 扫子目录加载 skill，放个 xxx.bak 兄弟目录等于凭空多一份陈旧副本。

适用边界与注意点

本技能与 CLI 源码同仓库，改了 CLI 行为就在同一次变更里更新它。命令细节与文档冲突时，以 helloworld --help 的实际输出为准——文档会过期，二进制不会。构建、打包与分发的细节见仓库根目录 README.md，安装与升级步骤见 scripts/install.md，输出契约与退出码的实现见 src/core/output.ts，分发产物的组装见 scripts/dist.mjs。不要自己写更新脚本。