claude-skills/WINDOWS-SETUP.md

# Windows Cross-Device Sync Guide

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

---

## 📋 Prerequisites

### Required Software

1. **Git for Windows**
   - Download: https://git-scm.com/download/win
   - Install with "Git Bash" option enabled
   - Use default settings during installation

2. **Claude Code** (if using skills)
   - Should already be installed
   - Skills directory: `%USERPROFILE%\.claude\skills`
   - Agents directory: `%USERPROFILE%\.claude\agents`

3. **PowerShell or Git Bash**
   - PowerShell: Built into Windows
   - Git Bash: Comes with Git for Windows (recommended for commands below)

---

## 🤖 Agent Sync on Windows

### Initial Setup

Open **Git Bash** (or PowerShell with git installed):

```bash
# Configure git (one-time)
git config --global user.name "admin"
git config --global user.email "admin@server-ai.local"
git config --global init.defaultBranch main

# Clone agents repository
git clone https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-agents.git %USERPROFILE%\.claude\agents

# Or in Git Bash (Unix-style paths)
git clone https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-agents.git ~/.claude/agents
```

### If You Have Existing Agents

```bash
# Backup first
cp -r ~/.claude/agents ~/.claude/agents.backup

# Initialize git
cd ~/.claude/agents
git init
git checkout -b main

# Commit existing agents
git add .
git commit -m "Add existing agents from Windows PC"

# Connect to Gitea
git remote add origin https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-agents.git

# Merge with remote
git pull origin main --allow-unrelated-histories

# Push your agents
git push origin main
```

### Daily Sync (Git Bash)

```bash
# Pull updates
cd ~/.claude/agents
git pull origin main

# Push changes
cd ~/.claude/agents
git add .
git commit -m "Update agents from Windows"
git push origin main
```

### Daily Sync (PowerShell)

```powershell
# Pull updates
cd $env:USERPROFILE\.claude\agents
git pull origin main

# Push changes
cd $env:USERPROFILE\.claude\agents
git add .
git commit -m "Update agents from Windows"
git push origin main
```

---

## 🎯 Skills Sync on Windows

### Skillshare Installation on Windows

**Method 1: Manual Installation (Recommended)**

1. Download latest release from GitHub:
   - Go to: https://github.com/runkids/skillshare/releases
   - Download: `skillshare_<version>_windows_amd64.zip`

2. Extract and install:
   ```powershell
   # In PowerShell (as Administrator)
   Expand-Archive skillshare_<version>_windows_amd64.zip -DestinationPath C:\Program Files\skillshare

   # Add to PATH
   $env:Path += ";C:\Program Files\skillshare"
   [Environment]::SetEnvironmentVariable("Path", $env:Path, [EnvironmentVariableTarget]::Machine)
   ```

3. Verify installation:
   ```powershell
   skillshare version
   ```

**Method 2: Using Scoop (if you have Scoop installed)**

```powershell
# Install via Scoop
scoop bucket add extras
scoop install skillshare
```

**Method 3: Using Chocolatey (if available)**

```powershell
# Check if available
choco search skillshare

# If available
choco install skillshare
```

### Initialize Skillshare on Windows

**In Git Bash:**

```bash
# Initialize without prompts (AI-friendly)
skillshare init --no-copy --all-targets --git

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

# Pull skills and sync to Claude Code
skillshare pull --remote
```

**In PowerShell:**

```powershell
# Initialize
skillshare init --no-copy --all-targets --git

# Add git remote
cd $env:USERPROFILE\.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
```

### Daily Skills Sync (Windows)

**Git Bash:**
```bash
# Pull from Gitea (auto-syncs to Claude Code)
skillshare pull --remote

# Push changes
skillshare new my-skill
skillshare sync
skillshare push -m "Add my-skill from Windows"
```

**PowerShell:**
```powershell
# Same commands work in PowerShell
skillshare pull --remote
skillshare push -m "Update from Windows"
```

---

## 🔧 Windows-Specific Paths

### Claude Code Directories

