qiaomu-design makes Claude Code pick a visual direction before it writes code

The problem is convergence, not drawing ability

The project's argument about why AI-generated interfaces fail is more specific than the usual complaint that the output looks generic. The diagnosis lists five causes: default aesthetics converge, the direction offered is only adjectives, the implementer self-reviews and so introduces bias, the process keeps adding rather than removing, and the result does not survive engineering and Chinese typography acceptance. qiaomu-design is an opinionated Agent Skill for visual direction, implementation and browser-based UI verification, and the emphasis is on the process rather than on a house style. The stated goal is to make the model produce design that does not look like a default AI template, and the mechanism is a loop the documentation describes as divergence, definition, selection, independent review, trimming and real acceptance. The documentation is careful about where quality comes from, saying explicitly that it comes from that closed loop and not from a model name, and that triggering the skill does not by itself switch the agent to a different external model. The default executor is the agent already running the task, and an external model is called only when the user explicitly names it in the current task, keeping isolation, diff review and independent acceptance in place.

The fitting room: four directions you actually look at

The most distinctive feature is the style fitting room, and it is the part that changes the shape of the work rather than just adding a step. Instead of describing four directions in prose, the skill generates four mutually exclusive directions as real mini mockups, writes them to a dated directory under design-previews/, and lets you pick by clicking or with the keyboard, with the chosen direction, the dial settings and the suggestions returned together. The three dials are the other half of the mechanism. The skill reads the design and adapts three dials, adventure, motion and density, by task type, with functional pages converging and open-ended briefs allowed to spread out. So the interaction is not you describing a look in words. The agent produces four artefacts, you react to the artefacts, and the reaction carries a structured payload. The documentation also links a comparison lab for frontend design skills that shows 80 real generated pages from 8 popular variants across 10 tasks, and states that qiaomu-design and one competing skill have completed all of those tasks, which is at least a stated basis for comparison rather than an assertion.

Bans and rules that shape the output

The skill enforces a set of prohibitions, and the design intent behind them is what makes this more than a prompt collection. The rules forbid the purple gradient, forbid Inter, forbid italics, forbid centred layouts, and forbid a set of AI copywriting words, all with the stated goal of eliminating the AI look at the source rather than patching it later. There is a separate Chinese typography rule set, which prefers system font stacks, subsets decorative Chinese fonts, and sets rules for line height, font weight and punctuation, drawing on the W3C clreq requirements, Ant Design and the Apple Human Interface Guidelines. A motion craft kit covers writing, reviewing and naming animations, plus Apple style fluid interactions covering gestures, springs, velocity handoff and transparent materials, credited to the Emil Kowalski system. The reference library is a further argument: 58 real design systems in the Google Stitch format, from sites such as Stripe, Linear and Apple, so that a request can be phrased as reference a particular site and follow its DESIGN.md rather than imitating a screenshot.

The three phase flow and the polish mode

The typical flow is three phases, each waiting for your confirmation. Phase one is diagnosis, combining design reading, the three dials and two or three key questions. Phase two is the fitting room, generating the dated preview directory and returning your chosen direction, dial values and suggestions. Phase three is execution, which starts by establishing a DESIGN.md anchor, then writes the code, then runs the preflight gate and delivers. There is a separate mode for work that already exists. If you ask to polish a page that already works, to remove the AI look without rebuilding it, or to add motion, the skill switches to a polish mode that does not tear the page down, offering six actions: audit, critique, polish, animate, harden and live. The trigger phrases are listed, including redesign, optimise the interface, UI review, reference a particular design and give me a design system, and the documentation is explicit that an existing page goes through the polish route. The practical value of that split is that it stops the common failure where a redesign request causes a rewrite that loses working behaviour.

Installing with the skills CLI, and the manual route

Installation is a single command through a skills CLI.

npx skills add joeseesun/qiaomu-design

