meta-skill：给 agent 用的那层元技能

2026-08-10

CLI-Anything 仓库里绝大多数 SKILL.md 都是在教 agent 怎么用某一款软件——怎么建工程、怎么导出、怎么进 REPL。有一份不是。cli-hub-meta-skill/ 这个目录我们采集时（2026-08-10，对应仓库快照 39634a6）只有一个文件 SKILL.md，115 行，它谁也不描述，只描述那个包管理器本身。

这份文件的位置有点特别：它在仓库顶层 82 个目录里，属于 14 个「有目录但 registry.json 里没有同名条目」的非 harness 目录之一；另一处是 skills/ 下另有 14 个未被任何 registry 条目引用的子目录，cli-hub-meta-skill 也在其中——这是两批不同的目录，只是个数碰巧都是 14。也就是说你用 cli-hub search 是搜不到它的，它不走注册表那条分发线。README 给的安装口径是另一条命令（README.md:245）：

npx skills add HKUDS/CLI-Anything --skill cli-hub-meta-skill -g -y

frontmatter 里 name 就是 cli-hub-meta-skill，description 一句话是 “Discover agent-native CLIs for professional software”（cli-hub-meta-skill/SKILL.md:1-6）。按字面看它像一份「发现工具」的技能。真正读进去会发现，这 115 行里最硬的几条约束，方向恰恰相反。

它给 agent 规定的标准动作序列

第 34 到 38 行先定义了 matrix 这个概念：一个 CLI 是一个工具，而 matrix 是打包成 capabilities × providers 的整条工作流。这一句是后面所有动作的前提——agent 面对的不是「装哪个软件」，而是「我要的这个能力，谁能提供」。

紧接着第 40 到 50 行给出标准动作序列，其中一句硬性要求是 preflight before you install。这条在这份文件里不是建议语气，而是作为动作序列本身的硬要求写出来的。

为什么这一层要专门把 preflight 提到 install 前面？回到仓库实况就清楚了。我们实读 registry.json 是 79 条 CLI，public_registry.json 22 条，合并 101 条。但注册表里有一条，不等于你机器上就有这个能力：

matrix.py:150-198 的 preflight 会检查三类依赖——环境变量 env、可执行文件 binary（走 shutil.which）、Python 包 package（走 importlib.util.find_spec / importlib.metadata.version）。三类里缺任何一类，这个 provider 就不算可用。
provider 的 kind 枚举有 8 种（harness-cli、public-cli、python、native、api、agent-skill、agent-native、web-search），而 matrix install 只管得了 harness-cli 与 public-cli 两类（matrix.py:20 的 INSTALLABLE_KINDS）。agent-skill 被单列出来，preflight 时直接标 available=False、状态写 agent-installable（matrix.py:17、:173-188）。
更前置的一条在 README 里：包装真实桌面软件的 CLI，需要用户自行安装上游应用（README.md:236）。装了 harness 不等于装了 Blender。

把这三条摞起来，「注册表有 79 条」和「你这台机器上能用几条」就是两件不同的事。preflight 是这份元技能把这件事机制化的地方。

退出码 3 不是失败

这份 SKILL.md 在第 55 到 56 行按 0 / 3 / 1 / 2 的次序把退出码约定复述了一遍，把 3 摆在了紧挨着 0 的位置。这套约定与 cli-hub/cli_hub/cli.py:60-65 里的退出码契约是一致的（0 成功 / 1 失败或未找到 / 2 用法错误 / 3 部分失败或存在 gap）。

这一条对写 agent 编排的人来说是本篇最实用的一行。3 的语义由 matrix.py:269-275 定义：一个 capability 只要有至少一个可用 provider，或者存在 agent-installable 兜底，就算被覆盖；覆盖不到的算硬 gap，硬 gap 驱动退出码 3。所以 3 表达的是「这条链上有几处没人接」，而不是「命令挂了」。agent 如果把非零一律当失败去重试，会在这里空转；把 3 当成 0 直接往下走，则会在缺口那一步撞墙。

与退出码配套的善后手段在 cli-hub 的命令面上有两个：失败可以用 cli-hub matrix install <name> --resume 续跑，装完可以用 cli-hub matrix doctor <name> 审计。doctor 那边的实现是逐个检查矩阵成员是否已记录安装、entry_point 是否在 PATH，并给出 cli-hub install <name> 形式的修复命令（installer.py:565-589）。要注意 --resume 与 --capability / --recipe / --only 不能混用，混用直接返回用法错误，也就是退出码 2（installer.py:476-479）。

反直觉的那一处：这份元技能主要在踩刹车

description 写的是 “Discover”，但第 52 到 57 行这一段的实质是限流。原话的意思是：给每一次安装划定范围，不要为了一个只需要单个 capability 的任务，去整装一个 14-CLI 的矩阵；要用 --capability <id>、--recipe <id> 或 --only a,b 收窄，用 --dry-run 零副作用地预览计划。

那个「14-CLI 矩阵」不是虚指。我们实读 matrix_registry.json，5 个矩阵里规模最大的 video-creation 正好引用 14 个 CLI、19 个 capability、7 个 recipe、4 条 known_gaps。也就是说这句警告直接对着仓库里现成的那个矩阵说的。

