官方 CLI 安装失败：GitHub clone 被重置/卡死（国内高频）

你会遇到什么

执行 npx -y skills add addyosmani/agent-skills --yes --global，卡在 Cloning repository… 后报 fatal: unable to access ... Connection reset by peer / Installation failed。

最坑的是：CLI 失败时 exit 码仍为 0，只看命令返回值会误判成功。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

skills CLI 安装流程依赖 git clone https://github.com/addyosmani/agent-skills.git（直连）。国内出口到 GitHub 直连不稳定（本市场连通性基线：GitHub 直连慢/被重置），clone 大一点就被重置。

“安装失败但 exit 码是 0”是 CLI 工具常见的错误报告缺口：CLI 的退出码只反映“主流程有没有跑到最后”，不反映“每个子步骤成没成功”——这个 CLI 把 clone 失败当作可恢复的中间步骤，吞掉错误后仍以 0 退出。所以“看 exit 码判断成败”在工具链里不可靠，判断成败要看最终产物（命令的目标是“24 个技能目录就位”，那就查目录）。

这正是“以产物为准”原则：安装类命令的契约是“它承诺的产物存在”，不是“它返回 0”。

这类 CLI 的另一个特点是安装过程把网络步骤内嵌（clone 是流程的一部分），网络一断整个流程就卡/失败——但网络步骤是可以替换的：方式 B（codeload tarball）把“clone 源码仓库”换成“下载压缩包”，产物相同、通道更稳。

判断路径固定：报错文本 Connection reset by peer = 直连通道问题 → 换通道（方式 B）→ 以产物验证（目录就位）而非 exit 码。

一步步来

1. 确认失败形态 — 必做

看到 Recv failure: Connection reset by peer 就是直连问题；给 CLI 装代理环境变量（git 走代理）后重试方式 A 也可以。

2. 方式 B：tarball 手工复制 — 必做

curl -sL https://gh-proxy.com/https://codeload.github.com/addyosmani/agent-skills/tar.gz/refs/tags/0.6.7 | tar xz

实测：经 gh-proxy 拉 codeload tarball 277KB 秒级完成。

3. 复制技能目录 — 必做

cp -r agent-skills-0.6.7/skills ~/.claude/skills/agent-skills

4. 判断成功看输出，不是 exit 码 — 必做

ls ~/.claude/skills/agent-skills | head

怎么确认修好了

技能目录就位（实测输出形态）：

ls ~/.claude/skills/agent-skills
→ 24 个子目录 + 24 个 SKILL.md 全部就位

而不是只看命令 exit 码（CLI 失败时也是 0）。

其它环境的表现

症状

npx -y skills add addyosmani/agent-skills --yes --global 卡在 Cloning repository… 后报 fatal: unable to access ... Connection reset by peer / Installation failed。

原因

skills CLI 安装流程依赖 git clone https://github.com/addyosmani/agent-skills.git（直连）；国内出口到 GitHub 直连不稳定（本市场连通性基线：GitHub 直连慢/被重置）。注意：CLI 失败时 exit 码仍为 0，只看命令返回值会误判成功。

解法

1. 方式 B（国内推荐，实测可行）：codeload tarball 手工复制——curl -sL https://gh-proxy.com/https://codeload.github.com/addyosmani/agent-skills/tar.gz/refs/tags/0.6.7 | tar xz，再 cp -r agent-skills-0.6.7/skills ~/.claude/skills/agent-skills（0.6.7 为当前收录版本，升级时换 tag）。
2. 或给 CLI 装代理环境变量（git 走代理）后重试方式 A。
3. 判断成功看输出（24 技能目录就位）而不是 exit 码。