Ian Xiaohei Illustrations: a Codex Skill for Chinese hand-drawn article images

What problem the Xiaohei skill solves for Chinese writers

Most image prompts fail Chinese writers in the same way: they produce a picture that is adjacent to the article rather than a picture of the article's argument. The README frames the goal narrowly. The skill is meant to first understand the cognitive anchors in a piece, then turn one judgement, process, structure, state or metaphor into a memorable 16:9 hand-drawn explainer. The repository states plainly that it is not a general illustration prompt and not a PPT infographic template.

The intended user is someone writing Chinese articles, posts, blogs, Notion documents or methodology content who wants body images with a consistent visual language. The README also lists who should stay away: people who want commercial illustration or brand key visuals, traditional infographics, architecture diagrams, children's cartoon or sticker styles, or strictly editable vector source files. That second list matters more than the first. The skill is opinionated about output, and the opinion is the product.

The Xiaohei character and the visual rules behind it

Xiaohei is a black solid body with white dot eyes, thin legs and an empty expression. The README is explicit that Xiaohei is not a mascot, not a sticker and not a corner decoration, but an absurd worker taking part in the system. The test the repository gives is blunt: if you can remove Xiaohei and the image still works, Xiaohei was decoration.

The style constraints are equally specific. Pure white background with no paper texture, beige, shadow or gradient. Black hand-drawn line work, thin lines, slight jitter. Generous negative space, with the subject occupying roughly 40 to 60 percent of the frame. A small number of red, orange and blue handwritten Chinese annotations. One image expresses one core action, structure, state or metaphor. The result is meant to be odd and clear rather than cute.

That last distinction is where most style guides stop and this one keeps going. Cuteness is a default attractor for character-driven illustration, and the README spends a paragraph pushing against it. Whether the model obeys is a separate question, but the constraint is at least written down in references/style-dna.md and references/xiaohei-ip.md.

How the skill works: shot list first, image model second

The workflow in the README runs in nine steps. It reads the article, Markdown, Notion content, screenshots or a topic the user supplies. It extracts core viewpoints, cognitive turns, process structures and paragraphs worth visualising. Then it outputs a shot list before generating anything, with one cognitive anchor per image. Each shot gets a structure type chosen from Workflow, a system fragment, before-and-after contrast, character state, conceptual metaphor, method layering, map route or comic panel. The skill then reinvents a low-tech, absurd but plausible physical metaphor, gives Xiaohei the core action, and calls the image model separately for each image.

Separation of planning from rendering is the design decision that carries the most weight. A shot list is cheap to review and cheap to reject, while a generated PNG is neither. The README's own prompt examples lean on this: one asks the skill to produce a shot list without generating images, and specifies that each entry should record which paragraph the image follows, the theme, the core meaning, the structure type, what Xiaohei is doing, and suggested Chinese annotation words.

After generation, the skill checks each image against a QA checklist covering white background, negative space, Xiaohei's action, Chinese annotations, whether it reads as a PPT slide, and whether it copies an old example. Final PNGs are saved to assets/<article-slug>-illustrations/ in the workspace. The skill does not output PPTX, PDF, Keynote, SVG, HTML or Canvas files, and it does not produce commercial posters or dense text infographics.

Installing the Codex Skill and running a first shot list

The repository separates what you clone from what you install. The root holds README, LICENSE, NOTICE and examples for GitHub readers. The subdirectory ian-xiaohei-illustrations/ is the part Codex needs. Clone the repository and enter it:

git clone https://github.com/helloianneo/ian-xiaohei-illustrations.git
cd ian-xiaohei-illustrations

Then copy only the skill subdirectory into your Codex skills folder. The README uses CODEX_HOME with a fallback to $HOME/.codex, so the command works whether or not that variable is set:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R ./ian-xiaohei-illustrations "${CODEX_HOME:-$HOME/.codex}/skills/"

After that, the skill is invoked by name from inside Codex. The README's first example asks for five images:

