If you keep your AI agent skills inside one local folder, you are basically managing configuration drift on purpose.

That setup works until it doesn't:

  • one machine has newer prompts than another
  • one agent has a patched script and another does not
  • you are never fully sure what is the source of truth

So we fixed it.

What We Changed

We created one shared repo:

~/.agents → pushed to github.com/nickyc1/agents

Then we moved reusable resources there:

  • skills/
  • TOOLS.md

And symlinked each workspace back to that source:

  • ~/.openclaw/workspace/skills -> ~/.agents/skills
  • ~/.openclaw/workspace/TOOLS.md -> ~/.agents/TOOLS.md

Result: all agents point to one canonical place.

Why a GitHub Repo Beats "Local for One Agent"

1) Single source of truth

No guessing where the latest version lives.

2) Version history and rollback

If a skill update breaks something, rollback is one command instead of detective work.

3) Cross-machine consistency

Laptop, Mac mini, and any future host can all pull the same skills.

4) Easier collaboration

You can review changes as commits/PRs instead of random file edits.

5) Faster scaling

Adding a new agent becomes wiring symlinks, not copy-pasting folders.

The Practical Pattern

Use this architecture:

  1. Keep shared skills and tools in one repo (~/.agents)
  2. Point each agent/workspace to that repo via symlinks
  3. Push updates to GitHub
  4. Pull updates on each machine (or automate it)

That gives you central control without losing local flexibility.

What to Watch Out For

  • Keep secrets out of the repo (use 1Password/service accounts)
  • Backup before first migration
  • Confirm each workspace still resolves symlinks correctly

How to Do This Yourself (Copy/Paste)

1) Create a shared local repo and move your skills/tools

# set your own paths if needed
BASE="$HOME/.agents"
WS="$HOME/.openclaw/workspace"
TS="$(date +%Y%m%d-%H%M%S)"

mkdir -p "$BASE/skills"
[ -d "$BASE/.git" ] || git -C "$BASE" init

# copy existing skills + tools into shared repo
rsync -a "$WS/skills/" "$BASE/skills/"
cp "$WS/TOOLS.md" "$BASE/TOOLS.md"

# backups before rewiring
mv "$WS/skills" "$WS/skills.backup-$TS"
cp "$WS/TOOLS.md" "$WS/TOOLS.md.backup-$TS"

# symlink workspace -> shared repo
ln -s "$BASE/skills" "$WS/skills"
rm "$WS/TOOLS.md"
ln -s "$BASE/TOOLS.md" "$WS/TOOLS.md"

# first commit
git -C "$BASE" add .
git -C "$BASE" commit -m "Initialize shared agents repo with skills and TOOLS"

2) Publish it to GitHub

# install GitHub CLI on macOS if needed
brew install gh

# login once (browser flow)
gh auth login -h github.com -p https -w

# create private repo and push
cd "$HOME/.agents"
gh repo create <your-github-username>/agents --private --source=. --remote=origin --push

3) Add a one-command sync script on every machine

cat > "$HOME/.agents/sync.sh" <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
cd "$HOME/.agents"
git pull --rebase

WS="$HOME/.openclaw/workspace"
[ -L "$WS/skills" ] || { rm -rf "$WS/skills"; ln -s "$HOME/.agents/skills" "$WS/skills"; }
[ -L "$WS/TOOLS.md" ] || { rm -f "$WS/TOOLS.md"; ln -s "$HOME/.agents/TOOLS.md" "$WS/TOOLS.md"; }

echo "Synced ~/.agents and verified symlinks."
EOF
chmod +x "$HOME/.agents/sync.sh"

4) Sanity checks

ls -la "$HOME/.openclaw/workspace" | grep -E "skills|TOOLS.md"
git -C "$HOME/.agents" remote -v
git -C "$HOME/.agents" status

If you see symlinks for skills and TOOLS.md, and origin points to GitHub, you are done.

Bottom Line

If you are running more than one agent or more than one machine, local-only skills are a trap.

A shared GitHub repo gives you reliability, speed, and confidence that every agent is actually running the same brain.