smart-illustrator: a Claude Code skill that picks an illustration engine per diagram

A skill is a markdown file, not a plugin

Smart Illustrator is an intelligent article illustration Skill for Claude Code, and the README explains what that word means before it explains anything else.

Skills are prompt-based extensions for Claude Code that give Claude specialized capabilities. Unlike MCP servers that require complex setup, skills are simple markdown files that Claude loads on demand.

That distinction shapes everything about how this project is built and how you adopt it. There is no server, no daemon and no protocol. The repository root contains a SKILL.md, a prompts/ directory, a references/ directory, a scripts/ directory, a styles/ directory and an assets/ directory. The skill is the markdown, and the scripts are optional helpers the skill can call.

The primary language recorded for the repository is TypeScript, and that is the scripts. The install options in the README are explicit about this. Option A clones the whole repository into the Claude Code skills directory, and Option B copies individual files if you only want the skill without the scripts:

# If you only want the skill without scripts
cp -r smart-illustrator/SKILL.md ~/.claude/skills/smart-illustrator/
cp -r smart-illustrator/styles ~/.claude/skills/smart-illustrator/

So the minimum viable install is a markdown file and a styles folder, and the scripts are what make the difference between producing prompts and producing images.

Three engines, and the priority order between them

The v1.4.0 release added the tri-engine system, which is the current shape of the project. It introduces a new Excalidraw engine for hand-drawn concept diagrams, and the priority order is Gemini, then Excalidraw, then Mermaid. All diagram engines now output PNG by default.

The three engines do genuinely different jobs, and the feature list names them precisely. Gemini API for creative visuals, at 2K resolution. Excalidraw for hand-drawn diagrams. Mermaid CLI for structured diagrams. All three output PNG by default.

That default matters more than it sounds. Mermaid in particular normally lives in a web page as a code block, and rendering it to a PNG means the illustration is an image file like any other, which is what you need if the output is a newsletter or a video thumbnail rather than a documentation site.

The engine selection is automatic by default, and you can override it. The --engine parameter takes auto, gemini, excalidraw or mermaid, and the --mode parameter takes article, slides or cover. The automatic choice is made on content type: a concept that wants a visual gets Gemini, a diagram that wants to look sketched gets Excalidraw, and a diagram with a formal structure gets Mermaid.

There is also a --mermaid-embed flag, which embeds Mermaid code blocks instead of exporting PNG, for when you want the output to stay editable and live in the document.

Position detection is the part that is actually clever

The reason the project exists is stated in the Why section. Creating illustrations for articles is time-consuming: manual design takes hours, stock photos lack context, and generic AI tools do not understand article structure. Smart Illustrator combines intelligent position detection, the tri-engine system, and cover learning to generate contextual illustrations in minutes.

Position detection is the interesting piece. The feature list describes it as analysing article structure to identify optimal illustration points, and the illustration count guidelines give a sense of the heuristic. A short article of under 1000 words gets 1 to 2 images, a medium one of 1000 to 3000 words gets 2 to 4, a long one over 3000 words gets 4 to 6, and tutorials or guides get 1 per major step.

The count is auto-determined by article length unless you pass --count. So the tool is making an editorial judgement about where a reader would want a picture, which is the judgement a person would otherwise spend the afternoon making.

The illustration types are also enumerated, and they are content categories rather than styles: flowchart, sequence, mindmap, concept, comparison, scene, metaphor. Each type maps onto an engine choice, which is how the automatic selection works in practice.

The target audience is listed as newsletter writers, YouTube creators, technical bloggers and course instructors, and the when-to-use is high quality illustrations for articles, YouTube thumbnails with best practices, or a consistent visual style across a content series.

Cover mode and the platform presets

Cover Mode is a separate mode for generating high click-through rate YouTube thumbnails with best practices built in, and it takes a different set of parameters. The --mode parameter takes article, slides or cover, and in cover mode the --topic parameter gives the cover topic as an alternative to an article path, and --description gives the cover visual direction.

The --platform parameter selects the cover format, with presets for youtube, wechat, twitter, xiaohongshu, `landscape` and `square`, and it defaults to youtube. That is a per-platform size and layout decision rather than one output scaled to fit, which is the right way round for a thumbnail.

The other modes are worth separating. In article mode you pass a path to a markdown file and get an illustrated version back. In slides mode the tool prepares a slide deck rather than an article. The --no-cover flag skips cover generation in article mode, and --prompt-only outputs the prompts without calling the image API at all.

