关于 docker-via-wsl
为在 Windows 主机外部 shell 中使用 Docker 的 Agent 提供 WSL 操作指南，说明从 Windows shell 驱动 Docker 可能导致 SMB 路径挂载异常。
主要功能
- 01识别适用的 Windows shell 场景
- 02要求通过 wsl.exe 运行 Docker
- 03使用 WSL 原生 Linux 路径
- 04解释 SMB 挂载路径异常原因
- 05提供诊断与修复参考
适用场景
- 01从 Git Bash 调用 Docker
- 02从 PowerShell 或 cmd 操作容器
- 03排查网络共享目录的挂载错误
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/docker-via-wsl确认已加载。
附带文件references/diagnosis-and-fix.md
详细介绍
在 Windows 上通过 WSL 使用
适用场景
当你——也就是 AI Agent——运行在 Windows 主机上，而你的 shell 处于 WSL 之外时，适用本说明——你的 WSL 是 Git/MSYS（uname -s 显示 MOW64…/MSYS…），或者你处于 cmd 中。那里的 docker 二进制文件会与 Docker Desktop 通信，但守护进程及其文件系统位于 WSL2 中，因此你必须通过 wsl.exe 在 WSL 内运行命令。
如果你的 shell 位于 WSL 内（uname -s 显示 Linux，原生路径为 /home/<user>/...），则本技能不适用——直接运行 docker 即可。
问题
在 Windows 上，Docker Desktop 的守护进程运行在 WSL2 虚拟机内部。请在 WSL 内部、针对原生 Linux 路径执行每一条 docker 命令——包括 run、build、exec、pull、push、volume、network、inspect、compose……绝不要在 Windows shell（Git Bash、MSYS、PowerShell）中运行，尤其是在映射的网络/SMB 驱动器（Z:、UNC \\host\share）上。
为什么重要
从 CWD 位于网络共享上的 Windows shell 驱动 Docker，会迫使 Docker Desktop 将 Windows 绑定路径（例如 Z:\proj\config）转换成一个 WSL 路径。在 SMB/UNC 驱动器上，这种转换不可靠：它可能会重复路径段（例如 …/user/user/proj/config），导致 Docker 挂载一个错误、空目录，并自动把缺失的绑定源创建为空目录。于是容器期望的文件（init.sql、某个配置文件）会显示为目录，并报错 could not read from input file: Is a directory。你的编辑器通过共享写入的内容仍会落在正确路径上，因此宿主机与容器的视图会悄然不一致。
这不是 Docker 缓存 bug，也不是“单文件挂载很脆弱”的问题（从 WSL 中进行单文件绑定完全正常）。根本原因是从 Windows/SMB 而非 WSL 操作 Docker。
规则
通过 WSL、在 Linux 路径中运行任何 Docker 命令：
wsl.exe -e bash -lc "cd /home/<user>/<project> && docker compose up -d"
wsl.exe -e bash -lc "docker ps"
wsl.exe -e bash -lc "docker build -t myimg /home/<user>/<project>"
将项目放在 WSL 发行版原生可见的 Linux 文件系统上（/home/<user>/...），而不要通过盘符访问。
诊断与修复
关于如何检查挂载的路径、比较宿主机与容器的视图，以及清理虚假的绑定目录，请参阅 references/diagnosis-and-fix.md。