windows-path-troubleshooting — скилл для Claude Code
Скилл windows-path-troubleshooting объясняет, как записывать пути Windows для Read, Write и Edit и как перевести путь из Git Bash, чтобы не ловить ENOENT.
MIT 199 установок ★ 66 обновлён 2026-06-18
npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-path-troubleshooting -a claude-codeЧто делает windows-path-troubleshooting
Скилл описывает, как обращаться с путями на Windows, когда агент работает через Git Bash. Главное правило: в file_path для Read, Write и Edit идут обратные слэши, то есть D:\repos\project\file.tsx, а не D:/repos/project/file.tsx. Внутри есть таблица перевода MINGW-путей (/c/Users/name/ → C:\Users\name\) и порядок действий, если путь пришёл из вывода pwd.
Отдельные разделы — про пробелы в пути, переменные вроде $HOME, UNC-пути \\server\share и двойной слэш //c/foo. Есть рецепты с MSYS_NO_PATHCONV на случай, когда Git Bash сам переписывает аргументы. Скриптов нет: всё держится на одном SKILL.md с правилами и схемой разбора.
Ломается это предсказуемо. Путь с прямыми слэшами, скопированный из вывода Git Bash, возвращается из Read, Write и Edit как ENOENT: no such file or directory. Правило про обратные слэши записано в тексте скилла, поэтому такие вызовы чинятся через него.
Какие задачи решает
- починить ENOENT, когда путь скопирован из вывода Git Bash
- перевести
/s/repos/appвS:\repos\appперед вызовом Edit - записать путь с пробелами вроде
C:\Program Files\My App\config.jsonбез кавычек - разобрать UNC-путь
\\server\share\file.txtв файловой операции - отключить автоконверт путей Git Bash через
MSYS_NO_PATHCONV
Примеры запросов агенту
- Edit падает с ENOENT на
/s/repos/app/src/Button.tsx— переведи путь в формат Windows и повтори вызов. - Как записать
C:\Program Files\My App\config.jsonв Write, чтобы пробелы не сломали вызов? - Объясни, зачем в путях Git Bash двойной слэш
//c/fooи когда нуженMSYS_NO_PATHCONV.
Как установить windows-path-troubleshooting
1Через Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-path-troubleshooting -a claude-code2Вручную: положить файлы
~/.claude/skills/windows-path-troubleshooting/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/windows-path-troubleshooting/
1Через Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-path-troubleshooting -a codex2Вручную: положить файлы
.agents/skills/windows-path-troubleshooting/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-path-troubleshooting -a cursor2Вручную: положить файлы
.cursor/skills/windows-path-troubleshooting/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install JosiahSiegel/claude-plugin-marketplace plugins/windows-path-master/skills/windows-path-troubleshooting2Вручную: положить файлы
.github/skills/windows-path-troubleshooting/SKILL.md1Через Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-path-troubleshooting -a gemini-cli2Командой платформы
gemini skills install https://github.com/JosiahSiegel/claude-plugin-marketplace --path plugins/windows-path-master/skills/windows-path-troubleshootingВручную: положить файлы
.devin/skills/windows-path-troubleshooting/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-path-troubleshooting -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о windows-path-troubleshooting
Как установить windows-path-troubleshooting в Claude Code?
Выполните npx skills add JosiahSiegel/claude-plugin-marketplace --skill windows-path-troubleshooting -a claude-code. Скилл окажется в ~/.claude/skills/windows-path-troubleshooting/SKILL.md.
Что делает windows-path-troubleshooting?
Разбирает пути Windows для файловых инструментов: где нужны обратные слэши, как перевести MINGW-путь и что делать с пробелами, UNC и переменными окружения.
Почему /s/repos/app не работает в Read и Edit?
Это MINGW-путь Git Bash. Инструментам нужен вид S:\repos\app: буква диска с двоеточием и обратные слэши.
Исходный текст
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