Use $ian-xiaohei-illustrations 为这篇中文文章设计并生成 5 张小黑怪诞正文配图。

A safer first run is planning only, because it costs one model call and shows you the metaphor choices before any image is rendered. The README gives this prompt shape:

Use $ian-xiaohei-illustrations 先不要生图。
请分析下面这篇文章哪里值得配图，输出 5 张左右的 shot list。
每张图写清楚：放在哪段后、主题、核心意思、结构类型、小黑在做什么、建议中文标注词。

<粘贴文章>

What you should see is a shot list, not files. Each entry names a paragraph position, a theme, a structure type, Xiaohei's action and suggested Chinese annotation words. If the list reads as generic illustration ideas rather than arguments from your text, stop there and revise the article section you fed it. More prompt examples live in examples/prompts.md.

Where the output breaks: Chinese text, style drift and the wrong jobs

The README's own notes section is the most useful part of the documentation, because it admits the failure modes. Chinese text inside generated images is less stable the longer it gets, so shorter annotations are more reliable. Image models can produce wrong characters, hallucinated labels, style drift and extra titles, which is why the workflow includes a post-generation check. The suggested remedy for bad Chinese characters is to reduce the number of annotation words and regenerate rather than to keep editing.

There is a second limitation that is structural rather than technical. The skill produces one image per cognitive anchor. If your article is a step-by-step tutorial with twelve sequential steps, a single hand-drawn metaphor per image will not carry the sequence, and the README's exclusion list already rules out complex architecture diagrams and flowcharts. For that content, a diagramming tool is the right instrument.

The examples folder is another place readers get it wrong. The README says the eight sample images are style calibration, not composition templates, and that you should invent a new metaphor from the current article rather than reuse the objects and layouts. Nothing in the repository enforces that. It is a rule you have to hold yourself to when reviewing output.

Ian Handdrawn PPT and how the two skills differ

The README points to a sibling project, Ian Handdrawn PPT, described as a Skill for generating Chinese hand-drawn technical PPT-style page images. Both come from the same author and both use hand-drawn Chinese visuals, so the names invite confusion.

The difference is the unit of work. This skill targets body images inside prose: 16:9, one cognitive anchor per image, Xiaohei performing a core action, and output saved per article slug. The PPT skill targets whole pages in a presentation format. If your deliverable is a slide deck, the PPT skill matches the artefact. If your deliverable is an article that needs four to eight images distributed through the text, this one does. The README does not claim the two share a prompt format or a style file, so treat them as separate installations rather than a pipeline.

Maintenance, licence and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-06-03. The most recent release listed is v1.0.0 from 2026-05-27. There is no changelog in the repository, so there is no documented upgrade path between versions.

The practical upgrade cost is low and slightly unusual. The installable artefact is a directory of Markdown references plus an agents/openai.yaml file. Updating means replacing that directory under your Codex skills path. Nothing in the README describes a migration step, a config schema version or a state file, so there is no data to migrate. The cost you should actually budget is re-calibration: if style-dna.md or qa-checklist.md changes, previously generated images may no longer match the current rules, and the README's warning against copying old examples becomes harder to follow when your own archive is the nearest reference.

The project is MIT licensed. That permits commercial use and modification, and the repository includes a NOTICE.md alongside LICENSE. The README does not state how the Xiaohei character itself should be attributed in commercial work, so if you plan to publish images built on the character, read NOTICE.md and LICENSE before you rely on the default. This is a description of what the files say, not legal advice.

Editorial conclusion

Adopt it if you write Chinese knowledge or methodology content and already run Codex, because the skill ships a shot list workflow, a style DNA reference and a QA checklist rather than a single prompt. Do not adopt it if you need editable vector output, PPTX or commercial illustration. Before committing, open ian-xiaohei-illustrations/references/qa-checklist.md and style-dna.md, and check that your Codex skills directory resolves through CODEX_HOME.

Frequently asked questions

Official sources

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