npx skills 报错怎么办5 类常见错误的分阶段排查指南【免费下载链接】skillsThe open agent skills tool - npx skills项目地址: https://gitcode.com/GitHub_Trending/ad/skills装到一半弹出 GitCloneError多半是网络或凭据的问题加一个选项就报 Unknown option多半是参数写错了。npx skills 命令错误不用慌把报错对上阶段逐项验证即可。 错误速查总表先拿报错关键字对下表锁定你卡在哪一步再进对应小节错误关键词触发阶段一句话根因跳转锚点GitCloneError / Clone timed out安装时仓库拉不下来网络慢、凭据缺失或地址有误仓库克隆失败Failed to sync node_modules skills安装时本地依赖没装好锁文件恢复中断依赖同步失败Unknown option / Unknown command使用中传了工具不支持的选项或子命令未知参数Invalid skill name: potential path traversal detected使用中技能名带了../等路径字符路径遍历拦截ENOENT卸载与维护删的是一个没装在当前作用域里的技能文件不存在安装前环境自查清单绝大多数安装期错误在安装前就能提前排除。按顺序过三件事Git 已安装且能连上仓库。验证# 检查 git 版本是否可用 git --version # 连通技能仓库成功会列出分支名 git ls-remote https://gitcode.com/GitHub_Trending/ad/skills HEADGit 凭据已配置私有仓库必查。SSH 方式验证# 验证 SSH 密钥是否已加载 ssh-add -l用 GitHub CLI 的场景可改跑gh auth status确认登录状态。npm / Node 版本正常。npx 依赖 npm 执行版本过低会出怪问题# 查看 node 与 npm 版本 node -v npm -v安装时克隆与依赖类错误排查这一步 npx skills 会临时克隆技能仓库并写入本地网络、凭据、依赖三件事任何一件掉链子都会在这里报错。仓库克隆失败症状GitCloneError: Failed to clone [仓库URL]: … 或 Clone timed out after 300s.根因克隆默认 5 分钟超时私有仓库没配凭据时也会失败。源码里已按「超时 / 鉴权失败 / 其他」三类给出不同提示先看你的属于哪一类。修复# 大仓库或网络慢时把克隆超时提到 10 分钟再装 SKILLS_CLONE_TIMEOUT_MS600000 npx skills add [owner]/[repo] # 私有仓库先确认凭据再换 SSH 地址重装 ssh-add -l npx skills add gitgithub.com:[owner]/[repo].git # 网络实在不通先手动克隆把本地路径传给 add git clone https://gitcode.com/GitHub_Trending/ad/skills [本地目录] npx skills add [本地目录]相关实现src/git.ts依赖同步失败症状Failed to sync node_modules skills: …根因你在跑experimental_install它按 skills-lock.json 从 node_modules 恢复技能但本地依赖缺失或装坏了。修复# 清掉可能损坏的 npm 缓存 npm cache clean --force # 重新安装项目依赖 npm install # 依赖就绪后再从锁文件恢复技能 npx skills experimental_install相关实现src/install.ts使用中命令参数与执行类错误排查安装没问题之后报错多半出在参数上——参数不匹配会立刻报错退出不会造成半装状态。未知参数症状Error: Unknown option: [参数名] 或 Unknown command: [命令]根因use子命令只认--skill/-s、--agent/-a、--full-depth这几个选项子命令拼错比如skills inastall也会直接报 Unknown command。修复# 查看当前支持的子命令与选项 npx skills --help # 确认技能属于哪个包用 add 安装而不是瞎试选项 npx skills list # 用正确语法装技能别名 install 也有效 npx skills add [owner]/[repo] --skill [技能名称]相关实现src/cli.ts路径遍历拦截症状Invalid skill name: potential path traversal detected根因技能目录名里出现../这类字符安装器会先清洗并校验名字一旦发现想写出目标目录就拒绝写入。这是 npx skills 的安全机制不是环境坏了。修复# 列出仓库里真实的技能名复制粘贴使用 npx skills add [owner]/[repo] --list # 用干净的名字指定要装的技能 npx skills add [owner]/[repo] -s [技能名称] # 安装成功后确认落盘位置 npx skills list相关实现src/installer.ts卸载与维护文件/目录类错误排查删除、更新技能时错误几乎都跟「文件到底在不在这个作用域」有关。文件不存在症状ENOENT: no such file or directory, …根因你删的是一个没装在当前作用域的技能。项目级不带-g和全局级带-g是两套目录用错作用域就会报文件不存在。修复# 先看项目作用域里装了什么 npx skills list # 再看全局作用域确认技能装在哪一层 npx skills list -g # 确认存在后再删装成全局的就带 -g 删 npx skills remove [技能名称] npx skills remove [技能名称] -g相关实现src/remove.ts仍无法解决三条求助路径对着--help逐字核参数# 打印全部子命令与选项 npx skills --help # 查当前版本号锁定问题版本 npx skills --version用list --json核对真实状态它输出纯文本、不带颜色码方便逐字段比对# 导出项目作用域已装技能的 JSON 清单 npx skills list --json带着完整报错信息去提问。提交 issue 时附三样东西报错原文、--version输出、完整命令。信息越齐复现越快。下次再看到红色报错先对速查表锁阶段再进小节验证。【免费下载链接】skillsThe open agent skills tool - npx skills项目地址: https://gitcode.com/GitHub_Trending/ad/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考