AGENTS.md

@@ -179,7 +179,11 @@ Always use a consistent scale test, named export presets, and repeatable import
 
 ## Blender skills
 
-`.agents/skills/blender-skills/` holds 94 Blender skill packs (MIT, blender-skills 1.3.0). They are agent instructions, not add-ons, and nothing in the pipeline depends on them.
+The 93 upstream Blender skill packs (MIT, blender-skills 1.3.0) live once, in the **common** agent folder `~/.pi/agent/skills/`, together with the shared `references/` notes and the upstream `LICENSE`. They are agent instructions, not add-ons, and nothing in the pipeline depends on them.
+
+Only the project-specific pack stays in the repository: `.agents/skills/blender-skills/blender-director/` — the pipeline orchestrator, which names this project's tools and stages. It refers to the shared notes by absolute path (`~/.pi/agent/skills/references/…`).
+
+Do not copy the common packs into the repository: a second copy under a different root is a name collision, and Pi keeps the first one it finds and warns on every start. Add a pack to `~/.pi/agent/skills/<pack>/SKILL.md` (one level down, flat) and it is picked up everywhere; `references/` sits beside them at `~/.pi/agent/skills/references/`.
 
 **All agents must consult the relevant skill packs before starting a task in that discipline.** Each patch section in `TODO.md` lists its suggested skills; the general mapping is:
 

Docs/toolchain.md

@@ -33,8 +33,9 @@ Unreal Engine 5.9 is in preview and Unreal Engine 6 has been announced as of Nov
 | --- | --- |
 | Package | blender-skills `1.3.0`, upstream commit `8f778d2`, MIT |
 | Source | <https://github.com/arjun988/blender-skills> |
-| Location | Local only: `.agents/skills/blender-skills/` — not distributed with the repository |
-| Installed | 2026-11-06, copied from a local checkout of `.claude/skills/` without edits |
+| Location | Local only, common root: `~/.pi/agent/skills/` (93 packs, `references/`, `LICENSE`) — not distributed with the repository |
+| Project-specific | `.agents/skills/blender-skills/blender-director/` in this repository |
+| Installed | 2026-11-06, copied from a local checkout of `.claude/skills/` without edits; flattened to the common root on 2026-11-10 |
 
 These are instructions and reference notes for agents, not code that runs in a build. Four of them assume a **Blender MCP server**; this project drives Blender headlessly through `bpy` (`Tools/*.py`) instead, so MCP is optional and nothing depends on it.
 

MEMORY.md

@@ -599,3 +599,29 @@ Road_Hollywood_07 158   (was 366)
 
 - Every `.blend` under `Art/` checked out read-only; a Blender save then fails with `RuntimeError: Error: Cannot save blend file ... is not writable`, and because the export happens after the save in `Tools/hero_facade_build.py`, **the FBX is never written and the old one is reused silently**. All 20 `.blend`/`.blend1` files were made writable; `find Art -name '*.blend' ! -perm -u+w` now returns 0.
 - **Re-rendering does not pick up `.blend` changes.** `Tools/render_screenshots.sh` renders the imported UE assets, so a rebuild is needed in between: Blender build → `Tools/ue_*_import.py` → render. Chmod alone cannot change a pixel; the hero captures are byte-identical before and after.
+
+## 2026-11-10 — skills: one common copy, project-specific stays local
+
+- **Symlinked packs were the wrong fix.** The 2026-11-06 fix put 94 symlinks in
+  `~/.agents/skills/<pack>` → the repo, while `~/.pi/agent/skills/blender-skills/`
+  held a full second copy of the same packs. Pi keeps the first discovery and warns
+  on every start: 94 "collision" lines. `~/.agents/skills/blender-skills/` (the
+  upstream git checkout) also contains 94 packs under `.claude/skills/` and
+  `.cursor/skills/` — inert, because dot-directories are not scanned.
+- **`blender-director/SKILL.md` never loaded.** It declared `role:` twice in
+  `metadata` (`specialist` then `orchestrator`); duplicate YAML keys are fatal, so
+  the pack was dropped silently while the other 94 loaded.
+- **Layout now** — shared, one level down and flat so it is discovered:
+  `~/.pi/agent/skills/<93 packs>/`, `~/.pi/agent/skills/references/`,
+  `~/.pi/agent/skills/LICENSE`. Project-specific and versioned:
+  `.agents/skills/blender-skills/blender-director/`, whose `../references/` links
+  were rewritten to `~/.pi/agent/skills/references/…` because it no longer sits
+  beside them. The 94 `~/.agents/skills` symlinks are gone.
+- **Verified** by walking the three discovery roots
+  (`~/.pi/agent/skills`, `~/.agents/skills`, project `.agents/skills`, dot-dirs
+  skipped), parsing every frontmatter: **97 skills loaded, 0 malformed, 0
+  collisions**. Backups of the old trees: `/tmp/agent-skills-backup.tgz`,
+  `/tmp/pi-blender-skills-dupe` (now consumed).
+- Rule: a skill exists in **one** place. Two roots with the same `name` is a
+  warning on every start, and the loser is invisible — check the startup list, not
+  the file tree.