Guide · Agent skill
How to use the Better UI Polish agent skill (better-ui)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The better-ui skill is an agent skill that gives an AI coding agent a fixed set of visual polish rules for interface code: border radius, shadows, image outlines, icon swaps and animation timing. This guide explains what an agent skill is, how to install better-ui, how to ask for it, and where its limits are. By the end you will be able to install the skill and request polish review or implementation with clear expectations.
Better UI Polishjakubkrehel/skills · MIT Download the skill Quick start
- 1Download the ZIP. Get the better-ui ZIP from this page and unzip it on your machine.
- 2Choose where to install. Place the folder in ~/.claude/skills/ for all projects, or in a project's .claude/skills/ folder for one project.
- 3Or upload in the Claude apps. Open Settings → Capabilities → Skills and upload the skill there.
- 4Describe a UI task. Ask for a polish review or implementation in plain language, naming the component and interaction.
- 5Check the result. Review the agent's changes, keeping project conventions and checking accessibility separately.
What an agent skill is and what better-ui makes the agent do
An agent skill is a folder containing a SKILL.md file and supporting notes that an AI agent loads when a task matches the skill's description. better-ui is one such skill, described as polishing surfaces, icons and motion with exact values for border radius, optical alignment, shadows, icon states and animation.
With the skill installed, the agent follows specific rules when it writes or reviews user interface code. It sets the outer radius of nested surfaces to the inner radius plus padding plus border width, replaces decorative borders with layered transparent box-shadow values, and outlines content images with a 1px inset line in oklch(0 0 0 / 0.1) for light mode or oklch(1 0 0 / 0.1) for dark mode.
- Press feedback: a pressed button scales to 0.96 over 150ms with ease-out; disabled buttons do not scale.
- Exits: opacity, 4px blur and a -12px translateY over 150ms with ease-out.
- Enters on staged content: stagger groups 100ms apart, each over 300ms with ease-out.
- Icon swaps: cross-fade with scale 0.25 to 1, opacity 0 to 1 and blur 4px to 0px.
- Motion is gated behind prefers-reduced-motion: no-preference, with an opacity cross-fade as the fallback.
- Transitions name exact properties instead of all, and hover styles sit behind @media (hover: hover).
Install better-ui in Claude or a project
Download the better-ui ZIP from this page and unzip it. To make the skill available across all your projects, place the unzipped folder in ~/.claude/skills/. To scope it to one project, place it in that project's .claude/skills/ folder.
In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/better-ui
- Project install: .claude/skills/better-ui inside your repository
Trigger the skill with natural requests
You do not need a special command. Describe the task in plain language that touches surfaces, icons, shadows or motion, and the agent can load the skill when the request matches its description.
Be specific about the part of the interface. Naming the component and the interaction gives the agent the clearest signal.
- Review this card component for visual polish, especially the radius on the nested inner image.
- Add a press effect to the primary button and make sure it respects reduced motion.
- Replace the border on this dropdown with a shadow ring and keep the divider lines.
- Make the play and pause icon swap in this player cross-fade.
Know what the skill covers and what it leaves to other skills
better-ui is opinionated, but the skill states that exact values apply only where no project convention conflicts. Keep the project's component library, tokens and density, and match its motion language wherever no rule gives a value. A deliberate, consistent convention such as a style with no shadows is treated as a preference, not a finding.
The skill defers other topics to sibling skills: text wrapping and font rendering to better-typography, hit areas, keyboard support, ARIA and reduced-motion requirements to better-accessibility, grouping and breakpoints to better-layout, and color tokens and contrast to better-colors. Install those alongside better-ui if your review needs them.
Safety notes: scripts and network
The skill's listing states that it runs no scripts, uses no network connection and lists no requirements. It is a set of written guidance files: agents/openai.yaml, animations.md, enter-exit.md, icon-transitions.md, icons.md, performance.md, SKILL.md and surfaces.md.
Because it is written guidance, the main risk is over-application rather than code execution. Review the agent's changes as you would any patch, especially where a rule overrides an existing design decision.
Tips for getting useful results
Ask for a review first, then ask for changes. A written list of findings is easier to check than a large rewrite.
Give the agent your project's existing tokens and component library so it keeps them. The skill says project conventions take priority.
Check accessibility separately. If focus, keyboard support or reduced motion have not been handled, bring in better-accessibility before shipping.
What people use it for
- Reviewing a card or modal for nested corner radius and shadow-versus-border issues.
- Adding consistent press feedback and reduced-motion-safe fallbacks to a button library.
- Making icon swaps such as copy to copied cross-fade with exact timing.
- Writing a shared written standard for button press, icon swap and entrance animations.
Frequently asked questions
How do I install the better-ui skill?
Download the better-ui ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, you can upload it under Settings → Capabilities → Skills.
Is the better-ui skill free?
The skill is listed under the MIT licence. Check the licence file in the source repository for the full terms.
Does better-ui require anything else to run?
The listing states it requires nothing, runs no scripts and uses no network. It works as written guidance for the agent.
Will better-ui change my design system?
Not by default. The skill says to keep the project's component library, tokens and density, and that a deliberate, consistent project convention is a preference rather than a finding. It is best for teams that want a consistent standard.
What should I use instead if my project has a very different visual style?
The listing says the skill is not for projects that need a fully custom or deliberately different visual language, because its rules are opinionated. For those projects, write your own conventions or skip the skill for styling decisions.
Why does the agent not fix my accessibility or colour issues?
better-ui defers reduced motion, hit areas, keyboard support and ARIA to better-accessibility, and colour tokens and contrast to better-colors. Install those sibling skills to cover those areas.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
better-ui suits front-end developers and designers who want exact, consistent polish values and a shared written standard for press, icon and entrance motion. Teams with a deliberately different visual language, or interfaces where accessibility and reduced motion are not yet handled, should choose something else or pair it with the sibling skills first.
Download the skill