dvy1987dvy1987/agent-loom/.agents/skills/agent-loom-sync/SKILL.md

agent-loom-sync

Skill4 starsChanged 3 months agoMITView on GitHub

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".

In this repository125 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .cursor/rules/agent-loom-routing.mdcCursor rule
- .cursor/rules/agent-loom-skills-index.mdcCursor rule
- adversarial-hatSkill
- agent-builderSkill
- agent-launcherSkill
- agent-observabilitySkill
- agent-run-retroSkill
- agent-system-architectureSkill
- api-and-interface-designSkill
- api-deprecation-and-migrationSkill
- apply-paper-to-projectSkill
- app-security-hardeningSkill
- architectural-decision-logSkill
- assumption-mappingSkill
- brainstormingSkill
- browser-testing-with-devtoolsSkill
- business-modelingSkill
- ci-cd-and-automationSkill
- codebase-understandingSkill
- code-review-crspSkill
- code-simplificationSkill
- compress-skillSkill
- context-engineeringSkill
- create-agent-promptSkill
- cross-link-skillsSkill
- customer-discoverySkill
- debug-and-fixSkill
- deep-thinkingSkill
- dependency-mappingSkill
- deploy-anywhereSkill
- deprecate-skillSkill
- design-directionSkill
- design-reviewSkill
- design-systemSkill
- dynamic-routingSkill
- eval-judgeSkill
- eval-outputSkill
- eval-pipelineSkill
- eval-rubric-designSkill
- experimentationSkill
- experiment-backlogSkill
- experiment-readoutSkill
- experiment-runbookSkill
- experiment-specSkill
- fault-localizeSkill
- feature-specSkill
- fermiSkill
- first-principlesSkill
- frontend-designSkill
- generate-changelogSkill
- git-workflow-and-versioningSkill
- gsap-animationSkill
- harness-engineeringSkill
- harness-evolutionSkill
- harness-generationSkill
- idea-evaluationSkill
- idea-generationSkill
- implementation-planSkill
- improve-skillsSkill
- The first 60 shown.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Default: ../agent-loom relative to project root.
line 51
Very specific:
Verify upstream exists and contains .agents/skills/.
line 55
Very specific:
Only if user asks: rsync upstream .agents/ROUTING.md when project has not forked it (no local diff).
line 89
Very specific:
Every project-local SKILL.md should carry origin: project-local.
line 111
Very specific:
Read references/examples.md for full session walkthroughs.
line 163
Distinctive:
No changes — citation audit passed.
line 169

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

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

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

<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

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free