Skills Sync Skill

Synchronize the local .agents/skills/ directory with the upstream agent-skills repository.

Prerequisites

• •rsync installed (default on this machine)
• •Upstream path (defaults to $HOME/workspace/experiments/agent-skills if present)

Override with environment variables:

Usage

# Inspect current wiring (paths, fanout targets)
.agents/skills/skills-sync/skills-sync info
# alias: "find" if you prefer `skills-sync find`

# Push local changes into upstream repo (default)
.agents/skills/skills-sync/skills-sync push

# Pull from upstream repo into this project
.agents/skills/skills-sync/skills-sync pull

# Dry-run to review rsync plan
.agents/skills/skills-sync/skills-sync push --dry-run

# Push local skills AND fan out to other projects
SKILLS_FANOUT_PROJECTS="$HOME/workspace/experiments/fetcher:$HOME/workspace/experiments/extractor:$HOME/.codex/skills:$HOME/.pi/agent" \
  .agents/skills/skills-sync/skills-sync push --fanout

# Push + auto-commit upstream (if SKILLS_SYNC_AUTOCOMMIT=1)
SKILLS_SYNC_AUTOCOMMIT=1 .agents/skills/skills-sync/skills-sync push

# Push + fanout + auto-commit
SKILLS_FANOUT_PROJECTS="..." SKILLS_SYNC_AUTOCOMMIT=1 \
  .agents/skills/skills-sync/skills-sync push --fanout

• •push: Local .agents/skills/ → $SKILLS_UPSTREAM_REPO/skills/
• •pull: $SKILLS_UPSTREAM_REPO/skills/ → local .agents/skills/

After a push, commit and push from the upstream repo so other projects stay current (auto-commit runs this for you when SKILLS_SYNC_AUTOCOMMIT=1):

cd "$SKILLS_UPSTREAM_REPO"
git status
git commit -am "Update shared skills"
git push

Options

• •--dry-run – Preview rsync without modifying files
• •--delete is always enabled so removed files stay in sync
• •--fanout – When pushing, also copy local skills into every project listed in SKILLS_FANOUT_PROJECTS (each root is expected to contain .agents/skills/)
• •--fanout-targets path1:path2 – Override SKILLS_FANOUT_PROJECTS inline
• •--no-autocommit – Disable auto-commit even if SKILLS_SYNC_AUTOCOMMIT=1
• •info / find – Read-only discovery helper that prints the detected local directory, upstream repo, and every configured fanout root plus whether it already has a .agents/skills/ folder.

Notes

• •The script prints the exact rsync command and a short summary of what to do next (commit/push).
• •Pull mode overwrites local changes. Use --dry-run first if unsure.
• •Fanout is opt-in: define SKILLS_FANOUT_PROJECTS (e.g., $HOME/workspace/experiments/fetcher:$HOME/workspace/experiments/extractor) to broadcast updates to additional repos once your upstream copy is ready.
• •Auto-commit is opt-in: set SKILLS_SYNC_AUTOCOMMIT=1 to have the script run git add/commit/push in the upstream repo after push. Use --no-autocommit to temporarily disable.