| Linux/Mac | Windows (Git Bash) | Windows (PowerShell) |
|-----------|-------------------|---------------------|
| `~/.claude/agents` | `~/.claude/agents` | `$env:USERPROFILE\.claude\agents` |
| `~/.claude/skills` | `~/.claude/skills` | `$env:USERPROFILE\.claude\skills` |
| `~/.config/skillshare/skills` | `~/.config/skillshare/skills` | `$env:USERPROFILE\.config\skillshare\skills` |

### Typical Windows Paths

- **Agents**: `C:\Users\YourName\.claude\agents`
- **Skills (Claude)**: `C:\Users\YourName\.claude\skills`
- **Skills (Source)**: `C:\Users\YourName\.config\skillshare\skills`

---

## 🖥️ Windows Batch Scripts

### sync-agents.bat

Create `sync-agents.bat` in `%USERPROFILE%\scripts\`:

```batch
@echo off
echo Syncing Claude agents...
cd %USERPROFILE%\.claude\agents
git pull origin main
if %ERRORLEVEL% EQU 0 (
    echo.
    echo ✓ Agents synced successfully!
    echo.
    echo Current agents:
    dir /b *.md
) else (
    echo.
    echo ✗ Sync failed!
)
pause
```

### sync-skills.bat

Create `sync-skills.bat` in `%USERPROFILE%\scripts\`:

```batch
@echo off
echo Syncing Claude skills...
skillshare pull --remote
if %ERRORLEVEL% EQU 0 (
    echo.
    echo ✓ Skills synced successfully!
    skillshare status
) else (
    echo.
    echo ✗ Sync failed!
)
pause
```

### Usage

Double-click the `.bat` files or run from Command Prompt:
```cmd
%USERPROFILE%\scripts\sync-agents.bat
%USERPROFILE%\scripts\sync-skills.bat
```

---

## 🚀 PowerShell Scripts (Better Alternative)

### sync-agents.ps1

Create `sync-agents.ps1` in `%USERPROFILE%\Documents\WindowsPowerShell\Scripts\`:

```powershell
# Sync Claude agents from Gitea
$agentsPath = "$env:USERPROFILE\.claude\agents"

Write-Host "🔄 Syncing Claude agents..." -ForegroundColor Cyan
Set-Location $agentsPath

try {
    git pull origin main
    Write-Host "`n✅ Agents synced successfully!`n" -ForegroundColor Green

    Write-Host "📊 Current agents:" -ForegroundColor Cyan
    Get-ChildItem -Filter *.md | ForEach-Object {
        Write-Host "  - $($_.BaseName)" -ForegroundColor White
    }
} catch {
    Write-Host "`n❌ Sync failed: $_`n" -ForegroundColor Red
}

Read-Host "`nPress Enter to continue"
```

### sync-skills.ps1

Create `sync-skills.ps1`:

```powershell
# Sync Claude skills via Skillshare
Write-Host "🔄 Syncing Claude skills..." -ForegroundColor Cyan

try {
    skillshare pull --remote
    Write-Host "`n✅ Skills synced successfully!`n" -ForegroundColor Green
    skillshare status
} catch {
    Write-Host "`n❌ Sync failed: $_`n" -ForegroundColor Red
}

Read-Host "`nPress Enter to continue"
```

### Enable PowerShell Scripts (One-Time)

```powershell
# Run PowerShell as Administrator
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### Create PowerShell Aliases

Add to your PowerShell profile:

```powershell
# Edit profile
notepad $PROFILE

# Add these lines:
function Sync-Agents {
    Set-Location "$env:USERPROFILE\.claude\agents"
    git pull origin main
}

function Sync-Skills {
    skillshare pull --remote
}

function Push-Agents {
    param([string]$message = "Update agents from Windows")
    Set-Location "$env:USERPROFILE\.claude\agents"
    git add .
    git commit -m $message
    git push origin main
}

function Push-Skills {
    param([string]$message = "Update skills from Windows")
    skillshare sync
    skillshare push -m $message
}

# Usage:
# Sync-Agents
# Sync-Skills
# Push-Agents -message "Add new agent"
# Push-Skills -message "Update helper skill"
```

---

## 🔐 Credential Management on Windows

