Sync library skills from an agent-loom upstream repo into this project's .agents/skills while preserving project-local and forked skills. Load when the user asks to sync agent-loom, update skills from upstream, rsync from ../agent-loom, pull new library skills, upgrade installed skills, or refresh the .agents folder without losing custom project skills. Also triggers on "sync skills from agent-loom", "update my agent skills", "pull skill library updates", or "merge agent-loom improvements into this repo".
Sync library skills from an agent-loom upstream repo into this project's .agents/skills while preserving project-local and forked skills. Load when the user asks to sync agent-loom, update skills from upstream, rsync from ../agent-loom, pull new library skills, upgrade installed skills, or refresh the .agents folder without losing custom project skills. Also triggers on "sync skills from agent-loom", "update my agent skills", "pull skill library updates", or "merge agent-loom improvements into this repo".
license
MIT
metadata
{"author":"dvy1987","version":"1.2","category":"project-specific","sources":"agent-loom consumer install pattern (copy .agents + local skills)","resources":{"references":["examples.md","sync-policy.md"],"scripts":["sync_agent_loom.py"],"templates":["agent-loom-sync.json"]}}
Agent-Loom Sync
You merge upstream agent-loom library improvements into a consumer project's .agents/skills/ without deleting or overwriting skills that belong only to this project.
Hard Rules
Never delete local-only skills. A skill directory present in the project but absent from upstream is project-local — keep it forever unless the user explicitly asks to remove it.
Never overwrite protected or forked skills without explicit user approval. Protection sources: metadata.origin: project-local in SKILL.md, .agents/agent-loom-sync.json → protected_skills / forked_skills, or skills that exist only locally.
Always dry-run before apply. Present the plan (add / update / unchanged / local-only / forked) and wait for confirmation before --apply.
Never sync the project root AGENTS.md from upstream. That file is project-specific (from project-setup). Sync .agents/skills/, and hooks/ when present upstream, optionally .agents/ROUTING.md when the user opts in.
Never run rsync on the whole .agents/skills/ tree with --delete. Sync per library skill directory only — bulk delete would remove project-local skills.
Ensure metadata.origin: project-local on every local-only skill. After --apply, sync_agent_loom.py stamps missing origin on skills absent from upstream. Report stamped skills in the impact report. Same-name upstream forks use forked_skills in config instead.
Workflow
Step 1 — Resolve upstream path
Default: ../agent-loom relative to project root. Override via:
User-provided path argument
.agents/agent-loom-sync.json → "upstream"
Verify upstream exists and contains .agents/skills/. If missing, stop with the exact path checked.
Bootstrap config if absent: copy templates/agent-loom-sync.json → .agents/agent-loom-sync.json.
Classify each skill — read references/sync-policy.md for protection rules. Summarize for the user:
Bucket
Meaning
Add
New upstream skill not in project
Update
Upstream skill differs; safe to rsync
Unchanged
Already matches upstream hash
Local-only
Project skill with no upstream counterpart — protected
Forked
Modified library skill — skipped until user merges
Step 3 — Confirm with user
Show counts and name lists for Add and Update. Ask: "Apply sync?" One confirmation for apply; forked skills need per-skill decision if user wants upstream version.
Updates .agents/agent-loom-sync.json with last_sync and upstream_commit. Script stamps metadata.origin: project-local on local-only skills missing it — report which skills were stamped.
Step 5 — Optional ROUTING.md
Only if user asks: rsync upstream .agents/ROUTING.md when project has not forked it (no local diff). Never auto-overwrite without asking.
Step 6 — Post-sync validation
Invoke validate-skills (or run Step 4e craft gates) on updated skills. Report P0/P1 before user commits.
Regenerate host routing adapters: python3 .agents/skills/project-setup/scripts/gen_host_adapters.py (refreshes .cursor/rules/ from the synced skill set).
Step 7 — Log and handoff
Append to docs/skill-outputs/SKILL-OUTPUTS.md. Recommend commit message: chore: sync agent-loom library @ <commit>. Offer memory-handoff if session ends.
Project-local origin (this skill's job)
Responsibility
Owner
Write metadata.origin: project-local when creating skills
universal-skill-creator (Step 4 + Step 7b)
Stamp missing origin on local-only skills after sync
agent-loom-sync (--apply via sync_agent_loom.py)
Protect skills with that metadata from overwrite
agent-loom-sync sync plan
Same-name customized upstream skill
forked_skills in .agents/agent-loom-sync.json
Every project-local SKILL.md should carry origin: project-local. These skills ensure it — not the user.
Gotchas
Copying all of .agents/ once ≠ ongoing sync. This skill is the ongoing path; re-copying blindly deletes project-local skills.
../agent-loom is relative to project root, not the skill directory — run the script from repo root.
rsync --delete is per-skill, removing stale files inside an updated library skill dir only.
Global install (install.sh) is different — that symlinks to ~/.agents/skills; this skill targets project-copied .agents/.
Upstream must be pulled first — remind user to git pull in agent-loom before sync if they want latest.
Common Rationalizations
Excuse
Reality
"Just rsync the whole .agents folder"
Deletes project-local skills and project config
"Skip dry-run, I trust upstream"
Forked/custom skills get wiped without a plan
"Overwrite my fork — upstream is always right"
Require explicit per-skill opt-in to replace forked
"Sync AGENTS.md from agent-loom"
Project AGENTS.md is from project-setup — merge manually
"Delete skills removed upstream"
Local-only stays; upstream removals don't delete local skills
Verification
Dry-run plan shown before apply
All local-only skills listed under protected
No protected/forked skill in Update list without user approval
agent-loom-sync.json updated after apply
Local-only skills have metadata.origin: project-local (stamped by apply if missing)
SKILL-OUTPUTS.md appended when files changed
Red Flags
Whole-tree rsync with delete on .agents/skills/
Local-only skill missing from protected list in plan
Forked skill overwritten without user opt-in
Upstream path points at wrong repo or missing .agents/skills
Example
sync agent-loom from ../agent-loom without losing my custom skills
Plan: 15 add, 22 update, 3 local-only protected. Awaiting confirm before --apply.
Read references/examples.md for full session walkthroughs.
Prune Log
Last pruned: 2026-07-04
No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)
Impact Report
Agent-loom sync: upstream @ <commit> | add: N | update: N | protected: N | forked: N | applied: yes/no | Config: .agents/agent-loom-sync.json