反直觉在于：这一层通常被想象成「让 agent 发现更多工具」的入口，而它花在约束上的篇幅比花在介绍上的多。原因在这类工具的副作用上——harness 安装走的是 sys.executable -m pip install …，装进的是当前 Python 环境（installer.py:184-192）；_run_command() 在命令串里出现 |、&&、||、;、$(、反引号时会用 shell=True，注释写明理由是「命令来自受信任的 registry，不是用户输入」（installer.py:67、:70-84）。装完之后，这些 harness 要驱动的是你本机的第三方桌面软件。一个能自己决定装什么的 agent，如果不先收窄范围，产生的是一串没人复核的本机写入与外部程序调用。把「先 preflight、按 capability 收窄、先 dry-run」写成硬约束，是这份元技能在这条链路上唯一的闸。

matrix install 的选项面也是照着这个思路开的：--capability/-c、--recipe、--only、--dry-run、--resume、--skill-only、--json（cli.py:823-836），其中三个收窄选项是三选一，同时给多个直接返回用法错误（matrix.py:363-365）。

第二处要留神的：它对 cli-hub 的自我描述

第 85 行有一句 “cli-hub is a lightweight wrapper around pip”。而 installer.py:304-310 实现的是五种安装策略：pip / npm / uv / command / bundled。这份 meta-skill 全文也没有提到 public registry 与 npm / uv 这两条安装路径。两处口径不一致，以我们实读的仓库状态为准，这里只陈述差异。

差异落到 agent 身上会变成什么，是可以从卡面事实推出来的两点：public_registry.json 那 22 条里，package_manager 分布是 npm 10、pip 4、brew 2、bundled 2、uv 1、script 1、缺省 2；而 bundled 这一策略根本不执行安装，它只检测 detect_cmd / entry_point 是否已在 PATH，否则提示去上游 App 里启用（installer.py:154-162）。只按「pip 的轻量包装」这一句去理解，这两类条目的行为都会被想岔。

它和矩阵 skill 是两层东西

容易混淆的是：cli-hub-meta-skill 与 cli-hub-matrix/ 下那 5 份矩阵 SKILL.md 不是一回事，体量也差得远。meta-skill 是 1 个文件 115 行；cli-hub-matrix/ 我们采集时共 13 个文件 4893 行，光 video-creation/SKILL.md 就 536 行，其下还带 7 篇 references 与一个 2580 行的 video_doctor.py。

两者的先后关系是被安装这一步串起来的：装完之后，矩阵 SKILL.md 会在本地渲染出来，agent 再去读那一份。渲染落点是 ~/.cli-hub/matrix/<name>/SKILL.md（matrix_skill.py:5-8、:31、:40）。所以 meta-skill 是常驻的那一层，矩阵 skill 是按需落到本机的那一层。顺带一个会影响阅读的细节：找不到本地资产时，渲染出来的文件会追加一段 “No local copy … relative links above will not resolve locally” 的说明（matrix_skill.py:135-142），看到这句就说明里面的相对链接在本机点不开。关于矩阵机制与渲染链路，另有一篇专门讲，本篇只交代这两层的分界。

你可以自己核对的几件事

以下都是读文件就能做的事，不需要安装任何东西：

ls cli-hub-meta-skill/
wc -l cli-hub-meta-skill/SKILL.md
sed -n '40,57p' cli-hub-meta-skill/SKILL.md
sed -n '85p'    cli-hub-meta-skill/SKILL.md
sed -n '304,310p' cli-hub/cli_hub/installer.py
sed -n '60,65p'   cli-hub/cli_hub/cli.py

我们采集时前两条依次得到「只有 SKILL.md 一个文件」与 115 行；第三、四条对应上面拆的动作序列与那句自我描述；后两条用来把第 85 行与五种策略、把第 55 到 56 行与退出码契约各自对上。以上为按仓库中的文件与行号组合的核查示例，未经实测，以官方文档与 --help 的实际输出为准。

还有一件与 agent 直接相关、但不在这 115 行里的事，值得知道：cli-hub 自身带埋点，默认 provider 是 posthog，退出方式是把 CLI_HUB_NO_ANALYTICS 设为 1/true/yes（analytics.py:16、:84-85），匿名 id 是一个 uuid4，存在 ~/.cli-hub/.analytics_id（analytics.py:23、:194-210）。它还专门为识别 agent 宿主写了 17 条环境变量规则与 21 条父进程 cmdline 正则（analytics.py:28-46、:48-70）。这说明「被 agent 调用」在这个工具里是被预期的一等场景。要不要开着，取决于你自己的判断，项目没给通用建议。

最后回到那句最该记住的话：注册表里有 79 条，不等于你机器上有 79 个能用的能力。这份 115 行的元技能存在的意义，基本就是把这句话翻译成 agent 能执行的动作顺序——先 preflight，再按 capability 收窄，最后才轮到 install。

本文依据 CLI-Anything 官方仓库（github.com/HKUDS/CLI-Anything）的 README、registry.json、 docs/ 与各 agent-harness/ 下的源码整理，核对日 2026-08-10，对应仓库快照 39634a6。本文内容为仓库源码与文档口径，我们没有安装或运行过其中任何一个 harness，也没有在本机驱动过任何一款宿主软件，因此不涉及实际操控效果的任何描述。这类 harness 会在本机执行外部程序与脚本，是否使用请结合自身环境评估。注册表与 harness 内容随上游更新而变动，请以仓库最新内容为准。安全相关做法请结合自身环境评估，本文不构成安全方案建议。