Claude Code Skills on Windows: Setup and Fixes (2026)
A. Frans
Published October 12, 2026
Table of Contents
- 01Where skills live on Windows
- 02Installing a skill on Windows
- 03Problem 1: Claude Code needs Git Bash
- 04Problem 2: `bash\r: No such file or directory`
- 05Problem 3: `python3` opens the Microsoft Store
- 06Problem 4: `UnicodeEncodeError` and garbled characters
- 07Problem 5: PowerShell writes files Claude can't read cleanly
- 08Problem 6: Mac-only commands in the instructions
- 09Problem 7: symlinks and long paths
- 10A Windows-friendly checklist for skill authors
- 11Where Windows still lags
- 12FAQ
Claude Code skills are written on Macs and tested on Macs, and most of them work on Windows anyway. The ones that break tend to break in the same five or six ways: a shell script with Windows line endings, a python3 call that opens the Microsoft Store, a file saved with a byte-order mark, a path that assumes forward slashes. None of these are Claude's fault and all of them are fixable in a few minutes once you know what you're looking at.
We run a few dozen skills daily on a Windows 11 machine, and this guide is the list we wish we'd had on day one.
Where skills live on Windows
| Scope | macOS / Linux path | Windows path |
|---|---|---|
| Personal (all projects) | ~/.claude/skills/<name>/SKILL.md | C:\Users\<you>\.claude\skills\<name>\SKILL.md |
| Project (shared via git) | .claude/skills/<name>/SKILL.md | <repo>\.claude\skills\<name>\SKILL.md |
| Plugin skills | managed by /plugin | managed by /plugin, stored under C:\Users\<you>\.claude\plugins\ |
.claude folder starts with a dot, and File Explorer shows it like any other folder, so you can create it by hand. In Git Bash or PowerShell, ~ resolves to C:\Users\<you>, so ~/.claude/skills works in both.
One trap: if you also use WSL, the Linux side has its own home directory. A skill in \\wsl$\Ubuntu\home\you\.claude\skills is invisible to Claude Code running natively on Windows, and the reverse is true too. Pick one environment and install skills there.
Installing a skill on Windows
The manual route is the same as on any OS: put the skill's folder in your skills directory. From Git Bash:
git clone https://github.com/anthropics/skills.git ~/anthropic-skills
mkdir -p ~/.claude/skills
cp -r ~/anthropic-skills/skills/pdf ~/.claude/skills/pdf
From PowerShell:
git clone https://github.com/anthropics/skills.git $HOME\anthropic-skills
New-Item -ItemType Directory -Force $HOME\.claude\skills
Copy-Item -Recurse $HOME\anthropic-skills\skills\pdf $HOME\.claude\skills\pdf
Restart Claude Code or start a new session, then ask for something the skill covers. That example installs Anthropic's PDF skill. If you'd rather go through the plugin system, /plugin inside Claude Code handles marketplaces the same way on every OS.
Before you install anything from a stranger's repo, read the SKILL.md and every script in it. Our 10-minute audit checklist covers what to look for.
Problem 1: Claude Code needs Git Bash
Native Windows Claude Code runs shell commands through Git Bash, so you need Git for Windows installed. If Claude Code can't find it, set the path explicitly:
$env:CLAUDE_CODE_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe"
Set it permanently through System Properties > Environment Variables if that fixes it. This matters for skills because most skills tell Claude to run commands, and those commands assume a Unix-like shell. Git Bash gives you ls, cp, grep and find, so a skill written on a Mac usually runs unchanged.
Usually. The rest of this list is the "usually."
Problem 2: bash\r: No such file or directory
This is the classic. A skill ships a .sh script, Git on Windows checks it out with CRLF line endings, and bash reads the first line as #!/usr/bin/env bash\r. The error mentions \r or $'\r': command not found.
Fix the file:
sed -i 's/\r$//' ~/.claude/skills/<name>/scripts/*.sh
Then stop it happening again. If you maintain the skill, add a .gitattributes to the repo:
*.sh text eol=lf
*.py text eol=lf
*.md text eol=lf
CRLF also bites outside scripts. We publish this site's articles from a Windows machine, and a batch drafted with CRLF line endings once rendered every Markdown table as a paragraph of literal pipe characters. If a skill outputs Markdown that looks wrong, check line endings before anything else.
Problem 3: python3 opens the Microsoft Store
Many skills call python3 scripts/something.py. On Windows, the Python installer from python.org gives you python and the py launcher, and python3 often resolves to a Store shortcut that does nothing useful.
Two fixes, pick one:
- Turn off the shortcut in Settings > Apps > Advanced app settings > App execution aliases, then make sure your real Python is on PATH.
- Tell Claude once, in your personal
CLAUDE.md: "On this machine, usepython, notpython3." Claude reads that file every session and adjusts the commands the skill suggests.
The second fix is faster and survives reinstalls.
Problem 4: UnicodeEncodeError and garbled characters
Python on Windows has long defaulted to the system code page (often cp1252) when a script opens a file without saying which encoding to use. A skill script that reads a UTF-8 file containing emoji, curly quotes or non-Latin text then crashes with UnicodeDecodeError, or writes mojibake like ’ where an apostrophe should be.
The quick fix is one environment variable, which switches Python into UTF-8 mode:
setx PYTHONUTF8 1
Open a new terminal afterwards. If you write skills, pass encoding="utf-8" to every open() call. It costs nothing and removes the whole class of bug for your Windows users.
Problem 5: PowerShell writes files Claude can't read cleanly
Windows PowerShell 5.1 (the one that ships with Windows) writes UTF-16 by default when you use > or Out-File, and its -Encoding utf8 option adds a byte-order mark. That's harmless for most files. In a SKILL.md, an invisible BOM before the opening --- can stop the frontmatter from being recognized, and then the skill has no name or description as far as Claude is concerned.
If you edit SKILL.md files, use an editor (VS Code saves UTF-8 without BOM by default) or PowerShell 7, which defaults to BOM-less UTF-8. To check an existing file from Git Bash:
head -c 3 SKILL.md | od -An -tx1
If it prints ef bb bf, there's a BOM. Strip it with sed -i '1s/^\xEF\xBB\xBF//' SKILL.md.
A skill whose frontmatter fails to parse looks exactly like a skill that won't trigger. If you're debugging that, our triggering guide covers the other causes, and the frontmatter fields explainer shows what valid frontmatter looks like.
Problem 6: Mac-only commands in the instructions
Some skills tell Claude to run open file.html, pbcopy, brew install or say. Those don't exist on Windows. Claude will often notice and substitute (start for open, clip for pbcopy), but not always, and a skill that depends on a Homebrew package needs a Windows equivalent installed some other way.
Read the skill before installing and search for these. If you find one, either add a line to your CLAUDE.md ("this is Windows; use start instead of open") or fork the skill and fix the instruction.
Problem 7: symlinks and long paths
Skills that symlink shared files between folders can fail on Windows, where creating symlinks needs Developer Mode or admin rights. Turn on Developer Mode (Settings > System > For developers) and set git config --global core.symlinks true before cloning.
Skills that bundle a Node project can also hit the old 260-character path limit inside node_modules. Enable long paths with git config --global core.longpaths true, and for Windows itself through the LongPathsEnabled registry setting or Group Policy.
A Windows-friendly checklist for skill authors
If you publish skills, five habits make them work for Windows users without extra effort:
1. Call scripts as python scripts/x.py, and mention that python3 may need to be python. 2. Use encoding="utf-8" on every file open. 3. Ship a .gitattributes that pins scripts to LF. 4. Avoid macOS-only commands in instructions, or give the Windows alternative next to them. 5. Use pathlib or os.path.join in Python instead of hard-coded / separators.
The writing guide in Anthropic's Skill Creator and the Writing Skills meta-skill both help you structure a skill, but neither tests on Windows for you. Ask a Windows user to install it once before you call it done. We cover the rest of the authoring workflow in how to write your first Claude Code skill.
Where Windows still lags
Skills themselves are plain Markdown and work everywhere. The friction lives in the scripts and shell commands skills carry, which were mostly written on Macs. Once Git Bash is set up, Python is UTF-8 and line endings are pinned, the remaining breakage is rare. Our own setup runs skills for PDF work, spreadsheets, video editing and browser automation without a Mac anywhere in the loop.
If you want Claude to control Windows apps directly rather than through a shell, look at Windows MCP, an MCP server for computer use on Windows. Developers can find more tooling on our full list for developers.
FAQ
Do Claude Code skills work on Windows?
Yes. Skills are Markdown files in a folder, so Claude Code reads them on any OS. Problems come from the scripts some skills bundle, which may assume macOS or Linux. Installing Git for Windows and fixing line endings and Python encoding resolves most of them.
Where is the Claude Code skills folder on Windows?
Personal skills go in C:\Users\<your-username>\.claude\skills\, one folder per skill with a SKILL.md inside. Project skills go in .claude\skills\ at the root of the repository.
Why does my skill script fail with a \r error on Windows?
The script has Windows (CRLF) line endings, and bash reads the carriage return as part of the command. Convert it with sed -i 's/\r$//' script.sh and add a .gitattributes rule like *.sh text eol=lf to stop it recurring.
Should I use WSL or native Windows for Claude Code skills?
Either works, but don't mix them. WSL has its own home directory, so skills installed there aren't visible to Claude Code running natively on Windows. If most of your skills run bash and Linux tools, WSL causes fewer surprises.
How do I stop a skill from calling python3 on Windows?
Disable the python3 app execution alias in Windows Settings, or add a line to your personal CLAUDE.md telling Claude to use python instead of python3 on this machine.
Share this article
⚙Related Tools
📄Related Articles
Get More AI Tool Guides
New comparisons and guides every week. Join thousands of professionals staying ahead of the AI curve.