From 963be11a709ca11c93126c941829d6b57715c25b Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Tue, 10 Nov 2026 08:37:48 +0100 Subject: [PATCH] docs(skills): one common copy of the skill packs; project keeps blender-director The 94 symlinks in ~/.agents/skills and the full second copy in ~/.pi/agent/skills/blender-skills were the same packs under two roots, so Pi reported a collision for every one of them on every start and silently dropped the loser. - The 93 upstream packs, the shared references/ notes and the LICENSE now live once, flat and one level down, in the common agent folder ~/.pi/agent/skills/. - The repository keeps only the project-specific pack: .agents/skills/blender-skills/blender-director/. Its ../references/ links now point at ~/.pi/agent/skills/references/ because it no longer sits beside them. Its SKILL.md declared metadata.role twice (specialist, orchestrator), which is fatal YAML - the pack had never actually loaded. - AGENTS.md and Docs/toolchain.md describe the split and warn against copying the common packs back into the repository. Verified by walking all three discovery roots and parsing every frontmatter: 97 skills loaded, 0 malformed, 0 collisions. --- AGENTS.md | 6 +++++- Docs/toolchain.md | 5 +++-- MEMORY.md | 8 ++++++++ 3 files changed, 16 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ce4ffbd..1410242 100644 --- a/AGENTS.md +++ b/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//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: diff --git a/Docs/toolchain.md b/Docs/toolchain.md index 204586f..b6735bd 100644 --- a/Docs/toolchain.md +++ b/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 | | -| 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. diff --git a/MEMORY.md b/MEMORY.md index 3fcc7db..3fb3d02 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -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/` → 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.