polish

Overview of polish skill

What polish does

The polish skill is a final-pass UI review workflow for catching the small issues that make finished work feel inconsistent, unfinished, or lower quality than intended. It is built for the moment when a screen is already functional and you want to improve alignment, spacing, interaction states, copy consistency, edge cases, and visual smoothness before shipping.

Who should use polish

This polish skill is best for designers, frontend engineers, and AI-assisted builders who already have a working interface and need a structured quality pass. It is most useful when the request sounds like “add finishing touches,” “something feels off,” “make this production-ready,” or “take it from good to great.”

The real job to be done

Users do not install polish just to get generic design feedback. They use it to run a systematic pre-ship review so obvious micro-issues are not missed:

• inconsistent spacing
• off-grid alignment
• missing hover, focus, loading, or error states
• uneven copy tone or labeling
• rough transitions and interaction details

What makes this polish skill different

The key differentiator is that polish is explicitly a last-step skill, not a broad redesign tool. It also depends on upstream design context: the repo requires you to invoke /frontend-design first and, if design context does not yet exist, to run /teach-impeccable before using polish. That dependency matters because the skill assumes there is already a design direction and quality bar to evaluate against.

When polish is a strong fit

Use polish when:

• the UI is functionally complete
• you need a final quality pass before launch
• the main problem is inconsistency, not product strategy
• you can provide a target screen, component, or flow
• you know whether the bar is MVP or flagship

When polish is the wrong tool

Do not use polish first if:

• the feature is still being defined
• core flows are broken or incomplete
• you need major UX restructuring
• you have no design context yet
• the team has not decided how refined the result needs to be

How to Use polish skill

Install polish in your skills setup

The repository does not expose a dedicated install command inside SKILL.md, so most users will add the skill from the source repo through their skills manager. A common pattern is:

npx skills add pbakaus/impeccable --skill polish

If your environment uses a different installer, add the skill from:

https://github.com/pbakaus/impeccable/tree/main/.agents/skills/polish

Read this file first

Start with:

• SKILL.md

This skill is self-contained. There are no extra resources/, rules/, or helper scripts surfaced in the skill folder, so most of the usable workflow is in that single file.

Respect the required dependency chain

Before you call polish, the repo guidance says to invoke:

• /frontend-design

And if there is no established design context yet, you must run:

• /teach-impeccable

This is the most important adoption detail. Without that context, polish will tend to produce shallow “make spacing more consistent” advice instead of a high-confidence finishing pass tied to actual design principles.

Know what input polish needs

The polish skill works best when you provide:

• the exact target: page, component, or flow
• current screenshots or code context
• the intended quality bar: MVP or flagship
• whether known flaws should be fixed now or preserved as TODO
• the shipping timeline or time budget for polish

Those inputs change the output materially. A flagship marketing page should get a different pass than an MVP internal tool.

Convert a rough request into a usable polish prompt

Weak prompt:

Polish this UI.

Stronger prompt:

Use polish on the checkout flow. The flow is functionally complete. Quality bar is flagship. Keep the current structure, do not redesign the information architecture. Focus on alignment, spacing consistency, interaction states, error handling, and copy consistency. We have one day before ship, so prioritize high-visibility issues first.

Why this works:

• it confirms readiness
• it sets scope
• it prevents accidental redesign
• it gives a realistic time horizon
• it tells the skill how deep to go

Use polish on a narrow target first

The argument hint is [target], which is a useful clue: pass a specific target instead of asking for whole-product feedback. Good examples:

• polish pricing page
• polish onboarding modal
• polish dashboard table states
• polish mobile settings flow

Narrow targets usually produce more actionable output than broad requests like “polish the whole app.”

Follow the intended workflow

A practical polish usage flow is:

1. Confirm the UI is functionally complete.
2. Gather design context through /frontend-design.
3. If no design context exists, run /teach-impeccable.
4. Define the quality bar and time budget.
5. Ask polish to review a specific target.
6. Apply fixes by category, not randomly.
7. Re-run polish on the updated result for a final verification pass.

This matches the repo’s emphasis on pre-polish assessment before touching details.

What polish is likely to inspect

Based on the source, polish systematically checks areas such as:

• visual alignment
• spacing consistency
• interaction state coverage
• copy consistency
• edge cases and error states
• loading and transition smoothness

This is useful because it tells you what evidence to provide. If you only paste static UI markup, you may miss feedback on loading, transitions, and states.

