该技能用于诊断和解决 run_shell 命令返回“unknown error”或含义不明失败的问题。适用场景包括：run_shell 返回 unknown error、shell 命令失败但无明确错误输出、命令在本地可用但在智能体环境中失败、以及间歇性或无法解释的 shell 失败。
主要排查步骤：第一步，捕获显式 stderr，在命令后追加 2>&1，使错误信息进入输出，例如 run_shell command="some-command 2>&1"。第二步，验证工作目录，运行 run_shell command="pwd && ls -la"，确认所在目录、所需文件或目录是否存在、权限是否正确。第三步，检查工具或命令是否可用，运行 run_shell command="which some-command || command -v some-command || type some-command"，未找到时检查 PATH 或安装所需包。第四步，改用绝对路径，例如 run_shell command="$(pwd)/script.py" 或 /absolute/path/to/script.py。第五步，用最小命令隔离问题，先测试 echo 'test'，再逐步增加命令复杂度。第六步，检查环境变量，运行 run_shell command="env | grep -i relevant_var"。
对于持续出现的 unknown error，可按完整诊断序列执行：抓取完整环境（pwd、ls -la、env），带完整错误捕获测试命令（2>&1 | head -50），检查命令可用性，再用绝对路径尝试。常见原因包括未捕获 stderr、工作目录错误、权限不足、命令未安装或不在 PATH、竞态或时序问题；可分别通过追加 2>&1、用 pwd 验证并使用绝对路径、用 ls -la 检查权限、用 which 检查并安装或指定完整路径、增加延迟或检查文件锁来处理。
最佳实践：调试时始终捕获 stderr；验证对工作目录和文件位置的假设；先简单后复杂；生产或可重复脚本使用绝对路径；行为不一致时检查工具版本；错误难以复现时记录环境。若该流程仍无法解决，问题可能与环境（容器或运行时）相关，可考虑使用 shell_agent 处理需要自主错误处理的复杂 shell 任务，并检查资源限制（磁盘空间、内存、超时）。