genjutsu

All modules

The modules behind cast, paint and bunshin, why they load on demand instead of all at once, and how the loader finds them on every install.

All documentation

Seventeen focused modules sit behind the three pipelines. They are internal: you never invoke one directly, and there is no /genjutsu:gsap. Each one carries metadata.internal: true, so npx skills never offers it on its own. cast, paint and bunshin decide which ones apply and load only those.

Why on demand

Context is finite, and most of these modules are irrelevant to any given project. A static site has no use for Metal shaders. A Compose app has no use for Framer Motion. Loading seventeen manuals every time would spend the context budget on material that will never be referenced, and dilute the material that will be.

So the loading rules are mechanical rather than clever:

  • Always: motion foundations.
  • By context: mobile principles when the target is mobile web or native iOS/Android; desktop principles when it is macOS or desktop web; the audit module when the scope is full or an audit was requested.
  • After the thesis, on the web: tells, when the stack is web and the scope is medium or full. cast loads it right after the thesis is validated; paint loads it in phase 3, before palette and type are fixed. Never on Compose or SwiftUI yet: the catalogue for those platforms has not been observed, and it is not invented.
  • By stack: whatever the scan found. GSAP present means the GSAP module. Nothing present means the zero-dependency CSS module, because an existing choice is respected and a missing one is not invented.
  • For bunshin: orchestration, at the summoning, before the first clone. Its references load one at a time, when their phase comes. bunshin builds a whole site, so its scope is always full: tells, the mobile and desktop principles and the audit module all load before the foundation.
  • By thesis, or by scope: the advanced graphics modules for Apple and Android load when the scope is full, or when the validated thesis calls for them. That second trigger is lexical: shader, Metal, AGSL, RuntimeShader, Liquid Glass, glassEffect, colorEffect, layerEffect, distortionEffect, Material 3 Expressive, MotionScheme, holographic, CRT, displacement or ripple.

Each heavy module loads in its own shell call, so no single read grows past what the agent can see in full.

The four families

Foundations

Seven modules. motion-principles loads on every single invocation and is the reason the output is consistent across stacks. design-audit closes every pipeline. tells names the defaults models reach for and is loaded once there is a thesis to measure them against. ui-ux-pro-max carries the design-system dataset. mobile-principles and desktop-principles load by context. orchestration is how bunshin briefs, fences, checks and stops its clones, and nothing else loads it.

Web

Five modules: css-native, gsap, framer-motion, threejs-r3f, canvas-generative. Selected from your dependencies, not from preference.

Apple

Two modules: swiftui-motion always, swiftui-graphics when the thesis is advanced. iOS and macOS are told apart during the scan, and the platform UX layer differs accordingly.

Android

Three modules: compose-motion always, compose-graphics when the thesis is advanced, compose-multiplatform when the Kotlin Multiplatform and Compose plugins are both present.

How the loader finds them

Worth knowing if an install ever misbehaves. Every host puts the skill tree somewhere else, and Cowork has no fixed path at all. The same resolver runs in cast, paint, bunshin and the genjutsu router, numbered from zero the way the skill numbers it, and it stops at the first place that qualifies:

  1. On claude.ai, the uploaded bundle: under /mnt/skills/plugins, the current mount, then under /mnt/skills/user, the older one.
  2. The skill’s own folder, and the _jutsu folder next to it or one level up. This is what makes an npx install or a copied bundle resolve without guessing: after an npx install, the router passes its own folder down.
  3. The installed plugin’s own directory, when Claude Code provides it.
  4. A bounded search of the usual skill folders: .claude/skills and .agents/skills walking up from the project, then ~/.agents/skills, ~/.claude/skills, ~/.codex/skills, ~/.cursor/skills and /mnt/.claude/skills, and last /sessions, where Cowork mounts each session under a root of its own, such as /sessions/<session-id>/mnt/.claude/skills/genjutsu/_jutsu.
  5. Last, the Claude Code plugin cache, newest version first, so an old plugin version can never win over a newer bundle.

A folder only counts if it really holds genjutsu’s modules, which the resolver checks by looking for motion-principles inside it. The shared skills folder is used by dozens of agents, so a folder that merely happens to be called cast is never taken for genjutsu. Every search has a depth cap, so none of them can walk the whole filesystem.

If no folder qualifies, genjutsu stops before the pipeline starts, prints the install commands and every place it looked, and runs nothing on empty. If one module is missing, for instance after a partial upload on claude.ai, it carries on without that module, and the final report says so in two lines: the modules that loaded, and the ones that did not.