2026-11-10 08:37:59 +01:00
3 changed files with 16 additions and 3 deletions
@@ -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:

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

@@ -512,3 +512,11 @@ Scope: facts and traps that cost time to establish. Planned work lives in [TODO.
 - **A 1 cm solidify shell lets the body poke through.** Garments built by duplicating body faces needed 2 cm of solidify plus an 8 mm fatten along their own normals before the cloth read as continuous at shoulders, hips and knees.
 - **Warm skin sampling as blue-grey was lighting, not material.** The body stood in building shadow and was lit almost entirely by the blue `Demo_SkyLight` (intensity 2.6): face (99, 98, 100), arms (67, 74, 81). Raising the sun to pitch -74 moved the face to (131, 121, 117). A deliberate red test colour reaching the render first proved the material and the slot assignment were fine, which is what stopped a long hunt in the wrong place.
 - **The Unreal commandlet drops unknown command-line switches.** A `--unlit-test` flag passed after `-script` never reached Python; an environment variable does get through (and even that proved unnecessary once the red test settled the question).
+
+## 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**. Backup of the old trees: `/tmp/agent-skills-backup.tgz`.
+- 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.