admin/claude-agents

Fork 0

Files

admin 6bc800dfc1 Add WSL setup guide with shared and separate strategies

2026-01-29 17:00:26 +00:00

12 KiB

Raw Permalink Blame History

WSL (Windows Subsystem for Linux) Sync Guide

Complete guide for syncing Claude Code agents and skills using WSL on Windows.

🎯 Why WSL is Better Than Native Windows

✅ Same commands as Linux - No path conversions or PowerShell/Batch differences
✅ Native curl/git - Skillshare installs with one command
✅ Better performance - Git operations are faster
✅ Consistent with server - Same environment as server-ai
✅ Easy shell scripts - Bash scripts work as-is

📋 Prerequisites

Install WSL (If Not Already Installed)

# In PowerShell as Administrator
wsl --install

# Or install specific distro
wsl --install -d Ubuntu-22.04

# Reboot Windows

Verify WSL Installation

# Check WSL version (should be WSL 2)
wsl --version

# Enter WSL
wsl

# Check distro
cat /etc/os-release

🔀 Two Setup Strategies

Strategy 1: Shared (Recommended)

WSL and Windows Claude Code share the same skills/agents

Use when:

You use Claude Code in both WSL and Windows
Want consistency across both environments
Don't want duplicate files

Strategy 2: Separate

WSL has independent skills/agents, syncs separately

Use when:

Only use Claude Code in WSL or Windows, not both
Need different skills for different environments
Want complete isolation

🔗 Strategy 1: Shared Setup (WSL + Windows)

Step 1: Install in Windows First

Follow the Windows guide to set up agents/skills in Windows:

Agents: C:\Users\YourName\.claude\agents
Skills: C:\Users\YourName\.config\skillshare\skills

Step 2: Create Symlinks in WSL

# In WSL - Replace YourName with your Windows username

# Create .claude directory if it doesn't exist
mkdir -p ~/.claude

# Symlink agents (WSL points to Windows)
ln -s /mnt/c/Users/YourName/.claude/agents ~/.claude/agents

# Symlink skills target (for Claude Code in WSL)
ln -s /mnt/c/Users/YourName/.claude/skills ~/.claude/skills

# Symlink Skillshare source directory
mkdir -p ~/.config
ln -s /mnt/c/Users/YourName/.config/skillshare ~/.config/skillshare

Step 3: Verify Symlinks

# Check symlinks
ls -la ~/.claude/
ls -la ~/.config/

# Should show:
# agents -> /mnt/c/Users/YourName/.claude/agents
# skills -> /mnt/c/Users/YourName/.claude/skills
# skillshare -> /mnt/c/Users/YourName/.config/skillshare

Step 4: Install Skillshare in WSL (Optional)

# If you want to run skillshare commands from WSL
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh

# Test
skillshare status

Step 5: Daily Sync (From WSL)

# Pull agents (from WSL)
cd ~/.claude/agents  # Actually points to Windows directory
git pull origin main

# Pull skills (from WSL)
skillshare pull --remote  # Updates Windows skillshare directory

How it works:

Both WSL and Windows Claude Code read from same directories
Changes in WSL appear instantly in Windows (and vice versa)
Git sync updates both environments automatically

🔧 Strategy 2: Separate Setup (WSL Only)

Step 1: Install Git in WSL

# Update packages
sudo apt update

# Install git
sudo apt install git -y

# Configure git
git config --global user.name "admin"
git config --global user.email "admin@server-ai.local"
git config --global init.defaultBranch main

Step 2: Clone Agents

# Clone agents to WSL
git clone https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-agents.git ~/.claude/agents

# Verify
ls ~/.claude/agents/

Step 3: Install Skillshare

# Install Skillshare
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh

# Verify
skillshare version

Step 4: Setup Skills

# Initialize Skillshare
skillshare init --no-copy --all-targets --git

# Add remote
cd ~/.config/skillshare/skills
git remote add origin https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-skills.git

# Pull skills
skillshare pull --remote

# Verify
skillshare status

Step 5: Daily Sync

# Same as Linux commands - pull agents
cd ~/.claude/agents && git pull

# Pull skills
skillshare pull --remote

🗂️ Understanding WSL Paths

Accessing Windows from WSL

# Windows C: drive
/mnt/c/

# Windows user directory
/mnt/c/Users/YourName/

# Windows Claude directory
/mnt/c/Users/YourName/.claude/

# Windows Documents
/mnt/c/Users/YourName/Documents/

Accessing WSL from Windows

# In Windows Explorer, type:
\\wsl$\Ubuntu\home\yourname\.claude\

# Or in PowerShell
cd \\wsl$\Ubuntu\home\yourname\.claude\

Path Translations

