windows-path-troubleshooting — Claude Code skill: Windows path fixes
windows-path-troubleshooting — a skill that tells the agent how to write Windows paths for Read, Write and Edit, and how to convert Git Bash paths that end in ENOENT.
MIT 199 installs ★ 66 updated 2026-06-18
npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-path-troubleshooting -a claude-codeWhat windows-path-troubleshooting does
The skill covers the space between Git Bash and the file tools on Windows. Its hard rule: pass backslashes in file_path, so D:\repos\project\file.tsx, not D:/repos/project/file.tsx. A conversion table maps MINGW forms such as /c/Users/name/ to C:\Users\name\, and a decision tree helps the agent work out which form it was handed.
Smaller sections deal with spaces inside paths, $HOME-style variables, UNC shares like \\server\share\folder\file.txt and the double-slash escape //c/foo. There are recipes for MSYS_NO_PATHCONV too, for the cases where Git Bash rewrites arguments by itself. No scripts ship with it; everything sits in one SKILL.md.
What breaks is predictable. A forward-slash path copied from Git Bash output comes back from Read, Write and Edit as ENOENT: no such file or directory. The backslash rule that prevents it is written into the skill text.
What it helps with
- fix ENOENT after pasting a path from Git Bash output
- turn
/s/repos/appintoS:\repos\appbefore an Edit call - pass a path with spaces like
C:\Program Files\My App\config.jsonto Write - work with a UNC share such as
\\server\share\file.txt - switch off MSYS path conversion for a single command
Example prompts for the agent
- My Edit call failed with ENOENT on
/s/repos/app/src/Button.tsx; convert that to a Windows path and retry. - How do I pass
C:\Program Files\My App\config.jsonto Write without the spaces breaking it? - Explain the
//c/foodouble-slash form and when to setMSYS_NO_PATHCONV.
How to install windows-path-troubleshooting
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-path-troubleshooting -a claude-code2Manually: put the files in place
~/.claude/skills/windows-path-troubleshooting/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/windows-path-troubleshooting/
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-path-troubleshooting -a codex2Manually: put the files in place
.agents/skills/windows-path-troubleshooting/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-path-troubleshooting -a cursor2Manually: put the files in place
.cursor/skills/windows-path-troubleshooting/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install JosiahSiegel/claude-plugin-marketplace plugins/windows-path-master/skills/windows-path-troubleshooting2Manually: put the files in place
.github/skills/windows-path-troubleshooting/SKILL.md1Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-path-troubleshooting -a gemini-cli2Platform CLI
gemini skills install https://github.com/JosiahSiegel/claude-plugin-marketplace --path plugins/windows-path-master/skills/windows-path-troubleshootingManually: put the files in place
.devin/skills/windows-path-troubleshooting/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-path-troubleshooting -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about windows-path-troubleshooting
How do I install windows-path-troubleshooting in Claude Code?
Run npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-path-troubleshooting -a claude-code. The skill lands in ~/.claude/skills/windows-path-troubleshooting/SKILL.md.
What does windows-path-troubleshooting do?
It gives the agent rules for Windows file paths: when to use backslashes, how to convert Git Bash paths, and how to handle spaces, UNC shares and environment variables.
Why does /s/repos/app fail in Read or Edit?
That is a MINGW path from Git Bash. The tools want S:\repos\app, with the drive letter and backslashes.
Source text
SKILL.md · MIT
--- name: windows-path-troubleshooting description: | Complete Windows file path troubleshooting knowledge for Claude Code on Git Bash and Windows environments. PROACTIVELY activate for: (1) file path errors on Windows, (2) backslash vs forward slash issues, (3) Edit/Write/Read tool failures, (4) MINGW path resolution, (5) cross-platform path conversion, (6) MSYS_NO_PATHCONV usage, (7) double-slash escape patterns (//c/foo), (8) UNC and long path limits, (9) WSL vs native Windows interop. Provides: path-conversion rules, troubleshooting flowchart, MSYS env-var recipes, double-slash escape patterns, and Windows file-operation best practices. --- ## 🚨 CRITICAL GUIDELINES ### Windows File Path Requirements **MANDATORY: Always Use Backslashes on Windows for File Paths** When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`). **Examples:** - ❌ WRONG: `D:/repos/project/file.tsx` - ✅ CORRECT: `D:\repos\project\file.tsx` This applies to: - Edit tool file_path parameter - Write tool file_path parameter - All file operations on Windows systems ### Documentation Guidelines **NEVER create new documentation files unless explicitly requested by the user.** - **Priority**: Update existing README.md files rather than creating new documentation - **Repository cleanliness**: Keep repository root clean - only README.md unless user requests otherwise - **Style**: Documentation should be concise, direct, and professional - avoid AI-generated tone - **User preference**: Only create additional .md files when user specifically asks for documentation --- # Windows Path Troubleshooting for Claude Code ## 🚨 CRITICAL: Always Use Backslashes on Windows for File Paths **MANDATORY: When using Edit, Write, or Read tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`).** ### The Rule **Windows File Path Requirements:** - ✅ **CORRECT**: `D:\repos\project\file.tsx` - ❌ **WRONG**: `D:/repos/project/file.tsx` **This applies to:** - Edit tool `file_path` parameter - Write tool `file_path` parameter - Read tool `file_path` parameter - All file operations on Windows systems ### Why This Matters **Common error message when using forward slashes on Windows:** ```text Error: ENOENT: no such file or directory ``` **Root cause:** - Windows native file system uses backslashes (`\`) as path separators - Forward slashes (`/`) work in some Windows contexts but NOT in Claude Code file tools - Git Bash displays paths with forward slashes but Windows APIs require backslashes - Claude Code's Read/Write/Edit tools use Windows native APIs that expect backslashes ## 🔍 Common Windows Path Issues in Claude Code ### Issue 1: Forward Slashes in Tool Calls **Symptom:** ```text Edit tool fails with "file not found" or "no such file or directory" ``` **Cause:** Using forward slashes copied from Git Bash output: ```bash # Git Bash shows: /s/repos/claude-plugin-marketplace/file.tsx ``` **Incorrect usage:** ```text Edit(file_path="/s/repos/myproject/file.tsx") ``` **Correct usage:** ```text Edit(file_path="S:\repos\myproject\file.tsx") ``` **Solution steps:** 1. Identify the Windows drive letter (e.g., `/s/` → `S:`) 2. Replace forward slashes with backslashes 3. Add drive letter with colon 4. Use absolute Windows path format ### Issue 2: Git Bash MINGW Path Format **Symptom:** Paths like `/s/repos/` or `/c/Users/` don't work in Edit/Write/Read tools **MINGW path format explained:** - Git Bash uses POSIX-style paths on Windows - Drive letters are represented as `/c/`, `/d/`, `/s/`, etc. - These are MINGW virtual paths, not Windows paths - Claude Code tools need Windows-native paths **Conversion table:** | Git Bash (MINGW) | Windows Native | |------------------|----------------| | `/c/Users/name/` | `C:\Users\name\` | | `/d/repos/project/` | `D:\repos\project\` | | `/s/work/code/` | `S:\work\code\` | | `/mnt/c/Windows/` | `C:\Windows\` | **Conversion algorithm:** 1. Extract drive letter from first path segment (e.g., `/s/` → `S`) 2. Add colon to drive letter (e.g., `S` → `S:`) 3. Replace remaining forward slashes with backslashes 4. Combine: `S:` + `\repos\project\file.tsx` ### Issue 3: Relative Paths in Git Bash **Symptom:** Relative paths from Git Bash don't resolve correctly in Claude Code tools **Cause:** Git Bash current working directory uses MINGW format, but Claude Code tools use Windows format **Example scenario:** ```bash # In Git Bash: pwd # Shows: /s/repos/my-project # User provides relative path: ./src/components/Button.tsx ``` **Problem:** Claude Code can't resolve `./src/` from MINGW `/s/repos/my-project` **Solution:** 1. Get the full Windows path from Git Bash: ```bash pwd -W # Shows: S:/repos/my-project (Windows format with forward slashes) ``` 2. Convert to proper Windows path: `S:\repos\my-project` 3. Append relative path with backslashes: `S:\repos\my-project\src\components\Button.tsx` ### Issue 4: Environment Variable Expansion **Symptom:** Paths with environment variables like `$HOME` or `%USERPROFILE%` fail **Git Bash environment variables:** ```bash echo $HOME # Shows: /c/Users/username (MINGW format) ``` **Windows environment variables:** ```cmd echo %USERPROFILE% # Shows: C:\Users\username (Windows format) ``` **Best practice:** - Avoid environment variables in file paths for Claude Code tools - Use absolute Windows paths instead - If user provides `$HOME`, ask them to run `echo $HOME` and convert the result ### Issue 5: Spaces in File Paths **Symptom:** Paths with spaces break or cause "file not found" errors **Correct handling:** ```text ✅ CORRECT: Edit(file_path="C:\Program Files\My App\config.json") ✅ CORRECT: Edit(file_path="D:\My Documents\project\file.txt") ``` **Notes:** - Do NOT add quotes around the path in the parameter - The tool call itself handles escaping - Spaces are fine in Windows paths when using backslashes ### Issue 6: UNC Network Paths **Symptom:** Network paths like `\\server\share\file.txt` fail **Windows UNC format:** ```text \\server\share\folder\file.txt ``` **Git Bash representation:** ```text //server/share/folder/file.txt ``` **Correct usage in Claude Code:** ```text Edit(file_path="\\\\server\\share\\folder\\file.txt") ``` **Note:** Backslashes must be doubled in some contexts due to escaping, but Claude Code tools handle this automatically. ## 🔧 Path Detection and Conversion Algorithm When a user provides a file path, follow this decision tree: ### Step 1: Identify Path Format **MINGW Path (Git Bash):** - Starts with `/` followed by single letter and `/` (e.g., `/c/`, `/s/`) - Example: `/s/repos/project/file.tsx` - **Action:** Convert to Windows format **Windows Path:** - Starts with drive letter and colon (e.g., `C:`, `D:`) - Uses backslashes or forward slashes - Example: `S:\repos\project\file.tsx` or `S:/repos/project/file.tsx` - **Action:** Ensure backslashes are used **Relative Path:** - Starts with `./` or `../` or just filename - Example: `./src/components/Button.tsx` - **Action:** Request full path from user or detect current directory **UNC Path:** - Starts with `\\` or `//` - Example: `\\server\share\file.txt` - **Action:** Ensure backslashes are used ### Step 2: Conversion Process **For MINGW paths (`/x/...`):** ```text Input: /s/repos/myproject/src/components/Button.tsx Process: 1. Extract drive letter: "s" 2. Uppercase: "S" 3. Add colon: "S:" 4. Replace remaining slashes: \repos\myproject\src\components\Button.tsx 5. Combine: S:\repos\myproject\src\components\Button.tsx Output: S:\repos\myproject\src\components\Button.tsx ``` **For Windows paths with forward slashes (`X:/...`):** ```text Input: S:/repos/project/file.tsx Process: 1. Detect drive letter already present: "S:" 2. Replace forward slashes with backslashes: \repos\project\file.tsx 3. Combine: S:\repos\project\file.tsx Output: S:\repos\project\file.tsx ``` **For relative paths:** ```text Input: ./src/components/Button.tsx Current directory (from user or detection): S:\repos\my-project Process: 1. Remove ./ prefix 2. Replace forward slashes: src\components\Button.tsx 3. Combine with current directory: S:\repos\my-project\src\components\Button.tsx Output: S:\repos\my-project\src\components\Button.tsx ``` ## 🛠️ Interactive Path Fixing Workflow When you encounter a file path error on Windows: ### Step 1: Detect the Error **Error indicators:** - "ENOENT: no such file or directory" - "file not found" - Edit/Write/Read tool failure - User mentions "Windows" or "Git Bash" ### Step 2: Analyze the Path **Ask yourself:** 1. Was the path provided by the user in MINGW format? 2. Does the path use forward slashes? 3. Is it a relative path? 4. Did I receive the path from a Git Bash command output? ### Step 3: Request Clarification (If Needed) **If the path is ambiguous, ask:** ```bash I see you're working on Windows with Git Bash. To ensure I use the correct path format, could you run this command and share the output? pwd -W This will give me the Windows-formatted path. ``` ### Step 4: Convert and Retry **Conversion template:** ```text I'll convert the path from Git Bash format to Windows format: - Git Bash: /s/repos/project/file.tsx - Windows: S:\repos\project\file.tsx Retrying with the correct Windows path... ``` ### Step 5: Verify Success After conversion, verify the operation succeeded and explain what was fixed: ```text ✅ Successfully edited the file using the Windows path format (S:\repos\...). Note: On Windows with Git Bash, always use backslashes (\) in file paths for Claude Code's Edit/Write/Read tools, even though Git Bash displays paths with forward slashes (/). ``` ## 📋 Troubleshooting Checklist When file operations fail on Windows: - [ ] **Check path separator**: Are backslashes (`\`) used instead of forward slashes (`/`)? - [ ] **Check drive letter format**: Is it `C:` not `/c/`? - [ ] **Check MINGW conversion**: Did you convert `/x/path` to `X:\path`? - [ ] **Check relative vs absolute**: Is the path absolute starting with drive letter? - [ ] **Check environment variables**: Did you expand `$HOME` or `%USERPROFILE%`? - [ ] **Check spaces**: Are spaces in the path handled correctly? - [ ] **Check UNC paths**: Are network paths using `\\server\share` format? - [ ] **Check file existence**: Does the file actually exist at that path? ## 🎯 Quick Reference: Path Conversion Examples | Context | Path Format | Claude Code Tool Format | |---------|-------------|-------------------------| | Git Bash pwd | `/s/repos/project` | `S:\repos\project` | | Git Bash relative | `./src/file.tsx` | `S:\repos\project\src\file.tsx` | | Windows Explorer | `S:\repos\project\file.tsx` | `S:\repos\project\file.tsx` ✅ | | Windows with `/` | `S:/repos/project/file.tsx` | `S:\repos\project\file.tsx` | | MINGW full path | `/c/Users/name/file.txt` | `C:\Users\name\file.txt` | | Network share (Git Bash) | `//server/share/file.txt` | `\\server\share\file.txt` | | WSL path | `/mnt/c/repos/project` | `C:\repos\project` | ## 🚀 Best Practices for Windows File Operations ### 1. Always Convert Paths Proactively **Don't wait for errors** - If you see a path that looks like MINGW format, convert it immediately: ```text User provides: /s/repos/project/file.tsx You think: "This is MINGW format, I need to convert it to S:\repos\project\file.tsx" You do: Convert before calling Edit/Write/Read tool ``` ### 2. Use pwd -W in Git Bash **When you need current directory on Windows:** ```bash # Instead of: pwd # Shows: /s/repos/project (MINGW format) # Use: pwd -W # Shows: S:/repos/project (Windows format with /) ``` Then convert the forward slashes to backslashes. ### 3. Communicate Path Format Changes **Always explain when you convert paths:** ```text I'll convert the Git Bash path to Windows format for the Edit tool: - From: /s/repos/project/file.tsx - To: S:\repos\project\file.tsx ``` This helps users understand the requirement and learn for future interactions. ### 4. Validate Before Tool Use **Before calling Edit/Write/Read tools on Windows:** ```text Pre-flight checklist: ✅ Path starts with drive letter and colon (e.g., C:, S:) ✅ Path uses backslashes (\) not forward slashes (/) ✅ Path is absolute, not relative ✅ No MINGW format (no /c/, /s/, etc.) ``` ### 5. Handle User-Provided Paths Carefully **User might provide paths in various formats:** - Copy-pasted from Git Bash (MINGW format) - Copy-pasted from Windows Explorer (Windows format) - Typed manually (could be either) - From command output (varies by tool) **Always detect and convert as needed.** ## Error Lookup, Platform Notes, User Teaching & Advanced Scenarios Detailed lookup tables for common Claude Code Windows path errors, platform-specific behavior (PowerShell, CMD, Git Bash, WSL, Node/Python), user-teaching scripts, and advanced path scenarios (UNC paths, long paths, spaces, special characters) live in `references/error-platform-advanced.md`. Load that reference when the quick conversion workflow does not explain a path failure. ## ✅ Success Criteria You've successfully handled Windows paths when: 1. ✅ All Edit/Write/Read tool calls use backslashes on Windows 2. ✅ MINGW paths are converted before tool use 3. ✅ Relative paths are resolved to absolute Windows paths 4. ✅ User understands why conversion was necessary 5. ✅ File operations succeed without path-related errors 6. ✅ Path format is consistent throughout the session ## 🆘 When to Use This Skill **PROACTIVELY apply this knowledge when:** 1. User mentions they're on Windows 2. User mentions Git Bash or MINGW 3. You see paths starting with `/c/`, `/s/`, etc. 4. Edit/Write/Read tool fails with "file not found" 5. User provides paths with forward slashes on Windows 6. You need to read/edit/write files on Windows system **This skill is CRITICAL for Windows users** - Path format errors are the #1 cause of file operation failures on Windows with Git Bash.
© JosiahSiegel · MIT · JosiahSiegel/claude-plugin-marketplace