指南
Agent 技能无法使用?排查加载、工具与下载问题
重新安装前先定位失败阶段:账号权益、技能发现、调用、执行还是导出。保留定制文件,并准备简洁、脱敏的复现信息。
快速开始
让 AI 助手帮你完成
将这段提示粘贴到你正在使用的 AI 助手中:
帮我排查 Agent 技能,避免删除或覆盖文件。询问助手、本地或远程环境、技能名称及脱敏后的第一个错误。区分技能发现、触发、依赖、内容包权益与成果验证。每次提出一项检查,在修改配置前确认检查结果。
哪个阶段发生了失败?
先区分下载失败与助手失败。内容包已在磁盘上时,让助手识别目标 SKILL.md 并明确选择该技能。找到文件、加载指令、执行工具和验证导出是不同检查。重新安装前记录第一个失败点。
助手找不到技能
确认当前项目及助手读取的目录,将 SKILL.md 与脚本、参考资料和素材保存在一起。常规项目安装中,Codex 使用 .agents/skills,Claude Code 使用 .claude/skills,Cursor 支持 .cursor/skills 或 .agents/skills。其他位置与发现规则请以官方文档为准。
- 检查解压后的文件夹,留意 ZIP 是否增加了额外嵌套。
- 检查 YAML 中的 name、description 及助手特有的作用范围设置。
- 按助手文档刷新发现过程,再询问实际加载的是哪个文件。
.agents/skills/example-skill/
├── SKILL.md
├── scripts/
└── assets/可以发现,但没有按预期运行
通过明确选择来区分发现技能与自动匹配,并询问助手准备使用哪个文件和流程。相似描述、重复副本,以及调用或作用范围设置都会影响选择。确认哪个副本正在生效前,保留定制内容。
- Claude Code 和 Cursor 支持通过 / 命令选择技能;Codex 支持明确选择技能。
- 使用与说明中的输入和成果相符的要求,先完成一个小任务。
指令已经加载,但工具执行失败
记录第一个工具错误,并与当前版本的要求比较。在助手实际运行的环境中检查解释器、依赖包、路径与输入格式。助手标签不会安装 Python、Chromium 或 FFmpeg。远程会话也需要自身的文件与依赖;本地已有文件不能证明远程环境也有。
- 安装或升级依赖前,先检查说明中的版本要求。
- 通过服务商正常配置流程验证所需服务,并从日志中移除密钥。
- 执行成功但结果不正确时,应审核输入、计算与导出文件。
Skillrove 下载或 CLI 被阻止
| 现象 | 检查内容 |
|---|---|
| 要求登录或授权 | 使用目标账号和商店地址,并完成 CLI 浏览器授权。 |
| 要求验证邮箱 | 下载前完成账号验证;打开页面不会授予内容包下载权限。 |
| 要求高级内容权益 | 在账号中检查已确认购买或有效会员;权益缺失时联系客服。 |
| 目标目录已存在 | 选择新目录并保留定制文件。Skillrove CLI 会拒绝覆盖已有目标目录。 |
| 完整性或压缩包校验失败 | 保留错误与版本信息供客服排查。不要关闭校验或运行未完整解压的脚本。 |
预览已修改,但导出没有变化
保存的项目与导出成果是不同文件。在 Product Demo Studio 中,保存编辑后的项目并按说明重新运行构建器,生成新的导出。打开并检查新文件。编辑浏览器预览不会改写已有 MP4。
联系客服时应提供什么?
- 技能名称与版本、助手、操作系统,以及本地还是远程环境。
- 能够复现失败的最小输入,且仅分享你有权提供的内容。
- 第一个错误、预期结果及已尝试的检查,并移除密钥与个人信息。