xianxia-visual-director: a Codex Skill for cinematic xianxia still prompts

What xianxia-visual-director actually solves

Most xianxia image prompts fail in a predictable way. The writer stacks words like grand and epic, and the model returns a flat plate with fog where the architecture should be. The README frames the project against exactly that failure: it optimises existing xianxia prompts for insufficient scale, cities that do not read as bustling, flat space, heavy grey mist, muddy colour, or an over-applied orange-gold filter. That list is the product description. This is a repair tool for prompts that already exist, as much as a generator for new ones.

The audience is narrow and specific. You need to be running Codex with the Agent Skills mechanism, because installation copies a folder into ~/.codex/skills. You need to be working on Eastern fantasy environments rather than characters, since the shared rules govern thresholds, platforms, cloud harbours and cliff edges, and the human figure is explicitly a 1% to 4% scale reference seen from behind. If you are generating portraits, the canon here is dead weight.

The five-layer canon and the scale-evidence rule

The mechanism is a set of inherited constraints rather than a template. Every route, whether a single landmark or a populated celestial city, inherits the same shared canon. Six rules are listed in the README. The two that do the most work are the requirement for at least four observable or quantifiable pieces of monumental-scale evidence, and a fixed five-layer space: a near monumental threshold, a human-bearing interface, a governing mass, subordinate space, and a skyline terminus. Scale evidence means relationships the reader can check, such as figure height, column diameter, doorway size, platform span, architectural recession and the far celestial field. That is a real design position: prove size with geometry, do not assert it with adjectives.

The remaining rules are equally opinionated. Air must occupy roughly 40% to 60% of the frame and must have content, which the README defines as sky, cloud gaps, water, courtyards, doorways, deep space under bridges or distant skylight, explicitly not blank space or grey mist. Platforms, stairs, bridges, corridors, cloud harbours and cliff edges carry no railings by default. Architecture is built as beams, columns, bases, eaves, platforms and load-bearing relations before decoration is added anywhere. Costume follows a four-part formula the README gives as bone in the cloth, breath in the gauze, restraint in the ornament, a dominant in the colour, with hair, sleeves, hem and scarf sharing one wind direction.

Scene routes, style routes and how they combine

Routing is the part that separates this from a single prompt file. Two scene routes exist: single celestial realm, built around one landmark such as a gate, a divine tree library, an observatory, an island, an altar or a suspended scripture pavilion; and celestial settlement, which designs a civilisation that plausibly runs, with a main district, subordinate districts, lanes, courtyards, transit, cloud harbours, waterfall systems and far settlements. Two style routes sit alongside them: luminous translucent xianxia, which keeps colour bright and materials rich while avoiding neon and a global orange-gold wash, and Eastern sky megastructure, which uses cropped or occluded building fragments, threshold reveals and overhead compression to place the viewer beneath the structure.

A third route is described as independent canon: the celestial grand realm, quieter and more restrained, adding low cloud seas, limited distant anchors, a single active element and soft high-altitude diffuse light. Scene and style routes combine freely, and the README lists four pairings, including celestial settlement with Eastern sky megastructure. The design intent is that the canon stays fixed while the route changes, so two outputs from different routes still share a verifiable spatial grammar.

Installing the Skill and running a first prompt

The README gives two install paths. On macOS or Linux you clone the repository and copy the inner skill folder into the Codex skills directory. Note the doubled folder name in the path: the repository root contains a directory of the same name, and that inner directory is what gets copied.

git clone https://github.com/liyue-aigc/xianxia-visual-director.git
mkdir -p ~/.codex/skills
cp -R ./xianxia-visual-director/xianxia-visual-director ~/.codex/skills/

On Windows the same copy is done in PowerShell. The README warns that if the destination already exists you should back it up yourself before overwriting.

git clone https://github.com/liyue-aigc/xianxia-visual-director.git
Copy-Item -Recurse -Force `
  .\xianxia-visual-director\xianxia-visual-director `
  "$env:USERPROFILE\.codex\skills\xianxia-visual-director"

After copying, restart Codex or refresh the skill list. The smallest invocation in the README asks for a single scene and specifies the output package.

使用 $xianxia-visual-director。

