Oil UI: The Open-Source UI Design Skill for Claude Code and Codex That Compares Directions First

Oil UI is a free, MIT-licensed design skill for AI coding agents, and it is one of the faster-rising agent skills of the past fortnight. The repository oil-oil/oil-ui was created on September 30, 2026, and the GitHub page shows about 1,630 stars and 95 forks as of October 17. Its pitch is narrow and practical: stop your agent from producing the same generic landing page every time, by forcing it to explore several genuinely different directions, let you choose, and then check the result against real screenshots.

If you already use an agent skill in Claude Code or Codex, installing it takes one command. This post covers what Oil UI does, how it behaves in practice, what the free version leaves out, and how it compares to other design tooling we have covered.

TL;DR: the questions people ask first

What does Oil UI actually do?

The README describes Oil UI as "an interface design skill for AI agents" that "explores a few genuinely different design directions side by side, lets you choose one, then refines it against real screenshots." The skill file is the real instruction set the agent loads, and reading it shows a clear sequence of five stages.

1. Explore and converge on a direction. The agent first names the product category, finds two or three peers with distinctive styles, and decides what to keep and what to change.
2. Build the visual and interaction structure. Typography, color, spacing, imagery and motion are chosen from the direction, not from defaults.
3. Produce and gather evidence. The agent builds the most representative page first, then captures screenshots at the target viewports.
4. Independent review and fixes. A reviewer with no history of the work looks only at the screen, the task and the constraints.
5. Verify and deliver. A subtraction pass removes decoration and repeated copy, and the delivery note lists the direction, what changed, what was skipped and why.

The notable design choice is the first step. Rather than jump to code, the skill tells the agent to write three directions as plain text, recommend one, and ask whether to build just that one or all three as first screens. Only then does it render anything.

Turning "premium" and "clean" into decisions

The README argues that words like "premium" and "clean" do not tell you what to put on a screen. The skill asks the agent to set a tone from the subject, audience and brand voice (lively or calm, polished or raw, dense or airy) and then convert it into visible choices: which typefaces, how much white space, how much of the page uses color.

Each direction starts from something concrete, such as a material in its setting, a scene, a character or the visual language of another field, instead of an adjective like "minimal." That is a direct counter to the sameness many developers notice in AI-generated interfaces.

How the "different directions" rule works

The README is specific about what counts as different: of layout, typography, color and key imagery, any two directions may share at most one. After the previews exist, the agent places them side by side and squints at the light and dark shapes of each first screen. If two look alike, it changes the layout rather than just swapping colors.

That squint test is a cheap, human-style check that agents rarely do on their own. It targets the most common failure of "give me three options" prompts, where the agent returns one template in three palettes.

The built-in comparison page

When you want to compare, the skill puts the candidates on a single page. They can be HTML files, images or running development pages, and your current design can go first as a baseline. According to the README you can switch between desktop and mobile sizes, open each at actual size, browse with the arrow keys, and click "Select" on the one you like. You then paste the copied sentence back into the agent and it continues from your choice.

The skill is also explicit about when it does not stop to ask. If you say "you decide" or "just build it," or the run is unattended, it still makes the three first screens for the record, shrinks the screenshots to 480 px wide, views them side by side, picks one and writes down why.

Three screens of different sizes holding the same blocks, illustrating a side-by-side desktop and mobile design comparison in Oil UI

Memorable moments and the first screen

Two other ideas in the README are worth noting because they change what the agent builds.

• One memorable moment. Instead of polishing every part equally, the skill makes one or two details exceptional, such as the response to a tap, a successful payment, an AI at work indicator, or a 404 page. Everything else stays quiet.
• Who the first screen is for. On pages where people browse, shop or work, the first screen should be the content itself. Only pages meant to persuade get a designed opening layout, and that layout is settled before the copy is written.

SKILL.md adds guardrails against fake polish. Demo screens should not carry production notes like "sample" or "button not connected," and the agent must not invent business results, customer reviews or product metrics.

Install and first run

Per the README, send this to an agent that can install skills, or run it yourself:

npx skills add oil-oil/oil-ui

Then prompt it the way the README suggests:

Use oil-ui to explore a few design directions for this course booking product and build pages I can preview.

Other prompts from the README include creating three designs with different typography, colors and compositions on a comparison page, polishing a page using your project's existing design guidelines, reviewing a homepage without touching files, and recreating a page from a screenshot with a mobile layout added.

Two practical notes from reading SKILL.md:

