windows-path-troubleshooting

What this skill does

## 🚨 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 t