Ian Xiaohei Scenes: a Codex Skill for Chinese Article Illustrations

The problem Ian Xiaohei Scenes solves, and who it is for

Chinese article writers have a specific illustration problem. A generic image prompt produces something decorative that could sit under any post. A diagramming tool produces a flowchart that flattens a lived situation into boxes. The README frames the gap directly: the skill's goal is to first understand the real situation inside the content, then turn one abstract judgement into a visible physical scene.

The formula the repository repeats is a fixed cast: Xiaohei, one real object, one physical action, a short Chinese label, and negative space. The stated intent is that the reader sees a small, light, slightly odd scene and recognises their own situation within a second. That is a narrower target than illustration in general. It is aimed at people writing about work pressure, the state of being an employee in the AI era, creator blocks and project post-mortems.

The README is equally explicit about who should walk away. Commercial key visuals, brand posters, polished flat illustration, traditional flowcharts, architecture diagrams, course slides, chat UI, app screenshots, dashboards, and anything needing strictly editable vector source files are all listed as unsuitable. If your article needs a diagram of a system, this is the wrong tool and the repository says so.

How the skill works: master images, invariants and a QA pass

The mechanism is a nine-step workflow, and the interesting part is step three. In standard mode the agent first locks onto one of the six master images (01 through 06) as a style anchor. In easter-egg mode it locks onto master 07, the long-scroll story image. From there it writes out the master's invariants, the variation points for the current content, a three-second comprehension sentence, and failure signals.

That is a deliberate constraint. Instead of asking an image model for a fresh composition, the agent is told to hold proportions, negative space, real-object texture, Xiaohei's action and the narrative relationship, then vary only what the content demands. The README warns against mechanically reproducing the object combinations and compositions of the masters. So the masters are a measuring stick, not a stencil.

Each image is then generated with a separate call to the image model, and every result goes through a QA checklist covering aspect ratio, negative space, real-object presence, Xiaohei's action, Chinese labels, whether it reads as a PPT slide, and whether it is a copy of the master. The final PNG is saved and reported with its purpose and path. The workflow is documented in the skill's own SKILL.md and references directory rather than in the root README, so the root file is a shareable overview, not the operating manual.

Installing the skill into Codex and running a first shot list

The repository is cloned, then only the subdirectory ian-xiaohei-scenes/ is copied into the Codex skills directory. The root README, LICENSE, NOTICE and examples exist for GitHub readers and are not part of the install.

git clone https://github.com/helloianneo/ian-xiaohei-scenes.git
cd ian-xiaohei-scenes
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R ./ian-xiaohei-scenes "${CODEX_HOME:-$HOME/.codex}/skills/"

The copy targets ${CODEX_HOME:-$HOME/.codex}/skills, so it respects a custom CODEX_HOME if you set one and falls back to ~/.codex otherwise. After that, the skill is invoked by name from inside Codex. A sensible first run is planning only, with no image generation, so you can judge the shot list before spending model calls.

Use $ian-xiaohei-scenes 先不要生图。
请分析下面这篇文章哪里适合做“小黑 + 真实物件 + 物理动作”的正文配图。
输出 5 张左右的 shot list。

<粘贴文章>

The expected output is roughly five candidate shots, each tied to a situation in the article. If the shot list reads like a list of section headings rather than physical actions, the content is probably a methodology piece and belongs with the 1.0 illustrations skill instead.

Standard mode versus the long-scroll easter-egg mode

The two modes differ in format and in what they can carry. Standard mode produces a 16:9 body image on a pure white background: one real object scene, one core physical action that Xiaohei must perform, two to four short Chinese labels, and a small amount of blue, pink, yellow, green or red accent. Easter-egg mode produces an ultra-wide long-scroll story image on a near-white background, with a hand-drawn curved path, five to eight real-object nodes, Xiaohei participating at every node, starting on the left and converging on the right. The README rules out numbered timelines and PPT flowcharts for that mode.

The constraint that matters most is stated bluntly: one standard image carries one core physical action. The second is a diagnostic. If you remove Xiaohei and the image still works completely, Xiaohei was decoration and the composition has failed. That test is more useful than any aesthetic guidance in the repository, because it catches the most common way these images go wrong.