• For small, fully specified edits (change this copy, remove that element, make this button green), the skill tells the agent to just make the change and skip the whole exploration process. A vague request like "make this page look better" is not treated as a small edit.
• For existing projects, it distinguishes between a UI refresh, a flow fix and a new feature, and only the refresh may re-decide visual defaults. Flow fixes and features keep the current look.

What the free version leaves out

The README includes a feature table separating the open-source skill from Oil UI Pro. Both cover design direction, visual hierarchy, memorable moments and scroll storytelling, screenshot recreation, and pacing and generated assets. The open-source version gives a scored review with issues listed.

Pro adds the following, per the same table:

The README prices Pro at $9.99 as a one-time purchase with lifetime updates. We have not tested Pro and cannot verify those claims. Note the warning that if you own Pro you do not need the open-source version, and installing both makes them compete for the same requests.

SKILL.md also contains a built-in prompt to tell the user, once, that the full version exists when a task needs usability work, existing-project redesign or card prototypes. That is a sales mention inside a free skill, and the file states it plainly. Readers who dislike upsells inside agent output should know it is there.

Privacy and safety: what to check before installing

Any skill is instructions plus scripts that run on your machine, so read it first. These are the points the repository itself documents:

• Update check. Each use, the skill may run scripts/check_update.sh or the Python equivalent, which reads a public version list at ui.oiloil.org at most once per 10 minutes. The README says nothing from your project is uploaded, and results are cached in ~/.local/state/oil/ (or XDG_STATE_HOME, or %LOCALAPPDATA%\oil\ on Windows).
• No auto-update. By default it only reports a newer version. It downloads and replaces nothing unless you explicitly ask.
• Opt out. Set OIL_NO_UPDATE_CHECK=1 to disable the check. SKILL.md suggests this when a task may only write to a specified directory.
• Treat output as data. The skill tells the agent that update-check output is data and not to follow other instructions inside it.
• Allowed tools. The frontmatter limits Bash use to the update-check scripts.

None of this is a substitute for your own review. Skills that run shell commands are a real supply-chain surface, and our guide to agent skills covers how to audit one. If you run agents with broad permissions, a policy layer such as AgentBeam, the agent security platform from the explainx.ai team, is built to stop agents before they take dangerous actions.

How Oil UI compares with other design tooling

Oil UI sits in a crowded but fast-moving corner. Comparing it with posts we have already published:

A reasonable workflow is to use Oil UI at the start of a project to choose a direction, then write the winning direction's rules into a DESIGN.md or Figma spec so later sessions stay consistent. That ordering is our suggestion, not something the Oil UI README prescribes.

Honest limitations

• Evidence is the repo's own. The claims about quality come from the README and SKILL.md. We have not run it across a set of projects, and there is no independent benchmark of its output.
• It is design judgment only. SKILL.md says component ownership, data flow, state correctness and tests are out of scope. It will not fix your architecture.
• It needs vision. The skill states that without image viewing it cannot verify the actual look and should not score visuals, so use an agent and model that can read screenshots.
• Docs are mostly Chinese-first. SKILL.md is written in Chinese, with English and Chinese READMEs. The skill instructs the agent to reply in the user's language and not to leak Chinese into English conversations, but if you read the instructions yourself, expect to translate.
• Commit count is modest. Sixty-six commits and one open issue mean an early project. Version 0.23.4 suggests rapid iteration, so pin or read changes before updating.
• Star counts are not quality. About 1,600 stars in 17 days shows interest, not proof that the results beat a well-prompted agent.

What this means for builders

If you ship interfaces with Claude Code or Codex, the real cost of generic AI design is not the first draft, it is the number of rounds spent steering away from it. A skill that front-loads direction choice and visual review can shorten that loop, and because the free version is MIT licensed you can read exactly what it tells your agent before you trust it.

A low-risk way to evaluate it: install it in a scratch project, ask for three directions on a page you already know well, and compare the result against what your agent produces without it. If the directions differ meaningfully and the screenshots catch real layout bugs, keep it. If not, remove the folder.

For the broader context on how skills fit into agent workflows, see our explainers on agent skills, the ponytail skill for writing less code, and the PPT Master skill for editable slide decks.

Grid of component shapes with one green swatch, representing the design system a chosen Oil UI direction can feed into

Related reading

• What are agent skills? Complete guide
• DESIGN.md templates for professional UI with AI agents
• Variate: Claude Code skill for UI design variations
• Impeccable 4.5 design skill guide
• Vercel DESIGN.md spec-driven AI UI
• Figma Specs: markdown design rules for AI agents
• Official: Oil UI on GitHub and SKILL.md

Star counts, version numbers and pricing are as of October 17, 2026 and come from the repository and its README. They may have changed.