After that, in a client that supports Agent Skills, you simply ask for a design in natural language. The documentation also provides a manual route for anyone who prefers to copy the directory by hand, though it says the copy path varies by client and recommends the command above instead.

git clone https://github.com/joeseesun/qiaomu-design.git
cp -r qiaomu-design ~/.claude/skills/qiaomu-design

The prerequisites are listed as a checklist. You need Node.js and npx, verified by running the version command for both. You need a client that supports Agent Skills, naming Codex or Claude Code as examples. If you want the interactive direction feedback, you need a machine where a Node syntax check on the preview server script passes, which is the project's own way of testing that the optional local preview server can run. And if you specifically want the external model called, you need to install and verify the separate model CLI, which is not needed by default. The documentation also gives you a verification step for the install itself.

npx skills add joeseesun/qiaomu-design --list
test -f ~/.agents/skills/qiaomu-design/SKILL.md

The last of those commands checks that the skill file landed where the agent will look for it, which is the kind of check that saves a confusing half hour when a skill appears to be ignored.

What lives in the repository

The tree explains how the skill is organised, because a skill is a package of instructions rather than a program. At the top there is SKILL.md, which holds the persona, the workflow, the dials, the anti-pattern bans and the self-evolution protocol, and a manifest.json. The references/ directory is where the depth lives, and the listing is a design brief in itself. There is a user preferences ledger described as written to by the self-evolution mechanism and holding the highest priority, a style preview specification for the fitting room with its four directions and manual confirmation return, a divergence playbook with axis-level difference checks and 14 aesthetic directions, and a creative prompting file covering seeds, briefs, independent critique, media and trimming. Then there are the motion files, covering craft, review, a vocabulary for turning vague descriptions into precise briefs, and Apple fluid interfaces. Four Carbon files cover foundations, a component selection matrix with a seven-question dossier, complete form and CRUD workflows, and data visualization including chart selection, axes, colour, legends and dashboards, plus a source map covering 319 pages of documentation. A Chinese typography file, a preflight file and the design-systems library of 58 site references complete the set. The top level also has agents/, assets/, docs/, evals/, reports/, scripts/ and tests/ directories, so the project is run and measured, not just documented.

The delivery gate and the honesty caveat

Two things separate this from a prompt collection, and both are about accountability. The first is the delivery gate. There is a preflight checklist that is enforced, and the documentation is blunt that if any single item fails, the work is not delivered. The checklist is described as following Vercel's conventions and covers accessibility, form behaviour, focus traps and protection against dangerous operations, with review output in a file:line format so a finding points at a location rather than a vibe. The engineering checklist reference file is built on the same Vercel guidance plus component behaviour standards. The second thing is the evidence boundary, and the project states it before anything else. The core mechanism comes from controlled comparisons and real project iteration, the repository cases can be re-examined, but each specific project still needs its own test runs, desktop and mobile screenshots and interaction acceptance. That is an unusually clear statement of what a repository of examples can and cannot prove, and it is the right way to read the ten screenshots in the documentation, which come from a controlled comparison and are linked to live interactive originals.

Editorial conclusion

Adopt qiaomu-design if you use Claude Code or another Agent Skills client and your problem is that the model converges on the same generic landing page every time, since the skill's value is the forced divergence and selection step rather than any particular visual style. Do not adopt it if you want a component library or a design system you can import, because the deliverable is a process, not code, and do not adopt it expecting it to run without a client that supports Agent Skills. Verify two things before you commit to it: that the skill loads in your client, which you can check with the list flag and by confirming the SKILL.md file exists, and that the local preview server runs on your machine if you want interactive direction feedback, since that path is optional and separate from the main flow. The practical first step is to add the skill with npx skills add joeseesun/qiaomu-design, then ask for a design and see whether the four mockups arrive before any code does.

Frequently asked questions

Official sources

1. Issues
2. joeseesun/qiaomu-design on GitHub
3. License: MIT
4. README
5. Releases