The long-scroll mode is where the personal-experience nodes live. The README says those nodes can stay as style anchors, but when generating a new image you should replace them with the current user's own facts and nodes. Reusing the author's biography as content is a misuse the documentation anticipates.

Where it breaks: text rendering, drift and the wrong genre

The limitations are documented rather than hidden. AI image models can produce wrong characters, hallucinated labels, style drift and extra titles, and the README states that every generated image needs to be checked afterwards. The recommended remedy for badly mangled Chinese is to reduce the number of label words and regenerate. That is a real cost: short labels are more stable, which means the format cannot carry explanatory text, and any image that needs a sentence to make sense is outside the design.

Style drift is the second failure mode. The masters are described as a quality bar, not something to trace, and the QA checklist explicitly includes non-master-replication as a criterion. An agent that copies the master composition too faithfully produces an image that does not match the article; an agent that departs too far loses the visual identity that made the skill worth installing. That tension is not resolved by the repository, it is managed by the checklist and by you.

The third failure is genre. If the article is a methodology breakdown, a process explanation or a structural analysis, the visual core of 1.0 (pure white hand-drawn explanation) fits better, and the README's own comparison table says so. Long paragraphs, complete flows and dense explanations cannot be pushed into a single image here.

The 1.0 illustrations skill, and how the approach differs

The obvious alternative is the author's own earlier project, Ian Xiaohei Illustrations, referred to as 1.0. The difference is not quality, it is visual core. 1.0 is a pure white hand-drawn explanation image: it is built to break down an argument, a process, a structure or a cognitive model. 2.0 is a real-object scene on what reads as a white photography studio set, built to express a situation, an emotion, a project story or a product's evolution.

Choosing between them is a question about your content, not your taste. A tutorial that walks through four steps wants 1.0. A retrospective about a launch that went sideways wants 2.0. The README's comparison table is short and worth reading before installing either, because installing the wrong one produces images that are technically on-style and narratively wrong.

The same author also publishes Ian Handdrawn PPT, a skill for Chinese hand-drawn technical PPT-style page images, and a curated list of Claude Code skills. If your need is a slide rather than a body image, the PPT skill is the closer fit.

Maintenance, licence and what an upgrade actually costs

The repository is MIT licensed, and the LICENSE file sits at the root alongside NOTICE.md. MIT is permissive: you can reuse and modify the skill files, and the practical obligation is preserving the copyright and licence notice. Nothing here suggests the example images carry separate terms, but the repository does not spell out image licensing either, so if you plan to publish generated images commercially, that is a question for your own reading of LICENSE and NOTICE.md rather than something this article can settle.

On maintenance, the last push to the default branch was on 2026-06-04, the same day v1.0.0 was released. The repository is not archived. There is no second release in the repository, so there is no upgrade path to describe and no deprecation history to weigh. Practically, the upgrade cost of this skill is not a migration: it is a folder copy. Because installation is a recursive copy of ian-xiaohei-scenes/ into your skills directory, pulling a newer version means re-running the copy and being aware that any local edits to SKILL.md or the references files will be overwritten unless you keep them elsewhere.

The other cost is per-image. Each illustration is a separate model call, and the README's workflow treats regeneration as normal rather than exceptional. A five-image shot list is five generations plus whatever regeneration the QA pass forces.

Editorial conclusion

Adopt it if you already write Chinese articles or project retrospectives and want a repeatable visual language rather than one-off prompts, and if you accept that every generated image needs a manual pass for wrong characters and style drift. Do not adopt it for commercial key visuals, editable vector sources, dashboards or dense diagrams; the README lists those as out of scope. Before you commit, open ian-xiaohei-scenes/references/qa-checklist.md and examples/prompts.md and confirm the checklist matches the kind of image you actually need, because the skill's output quality is bounded by the image model you connect to it, not by the skill itself.

Frequently asked questions

Official sources

1. helloianneo/ian-xiaohei-scenes on GitHub
2. License: MIT
3. Project website
4. README
5. Releases