Agent-almanac setup-wsl-dev-environment

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/wenyan/skills/setup-wsl-dev-environment" ~/.claude/skills/pjt222-agent-almanac-setup-wsl-dev-environment-f940c6 && rm -rf "$T"

manifest: i18n/wenyan/skills/setup-wsl-dev-environment/SKILL.md

source content

Set Up WSL Development Environment

Configure a complete WSL2 development environment for cross-platform work.

When to Use

Setting up a new Windows machine for development
Configuring WSL2 for the first time
Adding development tools to an existing WSL installation
Setting up cross-platform workflows (WSL + Windows tools)

Inputs

Required: Windows 10/11 with WSL2 support
Optional: Preferred Linux distribution (default: Ubuntu)
Optional: Languages to set up (Node.js, Python, R)
Optional: Additional tools (Docker, tmux, fzf)

Procedure

Step 1: Install WSL2

In PowerShell (Administrator):

wsl --install
wsl --set-default-version 2

Restart if prompted. Ubuntu installs by default.

Expected: After reboot,

wsl --list --verbose

shows the distribution running under WSL version 2. The

wsl

command opens a Linux shell.

On failure: If WSL2 installation fails, enable the "Virtual Machine Platform" and "Windows Subsystem for Linux" Windows features manually via

optionalfeatures.exe

. On older Windows 10 builds, a kernel update may be required from Microsoft.

Step 2: Configure WSL Resource Limits

Create

~/.wslconfig

in Windows home directory:

[wsl2]
memory=8GB
processors=4
localhostForwarding=true

Expected: The

.wslconfig

file exists in the Windows user home directory (e.g.,

C:\Users\Name\.wslconfig

). After running

wsl --shutdown

and restarting WSL, resource limits are applied.

On failure: If the config has no effect, verify the file is in the correct location (Windows home, not WSL home). Run

wsl --shutdown

and reopen WSL for changes to take effect.

Step 3: Update and Install Essentials

sudo apt update && sudo apt upgrade -y
sudo apt install -y \
  build-essential \
  curl \
  wget \
  git \
  git-lfs \
  vim \
  htop \
  tree \
  jq \
  ripgrep \
  fd-find \
  unzip \
  zip

Create useful aliases:

echo 'alias fd="fdfind"' >> ~/.bashrc

Expected: All packages install without errors. Commands like

git --version

jq --version

rg --version

, and

tree

execute successfully.

On failure: If

apt install

fails, run

sudo apt update

first to refresh package lists. For packages not found, check that the Ubuntu version supports them or install from alternative sources (e.g., snap, cargo, or manual download).

Step 4: Configure Git

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
git config --global init.defaultBranch main
git config --global core.autocrlf input
git config --global color.ui auto
git config --global core.editor vim

Expected:

git config --list

shows the correct user name, email, default branch (

main

), autocrlf (

input

), and editor settings.

On failure: If settings are not applied, verify you used

--global

(not

--local

which only applies to the current repo). Check that

~/.gitconfig

contains the expected entries.

Step 5: Set Up SSH Keys

ssh-keygen -t ed25519 -C "your.email@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub
# Add to GitHub: Settings > SSH and GPG keys

Test:

ssh -T git@github.com

Expected:

ssh -T git@github.com

returns "Hi username! You've successfully authenticated." The SSH key pair exists at

~/.ssh/id_ed25519

and

~/.ssh/id_ed25519.pub

On failure: If authentication fails, verify the public key was added to GitHub (Settings > SSH and GPG keys). Check that

ssh-agent

is running and the key is loaded with

ssh-add -l

. If the agent is not running, add

eval "$(ssh-agent -s)"

~/.bashrc

Step 6: Install Node.js (via nvm)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts

Expected:

node --version

and

npm --version

return current LTS versions.

nvm ls

shows the installed version marked as default.

On failure: If

nvm

is not found after installation, source

~/.bashrc

or open a new terminal. If the install script fails, download and run it manually after reviewing the script contents.

