npx skills 调试避坑指南：命令卡死或报错，3 分钟定位问题

npx skills 调试避坑指南命令卡死或报错3 分钟定位问题【免费下载链接】skillsThe open agent skills tool - npx skills项目地址: https://gitcode.com/GitHub_Trending/ad/skillsnpx skills add敲下去之后终端转了五分钟没动静或者甩出一串fatal: ...加认证报错你根本分不清是参数写错了、网断了还是 token 没配对。这篇文章讲怎么把命令没反应、报错看不懂变成按步骤能查的问题。npx skills 是一个命令行工具负责把 AI 代理agent技能包安装、更新、列出到你本地用的各种代理工具里。两条命令先顶住真出问题时别急着重跑先打这两条npx skills add 包名 --help npx skills list --json第一条把这个命令支持的参数全列出来第二条用纯 JSON 打印已装技能不掺颜色码。参数对不对、装到没装上基本一眼就有数。输出里的三类信号命令跑完或跑崩的输出拆开看就三类。先看参数你敲的包名、-a的代理名有没有被认出来。参数写错时它通常先甩一段用法提示src/cli.ts 里就是这些入口和用法说明的出处。再看走到哪一步add会经过解析来源、clone 仓库、写入代理目录几步。卡在哪一步输出就停在哪一步——比如半天没动静多半卡在下载或 clone 阶段。最后看报错标记git 层的失败会以Error: ...加原因打在末尾。src/git.ts 里的GitCloneError会区分超时和认证失败报错措辞对应的是不同毛病。跟着报错走一遍clone 卡死或认证失败现象npx skills add 私有仓库转圈最后报 timeout 或Authentication failed。日志里看到什么输出停在下载/clone 阶段报错要么指向超时要么指向认证——两种情况GitCloneError里是分开标记的。去查哪里克隆逻辑在 src/git.ts。两个环境变量能直接动手SKILLS_CLONE_TIMEOUT_MS改克隆等待上限默认 5 分钟太长的话可以调小私有仓库认证走 tokenGITHUB_TOKEN或gh没配好就是这个错。怎么修超时就SKILLS_CLONE_TIMEOUT_MS120000 npx skills add 仓库认证就去把 token 配好再跑。跟着报错走一遍find 搜不到现象npx skills find 关键词空列表或者压根连不上。日志里看到什么报错指向 API 请求失败而不是本地解析失败。去查哪里搜索走 src/find.ts接口地址由SKILLS_API_URL控制。内网或代理环境下默认地址可能不通。怎么修把SKILLS_API_URL指到你环境里能访问的地址重跑搜索即可。把输出调小满屏输出里翻线索很累两个收窄的办法npx skills list --json npx skills 命令 --help--json把 list 变成机器可读的纯 JSON方便grep或肉眼扫--help列出该命令全部取值确认自己有没有漏参数。再复杂的问题把npx skills 命令的完整输出存下来对着 src/cli.ts 的命令分支找能省不少时间。下次再出问题按这个口诀来① 加--help对参数② 看输出卡在哪一步③ 用--json或报错措辞缩小范围。三步走完还没解决就 clone 仓库翻源码git clone https://gitcode.com/GitHub_Trending/ad/skillssrc/下每个命令都有对应文件报错从哪来答案就在哪。【免费下载链接】skillsThe open agent skills tool - npx skills项目地址: https://gitcode.com/GitHub_Trending/ad/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考