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.
This commit is contained in:
zwitschi committed 2026-11-10 08:36:58 +01:00
1 parent 61dd28bc89
commit 19ed4fefd4
3 files changed
+34 -3

No files matched your search

+26
View File
@@ -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.