Step 7: Install Python (via pyenv)

# Install build dependencies
sudo apt install -y make libssl-dev zlib1g-dev libbz2-dev \
  libreadline-dev libsqlite3-dev libncursesw5-dev xz-utils \
  tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

curl https://pyenv.run | bash

# Add to ~/.bashrc
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc

pyenv install 3.12
pyenv global 3.12

Expected:

python --version

returns Python 3.12.x.

pyenv versions

shows the installed version set as global.

On failure: If

pyenv install

fails with build errors, ensure all build dependencies from the

apt install

command were installed. Missing libraries (especially

libssl-dev

zlib1g-dev

) are the most common cause of Python build failures.

Step 8: Configure Shell

Add to

~/.bashrc

# History
export HISTSIZE=10000
export HISTFILESIZE=20000
export HISTCONTROL=ignoredups:erasedups
shopt -s histappend

# Navigation aliases
alias ll='ls -alF'
alias la='ls -A'
alias ..='cd ..'
alias ...='cd ../..'

# Development paths
export DEV_HOME="/mnt/d/dev/p"
alias dev='cd $DEV_HOME'

# Functions
mkcd() { mkdir -p "$1" && cd "$1"; }

# PATH additions
export PATH="$HOME/bin:$HOME/.local/bin:$PATH"

Expected: After running

source ~/.bashrc

, all aliases (

ll

la

..

dev

) work, the

mkcd

function creates and enters directories, and

$DEV_HOME

points to the development directory.

On failure: If aliases are not available, verify the additions were appended to

~/.bashrc

(not

~/.bash_profile

~/.profile

). Run

source ~/.bashrc

to reload without opening a new terminal.

Step 9: Set Up Claude Code CLI

# Add Claude CLI to PATH (after installation)
echo 'export PATH="$HOME/.claude/local/node_modules/.bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify
which claude

Expected:

which claude

returns the path to the Claude Code CLI binary (e.g.,

~/.claude/local/node_modules/.bin/claude

). Running

claude --version

prints the installed version.

On failure: If

claude

is not found, verify the PATH export was added to

~/.bashrc

and sourced. Check that Claude Code is actually installed at

~/.claude/local/

. If not installed, follow the Claude Code installation instructions first.

Step 10: Cross-Platform Path Reference

Windows	WSL
`C:\Users\Name`	`/mnt/c/Users/Name`
`D:\dev\projects`	`/mnt/d/dev/projects`
`%APPDATA%`	`/mnt/c/Users/Name/AppData/Roaming`

Open Windows Explorer from WSL:

explorer.exe .

Expected: The path conversion table is understood and tested: accessing a Windows path from WSL works (e.g.,

ls /mnt/c/Users/

), and

explorer.exe .

opens Windows Explorer to the current WSL directory.

On failure: If

/mnt/c/

is not accessible, verify WSL's automount is configured. Check

/etc/wsl.conf

for

[automount]

settings. Run

wsl --shutdown

and restart if mount points are stale.

Validation

WSL2 running with correct distribution
Git configured with correct identity
SSH key added to GitHub and connection verified
Node.js installed and working
Python installed and working
Shell aliases and functions work
Claude Code CLI accessible

Common Pitfalls

Slow file access on
/mnt/
: Store frequently accessed projects in WSL filesystem (
```
~/
```
) for better performance. Use
```
/mnt/
```
for projects shared with Windows tools.
Line endings:
```
core.autocrlf=input
```
prevents CRLF issues. Configure editors to use LF.

Permission issues: Files on

/mnt/

may show incorrect permissions. Add to

/etc/wsl.conf

[automount]\noptions = "metadata,umask=22,fmask=11"

Windows Defender: Exclude WSL directories from real-time scanning for better performance.

Related Skills

```
configure-git-repository
```
- detailed Git repository setup
```
configure-mcp-server
```
- MCP setup requires WSL environment
```
write-claude-md
```
- configure AI assistant for projects