Improve UI Skill

What is the improve-ui skill?

improve-ui is an agent skill from the ibelick/ui-skills repo. It audits one coherent product surface against the system that actually governs it, preserves the product's identity and reuses existing design owners. It prefers no finding to an unsupported one.

The skill is strictly read-only on product source. It writes plans only for the changes you select, and a different agent carries them out. The only files it creates or edits live under design-plans/.

How a session runs

1. Select the surface: one deployable application and one coherent surface family, traced from routes and layouts
2. Reconstruct the local system from DESIGN.md, repository guidance and the tokens, primitives and variants on the traced path
3. Prove each candidate finding with a contract, a runtime path and a single correction
4. Vet every finding by re-opening its sources and trying to falsify it
5. Report the survivors in a table, at most three, and name what to improve first
6. Write one self-contained plan per change you select

What you get back

• A Design language block: audited surface, design sources, documented decisions, governing owners and consumers, and explicit exceptions
• A Findings table with problem, evidence, proposed change, scope and confidence for each row
• An Improve first pick: the single finding with the strongest evidence and the biggest payoff
• Or the plain result No supported findings were found.

Who it is for

Best for

• Reviewing or refining an interface without replacing its identity
• Investigating design-system drift in a real codebase
• Preparing a design handoff that another agent can execute without your context

Not for

• Editing code directly. If asked to fix or improve, the skill offers a plan and never implements it
• Accessibility, metadata or performance reviews. It discards those findings unless you request them, and sibling skills in the same repo cover them
• Judging hierarchy or density from source alone. Those need rendered or user evidence

Use it with UiChemy

improve-ui suits a surface that already lives in a codebase with design rules. If that build came from an AI tool and you want it as WordPress, UiChemy AI to WordPress imports it into Elementor or Gutenberg. Audit the source first, then convert.

How to install Improve UI

git clone https://github.com/ibelick/ui-skills.git

1. Clone the repo

   Run the command above. The skill lives in skills/improve-ui.

2. Copy the whole folder

   Copy skills/improve-ui into your agent's skills directory. For Claude Code that is ~/.claude/skills/ for every project or .claude/skills/ inside one project. Keep references/plan-template.md with it, since the planning step reads that file.

3. Start with an audit

   Prompt the agent: Use improve-ui to audit the primary product surface, identify supported UI problems, and recommend what to improve first. Don't modify anything or write plans yet.

Check that it loaded

Run the audit prompt in a new session. You should get a Design language block, a Findings table with at most three rows and an Improve first pick, with no files changed.

Read the official instructions on GitHub

Key features

• Read-only boundaryThe agent never modifies product source and writes only under design-plans/. It installs no dependencies, runs no formatters and makes no commits or pushes, and design documentation changes are recorded in the plan for its executor.
• One surface at a timeThe skill honors the scope you give. For a broad request it picks one deployable application and one coherent surface family that represents a primary product task, and it states that choice.
• Trace, don't grepWork starts from the surface's routes and layouts and follows compositions, shared components, variants, resolved tokens and styles. A connection counts only when proven through rendering, imports, props, configuration or CSS inheritance.
• Local system reconstructionThe agent checks DESIGN.md, repository guidance and surface-local docs, and uses a source only after proving it is current. Drafts and proposals describe future intent, and having no design docs is not a finding.
• Three-proof gateA candidate survives only with a contract (a binding design decision or a direct contradiction in the same task), a runtime path to the affected surface, and one correction that needs no invented product intent.
• Scope filterA finding must change visual presentation, interface copy, layout, component styling or conformance to a documented design rule. Behavior bugs are rejected, and accessibility, metadata and performance findings are discarded unless requested.
• Vetting passBefore reporting, the agent re-opens every cited source and tries to falsify each candidate. It deletes any finding whose rule does not govern that surface, whose difference looks deliberate or whose evidence supports several fixes.
• Capped, ranked reportSurvivors are ordered by confidence, user impact, reach and correction cost, and the report stops at three. Any row missing a required column, including Confidence, is deleted.
• Self-contained plansFor each selected change the agent writes one plan from references/plan-template.md: evidence chain, design decision, reuse, changes, scope, validation, stop conditions and documentation updates. It asks which findings to plan first.

Frequently asked questions