The prompt-only mode is the most interesting one to know about, because it decouples the layout decision from the generation. You can run the tool to get the prompts, edit them by hand, and then generate. The output files list shows what a full run produces: the original article, an article-image.md with the illustrations, a cover PNG at 16:9, and content illustration PNGs at 3:4 numbered from one. The size difference is the point: covers are wide, in-article illustrations are tall.

Styles, resumption and brand customisation

The style system is a set of markdown files loaded by name, and the --style parameter takes light, dark or minimal, with light as the default. There is a --list-styles flag that lists everything available in the styles directory, and the style name maps to a file at styles/style-{name}.md.

Because the styles are markdown in a directory you can edit, the extension point for your own brand is the same mechanism the built-in styles use. The feature list says as much: Brand Customizable, modify styles/ to apply your brand style. The Cover style is one of the built-in ones, along with Light, Dark and Minimal.

The resume behaviour is a practical feature for a tool that calls a paid API. Resume Generation skips already-generated images and regenerates specific ones, so a run that failed halfway, or that you want to redo with a different style for one diagram, does not cost you a full regeneration.

The style and the engine are separate axes, which is worth noting. The style governs how the image looks and the engine governs how it is drawn, so a Mermaid diagram can be light or dark, and a Gemini visual can be minimal or cover styled.

The output files are written next to the input, following a fixed naming pattern, which makes them easy to script against.

Running the scripts directly, and what the setup needs

The skill can be used through Claude Code, but the underlying scripts can also be run on their own, and the README documents them.

The prerequisites are listed in full. You need the Claude Code CLI installed, the Bun runtime for the scripts, the Mermaid CLI for Mermaid diagrams, which installs with npm install -g @mermaid-js/mermaid-cli. Excalidraw export dependencies are optional and install from the scripts directory with npm install followed by npx playwright install firefox. And a Gemini API key is optional, for the creative visuals.

The individual image script takes a prompt or a prompt file and an output path, and runs through npx bun:

export GEMINI_API_KEY=your_key

# From prompt text
npx -y bun ~/.claude/skills/smart-illustrator/scripts/generate-image.ts \
  --prompt "A concept diagram showing..." \
  --output image.png

There is a matching form that takes --prompt-file instead, so the prompts the skill writes can be reviewed and edited before generation.

The Playwright Firefox install for Excalidraw is worth noticing, because it means the Excalidraw path renders through a real browser rather than a native exporter. That is a heavier setup than the other two engines, and it is the main reason the skill is a Gemini-first tool with the other two as fallbacks.

The project is MIT licensed, and the release history is short. v1.4.0 on 2026-02-12 added the tri-engine system and article illustration constraints, v1.3.0 on 2026-02-10 added the Mermaid visual enhancement, and v1.0.0 on 2026-02-01 was the initial public release. The last push was on 2026-06-26.

The status note is the most useful paragraph in the README

The Status section is a quoted block, and it is worth reading in full because it tells you what kind of project this is before you build anything on it.

It says this is a public prototype that works for the author's demos, but does not yet cover all input scales and edge cases. Output quality varies based on model version and input structure, and results may fluctuate. The primary focus is demonstrating how tools and systems work together, not maintaining this codebase. And if you encounter issues, the request is to submit a reproducible case, with the input, the output file and the steps to reproduce.

That is an unusually clear statement of scope, and it is more useful than a badge would be. The line about output quality varying with the model version is the one to sit with, because it means the same input can give a different result after a Gemini model update, and a workflow that depends on consistency needs to know that.

The repository also has a Chinese version of the README at README.zh-CN.md, and the project is packaged as a Claude Code skill, which means it inherits the distribution model of that ecosystem rather than the npm one.

The alternative worth naming is a plain prompt file. If you only need one diagram for one article, a hand written prompt to an image model, or a Mermaid diagram you write yourself, gets you there with none of this setup. What the skill adds is the position detection, the engine routing, the cover mode with its platform presets, and the resume behaviour, and that is worth the setup only if you are producing illustrated content as a repeated workflow rather than a one-off.

Editorial conclusion

Adopt smart-illustrator if you write articles, newsletters or course material and want illustrated drafts in minutes rather than hours, and you are comfortable with a tool whose own status note says it is a public prototype that does not yet cover all input scales and edge cases. Do not adopt it as a production pipeline, because the maintainer says the primary focus is demonstrating how the pieces work together rather than maintaining the codebase. Before you install, decide which engine you want, since the three have very different setup costs, and note that all three engines output PNG by default, and that the Gemini key is optional.

Frequently asked questions

Official sources

1. axtonliu/smart-illustrator on GitHub
2. Issues
3. License: MIT
4. README
5. Releases