设计一座雨后初晴的悬空藏经阁。画面明亮通透，植物鲜绿，阴影透明，不要灰蒙蒙。

请输出参数锁定、视觉导演方案、完整提示词、负面约束和三个衍生方向。

What you should get back is the standard five-part output: parameter lock, visual direction plan, full prompt, negative constraints, and three derivative directions. The full prompt is documented to state camera height, viewing distance, tilt, focal length, the five layers, scale evidence, air distribution, character costume, colour budget and a single dominant light direction. Aspect ratios supported are 16:9, 21:9, 4:3, 3:2, 4:5 and 9:16, with 16:9 as the default, and the README states that a single-frame prompt is the default even when 9:16 is chosen.

Where the design breaks down

The most concrete limitation is legal, not technical. The README states plainly that the repository carries no open source licence and that public visibility does not grant permission to copy, modify or redistribute. For a skill whose entire value is a folder you copy into a local directory, that is a real friction point: installation itself is a copy. The README's own instruction to clone and copy is not the same as a licence grant, and the two sit in tension. Anyone planning to vendor this into a team image pipeline should treat that gap as unresolved.

Second, the skill is bound to one agent runtime. It is a Codex / Agent Skills artefact, and the install steps assume ~/.codex/skills. The README says the skill does not bind to a specific image generation platform, which is true of the prompt text, but the delivery mechanism is not portable to a plain prompt library workflow. Third, the canon is a constraint system, and constraints cost you range. Six inherited rules plus route selection mean the skill will push every output toward monumental architecture with tiny figures and large air volumes. If you want a close character shot, an interior, or a deliberately cluttered market scene, the shared rules fight you. Fourth, the README notes that non-built-in parameters such as the ones it names for soft-vivid or quiet-pilgrimage intent can be kept as user-defined, but you must explain how they map onto the built-in camera or saturation logic. That is a manual step the skill will not do for you.

The video director next door, and what to compare against

The README points to a sibling project, xianxia-cinematic-video-director, and the division of labour is explicit: this skill handles single images, keyframes and visual设定, while the video skill develops a scene into multiple shots, camera movement, pacing, continuity and per-shot video prompts. Using both means locking aspect ratio, spatial scale, saturation strategy, architecture, characters, costume, materials, weather and light direction exactly once. That is the real alternative to compare against, and the difference is scope rather than approach: same canon, same routing philosophy, different output medium. If your deliverable is a moving sequence, this skill is the wrong entry point and the video skill is the right one.

The other comparison is against a hand-written prompt template. A template gives you a fixed paragraph you edit; this gives you a router that selects constraints based on scene and style. The trade is control for consistency. A template can be tuned to anything, including a close-up, while the router will keep pulling toward the five-layer monumental composition. Neither is better in the abstract. The repository's own framing, that it is a visual routing system under a shared celestial canon rather than a fixed white-jade-corridor template, is the honest description of which side it sits on.

Maintenance, licence and what the repository does not say

The last push to the default branch was on 2026-08-08. The repository is not archived. No releases were retrieved, so there is no version history to reason about, and the README does not document an upgrade path, a rollback procedure, or a way to migrate an existing installation when the skill files change. Because installation is a folder copy, upgrading means re-copying the inner directory over the old one, which is exactly the operation the README tells you to back up first. Nothing more is documented, so plan for a manual overwrite rather than a package manager.

On licensing, the README is unambiguous that no open source licence is attached and that visibility is not a grant. That is a statement of fact from the repository, not a legal opinion, and anyone redistributing the skill folder or shipping it inside a product should get their own advice. The practical consequence is that you can read the canon and the reference files, but the permission to reuse them is not spelled out anywhere in the README.

Editorial conclusion

Adopt it if you already run Codex skills and want your xianxia stills to carry measurable scale instead of adjectives, and if you are comfortable with a repository that states it has no open source licence. Do not adopt it if you need a platform-agnostic prompt library with a clear redistribution grant, or if you want video rather than keyframes; the README points to a separate xianxia-cinematic-video-director skill for that. Before you clone, check whether the target skills directory already exists, because the README tells you to back it up yourself, and confirm your Codex version still loads skills from ~/.codex/skills.

Frequently asked questions

Official sources

1. Issues
2. liyue-aigc/xianxia-visual-director on GitHub
3. README