xianxia-visual-director: A Codex Skill for Structured Eastern Xianxia Image Prompts

What xianxia-visual-director Does and Who It Is For

xianxia-visual-director is a skill file for the Codex agent skill framework and similar systems. When invoked, it takes a short scene description or an existing prompt and expands it into a complete visual direction package: locked parameters, a spatial composition plan, a full positive prompt, negative constraints and three derivative directions for follow-up. It is aimed at digital artists, game designers and AI art practitioners who generate Eastern fantasy imagery and find that image generation models tend to produce flat composition, missing scale cues, distracting railings, uniform haze or visual noise when given loose prompts. The skill addresses these recurring patterns through explicit, verifiable spatial rules rather than through vague style imitation or mood adjectives.

The Shared Celestial Realm Rules

Every prompt generated through xianxia-visual-director inherits a set of seven spatial and visual rules that apply across all routing combinations. First, at least four observable or quantifiable scale cues must appear: pillar diameter, gate span, platform width, receding architecture or figures used as size reference. Second, every frame must include five spatial layers: a foreground threshold element (a massive gate or column), a human-scale surface, a dominant architectural mass, a subordinate spatial zone and a skyline terminus. Third, roughly 40 to 60 percent of the frame must be active air: sky, cloud gaps, water surfaces, courtyards, archway openings or distant light, but not blank fog or empty gray. Fourth, architecture establishes structural logic first (beams, bases, eaves, platforms, load-bearing relationships) before surface decoration is added. Fifth, platforms, stairs, bridges, corridors and cliff edges carry no railings by default. Sixth, environmental human figures occupy 1 to 4 percent of frame height and appear from behind or at a three-quarter angle. Seventh, garments follow a set of four principles: structure in the fabric body, breath in sheer layers, restraint in ornaments and a dominant color with limited accents.

Installing into Codex

The skill is installed by copying the inner xianxia-visual-director directory into the Codex skills folder. On macOS or Linux:

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 PowerShell the equivalent copy command uses Copy-Item -Recurse -Force targeting the same path under $env:USERPROFILE\.codex\skills\. After installation, restart Codex or refresh the skill list. The skill is then available as $xianxia-visual-director in any prompt. The README warns that if the target directory already exists, the user should back it up before overwriting.

Scene and Style Routing Options

The skill uses two independent routing dimensions that can be combined freely. Scene routes determine spatial scope: single-realm (one location or landmark such as a heavenly gate, observatory or suspended library) or celestial settlement (a full inhabited celestial civilization with districts, streets, courtyards, cloud ports and waterways). Style routes determine visual register: bright transparent xianxia (clear air, rich materials, precise architectural detail without neon colors or global orange-gold filtering) or eastern sky megastructure (a cropped or occluded giant architectural fragment that rises past the frame edge, with the viewer positioned below the mass). A third route, the celestial grand realm canon, adds a quieter, more expansive register with low cloud seas, a single primary motion and soft high-altitude diffused light.

A minimal invocation provides only a scene idea. A full invocation specifies the aspect ratio (16:9, 21:9, 4:3, 3:2, 4:5 or 9:16), the scene route, the style route, camera intent, spatial scale intensity and saturation strategy alongside the scene description.

Standard Output Structure

Every response from xianxia-visual-director includes five components. Parameter lock documents the confirmed aspect ratio, routes and scale settings. Visual direction describes the spatial intention, camera position, focal length and compositional priority in prose. The full positive prompt specifies lens height, viewing distance, tilt angle, focal length, all five spatial layers, scale evidence items, breathing space distribution, figure clothing, color budget and dominant light direction. Negative constraints list what must be absent: railings, flat composition, uniform haze, over-saturated filters, symmetrical mirror compositions and visual noise. Three derivative directions suggest variations in camera angle, weather, time of day or compositional shift that extend the current scene.

The README notes a companion skill, xianxia-cinematic-video-director, which handles multi-shot video prompt sequences and camera movement planning. The two skills are meant to share a single set of locked parameters: aspect ratio, architecture, figures, materials, weather and light direction should be locked once and not re-decided independently in each tool.

Reference Files and the Repository Layout

The inner skill directory follows the standard Codex skill structure. SKILL.md is the primary file that the agent loads on activation. The agents/ directory holds openai.yaml, which configures how the skill is loaded in OpenAI Agent-compatible contexts. The references/ directory groups supporting material into topic files: aspect-ratios.md, celestial-grand-realm-canon.md, celestial-realm-route.md, composition-color-light.md, eastern-sky-megastructure-style.md, prompt-examples.md, visual-dna.md and xianxia-master-rules.md. These reference files document the specific rules that the skill applies, the rationale behind them and worked examples of correct and incorrect prompt construction. The prompt-examples.md file is particularly useful for understanding how the routing system interacts with concrete scene descriptions before writing a real invocation.

Scope Limits and the Absence of a License

xianxia-visual-director generates structured image prompts. It does not call any image generation API and does not produce images directly. The README states that image generation should only occur when the user explicitly requests it and a generation capability is available. The skill is built for the Codex agent skill system and the README mentions compatibility with Agent-compatible tools, but the skill file contains an openai.yaml configuration under agents/, so platforms using the Agents framework can load it without Codex. The skill does not guarantee platform-specific support outside what the agents/ directory configures.

The repository carries no open source license. The README states that public visibility does not equal permission to copy, modify or redistribute. Developers who want to embed the skill in a product or modify the reference files must obtain explicit permission from the author.

Editorial conclusion

Artists and developers generating Eastern xianxia or sky megastructure imagery with a Codex-compatible agent will find xianxia-visual-director saves significant iteration time by enforcing spatial rules that image models frequently violate without explicit guidance. Users who work with image generation tools directly and do not use an agent skill system have no path to adopt it. The repository carries no license at all: the README states that public visibility does not grant permission to copy, modify or redistribute, so teams considering redistribution or product integration should contact the author first.

Frequently asked questions

Official sources

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