From bcc4d242c42dd5b104f9de5cc43a4c1500f40df6 Mon Sep 17 00:00:00 2001
From: admin <admin@server-ai.local>
Date: Thu, 29 Jan 2026 17:00:28 +0000
Subject: [PATCH] Add WSL setup guide with shared and separate strategies

---
 WSL-SETUP.md | 562 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 562 insertions(+)
 create mode 100644 WSL-SETUP.md

diff --git a/WSL-SETUP.md b/WSL-SETUP.md
new file mode 100644
index 0000000..414b795
--- /dev/null
+++ b/WSL-SETUP.md
@@ -0,0 +1,562 @@
+# 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)
+
+```powershell
+# In PowerShell as Administrator
+wsl --install
+
+# Or install specific distro
+wsl --install -d Ubuntu-22.04
+
+# Reboot Windows
+```
+
+### Verify WSL Installation
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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)
+
+```bash
+# 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)
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# Install Skillshare
+curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
+
+# Verify
+skillshare version
+```
+
+### Step 4: Setup Skills
+
+```bash
+# 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
+
+```bash
+# Same as Linux commands - pull agents
+cd ~/.claude/agents && git pull
+
+# Pull skills
+skillshare pull --remote
+```
+
+---
+
+## 🗂️ Understanding WSL Paths
+
+### Accessing Windows from WSL
+
+```bash
+# 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)
+
+```bash
+# 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)
+
+```bash
+# 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:
+
+```bash
+# 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:
+```bash
+sync-all        # Pull both agents and skills
+push-agents     # Push agent changes
+skill-status    # Check skillshare status
+```
+
+---
+
+## 🔄 Daily Workflow (WSL)
+
+### Morning Sync
+
+```bash
+# Open WSL terminal
+wsl
+
+# Pull latest from all machines
+sync-all  # Or manually:
+cd ~/.claude/agents && git pull
+skillshare pull --remote
+```
+
+### Working
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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:
+
+```bash
+# 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:
+
+```bash
+# In WSL, open VS Code
+code ~/.claude/agents/
+code ~/.config/skillshare/skills/
+
+# VS Code will connect to WSL automatically
+```
+
+---
+
+## 🐛 Troubleshooting WSL
+
+### Symlink Not Working
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# Install git
+sudo apt update
+sudo apt install git -y
+```
+
+### Skillshare Not Found
+
+```bash
+# 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
+
+```bash
+# 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
+**Use: Shared Setup**
+- Code in WSL, run Claude in Windows
+- Both access same skills/agents
+- Best of both worlds
+
+---
+
+## 📊 Performance Comparison
+
+| Operation | Native Windows | WSL (Shared) | WSL (Separate) |
+|-----------|---------------|--------------|----------------|
+| Git clone | Medium | Medium | Fast |
+| Git pull | Medium | Medium | Fast |
+| Skillshare sync | Medium | Slow | Fast |
+| File access | Fast | Slow | Fast |
+| Overall | Medium | Medium | **Fastest** |
+
+**Recommendation**: If performance matters, use separate WSL setup.
+
+---
+
+## 🔐 Credentials in WSL
+
+### Option 1: Store in Git URL (Already Configured)
+
+```bash
+# Already set in remote URL
+https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/...
+```
+
+### Option 2: Git Credential Helper
+
+```bash
+# Install credential helper
+git config --global credential.helper store
+
+# First pull/push will prompt for password
+# Then stored in ~/.git-credentials
+```
+
+### Option 3: SSH Keys
+
+```bash
+# Generate SSH key in WSL
+ssh-keygen -t ed25519 -C "admin@wsl"
+
+# Copy public key
+cat ~/.ssh/id_ed25519.pub
+
+# Add to Gitea (Settings → SSH Keys)
+
+# Update remotes
+cd ~/.claude/agents
+git remote set-url origin git@gitea.pressmess.duckdns.org:admin/claude-agents.git
+```
+
+---
+
+## 📚 Resources
+
+- **WSL Install**: https://learn.microsoft.com/en-us/windows/wsl/install
+- **WSL Best Practices**: https://learn.microsoft.com/en-us/windows/wsl/setup/environment
+- **VS Code + WSL**: https://code.visualstudio.com/docs/remote/wsl
+
+---
+
+## ✅ Quick Checklist
+
+### Shared Setup:
+- [ ] Install WSL
+- [ ] Set up agents/skills in Windows
+- [ ] Create symlinks from WSL to Windows
+- [ ] Test: `ls ~/.claude/agents`
+- [ ] Optional: Install Skillshare in WSL
+
+### Separate Setup:
+- [ ] Install WSL
+- [ ] Install git in WSL
+- [ ] Clone agents repo
+- [ ] Install Skillshare
+- [ ] Initialize Skillshare with remote
+- [ ] Test sync
+
+---
+
+**Last Updated**: 2026-01-29
+**Version**: 1.0
+**WSL Version**: WSL 2
+**Tested With**: Ubuntu 22.04, Ubuntu 24.04