Windows	WSL
`C:\Users\YourName\`	`/mnt/c/Users/YourName/`
`%USERPROFILE%\.claude`	`/mnt/c/Users/YourName/.claude`
`D:\Projects\`	`/mnt/d/Projects/`

🚀 Quick Setup Commands

Shared Setup (Fastest)

# Run in WSL after Windows setup is complete
mkdir -p ~/.claude ~/.config
ln -s /mnt/c/Users/$(cmd.exe /c "echo %USERNAME%" | tr -d '\r')/.claude/agents ~/.claude/agents
ln -s /mnt/c/Users/$(cmd.exe /c "echo %USERNAME%" | tr -d '\r')/.claude/skills ~/.claude/skills
ln -s /mnt/c/Users/$(cmd.exe /c "echo %USERNAME%" | tr -d '\r')/.config/skillshare ~/.config/skillshare

Separate Setup (Full Linux)

# Run in WSL
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
git clone https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-agents.git ~/.claude/agents
skillshare init --no-copy --all-targets --git
cd ~/.config/skillshare/skills
git remote add origin https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-skills.git
skillshare pull --remote

📝 WSL Shell Aliases

Add to ~/.bashrc in WSL:

# Sync shortcuts
alias sync-agents='cd ~/.claude/agents && git pull origin main'
alias sync-skills='skillshare pull --remote'
alias sync-all='sync-agents && sync-skills'

# Push shortcuts
alias push-agents='cd ~/.claude/agents && git add . && git commit -m "Update from WSL" && git push'
alias push-skills='skillshare sync && skillshare push -m "Update from WSL"'

# Status shortcuts
alias agent-status='cd ~/.claude/agents && git status'
alias skill-status='skillshare status'

# Reload bashrc
source ~/.bashrc

Usage:

sync-all        # Pull both agents and skills
push-agents     # Push agent changes
skill-status    # Check skillshare status

🔄 Daily Workflow (WSL)

Morning Sync

# Open WSL terminal
wsl

# Pull latest from all machines
sync-all  # Or manually:
cd ~/.claude/agents && git pull
skillshare pull --remote

Working

# Create new agent
nano ~/.claude/agents/my-new-agent.md

# Create new skill
skillshare new my-helper
nano ~/.config/skillshare/skills/my-helper/SKILL.md

Evening Push

# Push agents
cd ~/.claude/agents
git add .
git commit -m "Add my-new-agent"
git push origin main

# Push skills
skillshare sync
skillshare push -m "Add my-helper skill"

🛠️ WSL-Specific Tips

1. Performance

WSL 2 is fast, but accessing Windows files (/mnt/c/) is slower than native WSL files (~/).

If using shared setup:

Acceptable for git pull/push
Skillshare sync might be slightly slower

If performance is critical:

Use separate setup (pure WSL paths)

2. Line Endings

Git in WSL handles line endings correctly by default:

# Verify (should be false or input)
git config --global core.autocrlf

# Set if needed
git config --global core.autocrlf input

3. File Permissions

Windows files accessed from WSL may have unusual permissions:

# If you see weird permissions like 777
# Add to ~/.bashrc or /etc/wsl.conf
echo "[automount]
options = metadata,umask=22,fmask=11" | sudo tee -a /etc/wsl.conf

# Restart WSL
wsl --shutdown
wsl

4. VS Code Integration

VS Code works great with WSL:

# In WSL, open VS Code
code ~/.claude/agents/
code ~/.config/skillshare/skills/

# VS Code will connect to WSL automatically

🐛 Troubleshooting WSL

Symlink Not Working

# Check if symlink exists
ls -la ~/.claude/agents

# Remove broken symlink
rm ~/.claude/agents

# Recreate
ln -s /mnt/c/Users/YourName/.claude/agents ~/.claude/agents

Permission Denied

# Check Windows directory permissions
ls -la /mnt/c/Users/YourName/.claude/

# If owned by root, fix permissions
sudo chown -R $(whoami):$(whoami) ~/.claude/

Git Not Found in WSL

# Install git
sudo apt update
sudo apt install git -y

Skillshare Not Found

# Check installation
which skillshare

# If not found, reinstall
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh

# Add to PATH if needed
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

WSL Can't Access Windows Files

# Check if Windows drives are mounted
ls /mnt/c/

# If not mounted, check WSL config
cat /etc/wsl.conf

# Should have:
# [automount]
# enabled = true

🎯 Recommended Setup by Use Case

Case 1: Claude Code in Both WSL and Windows

Use: Shared Setup

Symlink WSL to Windows directories
One set of skills/agents
Sync from either environment

Case 2: Claude Code Only in WSL

Use: Separate Setup

Native WSL paths (~/.claude/)
Better performance
Pure Linux experience

Case 3: Claude Code Only in Windows

Use: Windows Native Setup

Don't need WSL for Claude Code
But can use WSL for git commands (faster)
Symlink Windows to WSL if desired

Case 4: Development in WSL, Claude Code in Windows