### Option 1: Git Credential Manager (Recommended)

Git for Windows includes Credential Manager:

```bash
# Configure credential helper (one-time)
git config --global credential.helper manager-core

# First push/pull will prompt for credentials
# Credentials are then stored securely in Windows Credential Manager
```

### Option 2: Store Credentials in URL (Less Secure)

Already configured in the remote URLs:
```bash
https://admin:MyN3wP%40ssword%21@gitea.pressmess.duckdns.org/admin/claude-agents.git
```

### Option 3: SSH Keys (Most Secure)

```bash
# Generate SSH key
ssh-keygen -t ed25519 -C "admin@windows-pc"

# Copy public key
cat ~/.ssh/id_ed25519.pub

# Add to Gitea:
# 1. Login to Gitea
# 2. Settings → SSH Keys → Add Key
# 3. Paste public key

# Update remote to use SSH
cd ~/.claude/agents
git remote set-url origin git@omv800:admin/claude-agents.git

cd ~/.config/skillshare/skills
git remote set-url origin git@omv800:admin/claude-skills.git
```

---

## 📱 Windows Task Scheduler (Auto-Sync)

### Create Scheduled Task for Auto-Pull

1. Open **Task Scheduler**
2. Create Basic Task:
   - **Name**: Sync Claude Agents
   - **Trigger**: Daily at startup or login
   - **Action**: Start a program
   - **Program**: `C:\Program Files\Git\bin\bash.exe`
   - **Arguments**: `-c "cd ~/.claude/agents && git pull origin main"`

3. Repeat for skills:
   - **Name**: Sync Claude Skills
   - **Program**: `skillshare.exe`
   - **Arguments**: `pull --remote`

---

## 🐛 Troubleshooting Windows

### Skillshare Not Found

```powershell
# Check if in PATH
$env:Path -split ';' | Select-String skillshare

# If not found, add manually
$env:Path += ";C:\Program Files\skillshare"
```

### Line Ending Issues

```bash
# Configure git to handle line endings
git config --global core.autocrlf true
```

### Permission Denied

```powershell
# Run PowerShell as Administrator
Start-Process powershell -Verb RunAs
```

### Git Command Not Found in PowerShell

```powershell
# Add Git to PATH
$env:Path += ";C:\Program Files\Git\bin"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [EnvironmentVariableTarget]::User)
```

### Skillshare Init Hangs

```bash
# Use non-interactive flags
skillshare init --no-copy --all-targets --git
```

---

## 🎯 Quick Setup Checklist

### For Agents:
- [ ] Install Git for Windows
- [ ] Configure git username/email
- [ ] Clone or initialize agents repo
- [ ] Test pull/push
- [ ] Create sync script (optional)

### For Skills:
- [ ] Install Git for Windows
- [ ] Download and install Skillshare binary
- [ ] Initialize Skillshare with `--all-targets --git`
- [ ] Add git remote
- [ ] Test `skillshare pull --remote`
- [ ] Create sync script (optional)

---

## 📚 Windows Resources

- **Git for Windows**: https://git-scm.com/download/win
- **Skillshare Releases**: https://github.com/runkids/skillshare/releases
- **PowerShell Docs**: https://docs.microsoft.com/powershell
- **Windows Terminal**: https://aka.ms/terminal (better than CMD)

---

## 💡 Best Practices for Windows

1. **Use Git Bash** for Linux-like commands
2. **Use PowerShell** for Windows-native scripting
3. **Windows Terminal** for better experience
4. **VSCode** as git GUI (optional)
5. **Store scripts** in `%USERPROFILE%\scripts\`
6. **Add to PATH** for easy access

---

## 🔗 Related Documentation

- **Linux/Mac Guide**: `/home/jon/AGENT-SYNC-GUIDE.md`
- **Skills Guide**: `/home/jon/SKILLS-SYNC-GUIDE.md`
- **Server Docs**: `/home/jon/SERVER-DOCUMENTATION.md`

---

**Last Updated**: 2026-01-29
**Version**: 1.0
**Platform**: Windows 10/11
**Tested With**: Git for Windows 2.43+, Skillshare 0.6.20