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.
Step 2 — Build sync plan
python3 .agents/skills/agent-loom-sync/scripts/sync_agent_loom.py --dry-run
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.
Step 4 — Apply
python3 .agents/skills/agent-loom-sync/scripts/sync_agent_loom.py --apply
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
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
<examples>
<example>
<input>sync agent-loom from ../agent-loom without losing my custom skills</input>
<output>Plan: 15 add, 22 update, 3 local-only protected. Awaiting confirm before --apply.</output>
</example>
</examples>
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