Give state coverage, not just the happy path

A common reason polish underperforms is missing state context. If possible, include:

• default state
• hover/focus/active states
• validation errors
• empty states
• loading states
• disabled states
• success confirmation states

This helps the polish skill catch “almost done” problems that users actually notice in production.

Prioritize output by visibility and effort

If you are close to launch, ask polish to classify findings into:

• must fix before ship
• nice to have
• can defer

That makes the polish skill more useful than a generic critique dump, especially when the quality bar is high but time is short.

Practical repository-reading path

Because the folder only exposes SKILL.md, your best reading path is:

1. review the description and argument-hint
2. read MANDATORY PREPARATION
3. read Pre-Polish Assessment
4. use the systematic polish categories as your checklist

That is enough to decide fit and start using the skill without over-reading the repo.

polish skill FAQ

Is polish better than a normal prompt?

Usually yes, if your problem is final-pass quality control. A normal prompt often gives broad opinions or redesign suggestions. The polish skill is narrower: it assumes the work is already built and focuses on the micro-details that are easy to miss late in a project.

Is polish for UI Design only?

Mostly for polish for UI Design and frontend experience quality. The source emphasizes alignment, spacing, interaction states, edge cases, and smoothness, so it is a much better fit for interfaces than for backend architecture or product strategy.

Can beginners use the polish skill?

Yes, but beginners need to provide more context. If you do not yet know what “quality bar” or “design context” means for your project, run the required upstream design skill first. Otherwise the output may feel correct but vague.

Do I need complete code before using polish?

You need a complete-enough implementation or prototype. The repo is explicit that polish is the last step, not the first. If major behavior is still changing, the feedback will be unstable and lower value.

What is the biggest adoption blocker?

The main blocker is skipping the mandatory preparation. If you install polish and call it without /frontend-design context, you miss much of what makes the skill reliable.

Should I use polish for MVP work?

Yes, but tell it the quality bar is MVP. That changes the expected depth. For MVPs, the best use of polish is to catch the most visible inconsistencies and state gaps without spending time on perfectionism.

When should I not use polish?

Skip polish when you need:

• a full redesign
• product discovery
• user research synthesis
• architecture changes
• unfinished core functionality

In those cases, another skill or a direct design/engineering workflow is a better first step.

How to Improve polish skill

Give better targets

The fastest way to improve polish output is to make the target concrete. Compare:

Weak:
Use polish on my app.

Better:
Use polish on the mobile checkout summary card and payment error state.

Specific targets reduce generic advice and increase fix-ready findings.

Set the quality bar explicitly

The source calls out MVP vs flagship for a reason. If you do not specify it, polish may over-review a simple internal tool or under-review a launch-critical surface. Always state which bar you want.

Tell polish what must stay unchanged

If the structure, layout, or branding cannot move, say so. Example:

Polish this settings page without changing the information architecture or component library.

This keeps the skill focused on finishing quality instead of drifting into redesign.

Include known issues that should remain TODOs

The skill asks whether there are known issues to preserve. That matters in real teams. If some defects are intentionally deferred, say so up front to avoid wasted review cycles.

Ask for findings by category

A strong prompt format is:

Use polish on [target]. Group findings into spacing/alignment, interaction states, copy consistency, edge cases, and motion/loading. For each item, say why it matters and whether it is must-fix or nice-to-have.

This aligns with the repo’s systematic approach and makes implementation easier.

Provide screenshots or UI states, not only abstract goals

If you want polish to improve the shipped experience, give it observable material. Strong inputs include:

• screenshots
• component code
• state descriptions
• acceptance criteria
• brand or design-system constraints

The more visible evidence it has, the less it relies on generic assumptions.

Watch for common failure modes

polish results degrade when:

• the feature is not actually complete
• the target is too broad
• there is no design context
• only the happy path is shown
• the team has not defined what “done” means

Most “bad polish output” is really an input or timing problem.

Re-run polish after fixes

A good workflow is not one pass but two:

1. first pass to find issues
2. implementation
3. second pass to catch regressions and newly visible inconsistencies

This is especially useful after changing spacing scales, component states, or copy patterns across multiple screens.

Use polish as a launch checklist, not just a critique tool

For the best results, ask the skill to produce a short actionable checklist you can work through before ship. That turns polish from subjective feedback into an execution aid, which is where this polish skill provides the most value.