SkillAgentSearch skills...

interface-refinement

Refine an existing interface with named commands (critique, polish, distill, typeset, colorize ...), a product and design context file, and a static detector of generic UI patterns

Install / Use

npx skills add borghei/Claude-Skills --skill interface-refinement

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

89/100

Supported Platforms

Universal

Our assessment of interface-refinement

interface-refinement scores 89/100 on our quality scale, 1707th of 4,698 Development & Engineering skills we index (top 37%).

Its SKILL.md is 22 KB long, well organised into 30 sections with 1 code example: a thorough specification that gives an agent plenty to work with.

It has 817 GitHub stars, a meaningful sign that others use it.

Substance
30/30
Structure
17/20
Description
15/15
Adoption
12/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so interface-refinement is actively maintained.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-11-10. Automated pattern scan on 2026-11-10. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

interface-refinement compared with similar skills

All 4 of these similar skills score higher than interface-refinement; compare them before choosing.

SkillScoreStarsUpdatedFormat
interface-refinement (this skill)by borghei8981756d agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md
claude-howtoby luongnv8910047.3k2d agoCLAUDE.md
Claude-Code-Game-Studiosby Donchitos10039.7k7d agoCLAUDE.md

Frequently asked questions

How do I install interface-refinement?
Run npx skills add borghei/Claude-Skills --skill interface-refinement. The install tabs above show the steps for each supported agent.
Which AI agents does interface-refinement work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is interface-refinement safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is interface-refinement still maintained?
The repository was last updated about 2 months ago, so interface-refinement is actively maintained.

name: interface-refinement description: > Refine an existing interface with named commands (critique, polish, distill, typeset, colorize ...), a product and design context file, and a static detector of generic UI patterns. Use when UI looks generic, cluttered or unfinished. license: MIT + Commons Clause metadata: version: 1.0.0 author: borghei category: engineering domain: design-engineering updated: 2026-11-08 tags: [ui-refinement, design-critique, design-review, generic-ui, typography, color, motion, accessibility]

Interface Refinement

A shared vocabulary for improving interfaces that already exist. Each command names one kind of change (distill removes, typeset fixes type, colorize gives colour a job, harden survives real content), says what it may change and what it must leave alone, and ends with a check that produces evidence. A context file records the product and its visual system so commands decide from facts. A static detector finds the patterns that make an interface look assembled from defaults: side stripes on rounded cards, gradient text, violet-to-cyan gradients, cream page grounds, eyebrow labels over headings, cards inside cards, chip soup, rows of identical cards, emoji icons, radial hazes, clip-path blobs, faint grey text, removed focus rings, broken images, template headlines and vague button labels. Given the context file, it also reports every literal colour, face, size and radius that has drifted outside the recorded system.

The agent reads the context file and the craft floor before any edit, keeps every change inside the named target, and never calls a refinement done without the evidence its command reference asks for: a rerun scan, a contrast ratio, a keyboard pass, screenshots at real widths.

Two rules hold across every command:

  • Refinement preserves. Identity, behaviour, copy and everything outside the named target stay as they are. If the concept itself is wrong, say so and recommend a redesign; do not smuggle one into a polish pass.
  • Scope is the contract. Every edit step lists what changes, what must not be touched, and how the result is verified. command_router.py --plan refuses plans that skip any of the three.

When to use this skill

  • "This looks generic / AI-made / like every other SaaS page" on an existing page or app
  • Critique or audit a surface before release, with scores and a prioritised fix list
  • A focused pass: typography, colour and contrast, spacing and hierarchy, motion, UX copy, edge cases and focus, responsive adaptation, first-run and empty states
  • "Tone it down" / "make it bolder" on a named section without restyling the rest
  • Gate a pull request that touches markup or styles on generic-pattern and quality findings
  • Write or check the project context file (product brief + design brief) that steers later work
  • Native screens: platform conformance review for iOS and Android

Use engineering/design-auditor for letter grades and landing-page template detection, engineering/a11y-audit for a WCAG scan of alt text, labels and landmarks. To choose a visual direction or build a new site from nothing, use a design-direction or frontend-build skill; this one refines what exists.

Clarify First

The target and its mode change every recommendation. Settle these before editing. When one is missing or vague and would change the result, ask; when it would not, use a sensible default and say which one you used.

  • Target: the file, component or route, and what is out of scope. Refinement edits only the named target.
  • Surface mode: persuade, operate, read or showcase (see references/surface-modes.md). "Quieter" on a dashboard and on a landing page are different jobs.
  • Context file: does interface-context.md exist and pass the linter? If not, offer init for anything bigger than a one-line fix; do not block a narrow fix on it.
  • Binding brand decisions: faces, colours or devices the owner chose on purpose. They override detector findings (waive with a reason).
  • Platform: web, iOS, Android or cross-platform; the web detector does not read native code.

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

Quick Start

# 1. Scan for generic and quality patterns (exit 1 on findings at or above medium)
python3 engineering/interface-refinement/scripts/ui_slop_detector.py \
  engineering/interface-refinement/assets/sample_ui_flawed.* --format text

# 2. Route the findings to the next commands (exit 1 when access-blocking work exists)
python3 engineering/interface-refinement/scripts/ui_slop_detector.py src/ --format json > detector.json
python3 engineering/interface-refinement/scripts/command_router.py --report detector.json --mode operate

# 3. Validate the refinement plan before editing
python3 engineering/interface-refinement/scripts/command_router.py \
  --plan engineering/interface-refinement/assets/sample_refinement_plan.json

# 4. Check shipped values against the recorded visual system (off-system-* rules, refusals fail)
python3 engineering/interface-refinement/scripts/ui_slop_detector.py src/ \
  --context engineering/interface-refinement/assets/sample_context.md --format text

# 5. Lint the project context file
python3 engineering/interface-refinement/scripts/context_linter.py \
  --input engineering/interface-refinement/assets/sample_context.md

Tools Overview

| Tool | Input | Output | Exit codes | |------|-------|--------|------------| | ui_slop_detector.py | files or directories (HTML, JSX, TSX, Vue, Svelte, Astro, CSS, SCSS, LESS); optional --context | findings with file:line, rule, severity, evidence, fix, owning command; summary by command | 0 clean at --fail-on, 1 findings, 2 bad input | | command_router.py --report | detector JSON + mode + platform | 2-3 next commands in triage order, then polish; a plan skeleton | 0 routed, 1 access-blocking work found, 2 bad input | | command_router.py --plan | refinement plan JSON | errors and warnings per step | 0 valid, 1 errors (warnings with --strict), 2 malformed | | context_linter.py | interface-context.md | errors and warnings by section | 0 pass, 1 errors (warnings with --strict), 2 not a context file | | ui_rules.py | --list [--scope S] or --contrast FG BG | rule catalog, or a WCAG ratio (translucent colours composited over white; pass the opaque ground for dark UIs) | 0 ok / ratio passes, 1 ratio fails, 2 bad colour, scope or catalog | | system_checks.py | --context file + files | off-system values only (drift report for document and extract) | 0 / 1 / 2 | | css_checks.py, markup_checks.py, class_checks.py, extra_checks.py | stylesheets, markup, or one class list | the detector's layers run alone, for debugging a rule | 0 / 1 / 2 | | css_parse.py | one file | the CSS blocks and declarations the detector reads, for debugging a parse | 0 parsed, 2 bad input |

All tools are stdlib-only, offline, deterministic, and support --format text|json. Waive a finding inline with ui-refine-ignore <rule> -- <reason>; waivers without a reason are rejected.

Commands

| Group | Command | Job | Detector rules routed here | Reference | |-------|---------|-----|----------------------------|-----------| | Evaluate | critique | design review, heuristic scores, 3-5 priority issues | none (judgment) | references/command-critique.md | | Evaluate | audit | five-dimension technical score out of 20 | all, as evidence | references/command-audit.md | | Context | init | write the product half of the context file | none | references/command-init.md | | Context | document | record the shipped visual system | none | references/command-document.md | | Context | extract | turn drift into tokens and shared components | off-system-color, off-system-font, off-system-radius, off-system-font-size | references/command-extract.md | | Refine | polish | closing pass: states, alignment, browser surfaces | emoji-icon, skipped-heading, buried-raster | references/command-polish.md | | Refine | distill | remove what does not earn its place | nested-cards, chip-soup, numbered-section-labels, shape-assembled-illustration | references/command-distill.md | | Refine | quieter | lower the volume, keep the point of view | side-stripe-border, glow-shadow, radial-glow, organic-clip-path, hairline-wide-shadow, hard-offset-shadow, repeating-stripes, grid-line-background | references/command-quieter.md | | Refine | bolder | raise one flat section with the system's own moves; "all-out" requests too | none (critique only) | references/command-bolder.md | | Refine | harden | focus, overflow, i18n, errors, edge content | focus-ring-removed, broken-image | references/command-harden.md | | Refine | clarify | labels, headlines, errors, empty states | vague-control-label, vague-headline | references/command-clarify.md | | Enhance | typeset | roles, scale, reading comfort, a type decision | gradient-text, kicker-above-heading, italic-serif-display, overused-face, default-font-stack, tiny-text, all-caps-body, oversized-headline, flat-type-hierarchy, tight-body-leading, wide-body-tracking, crushed-tracking, justified-text, everything-bold | references/command-typeset.md | | Enhance | colorize | colour roles, contrast, reflex palettes | low-contrast-pair, faint-gray-text, gray-on-color, ai-hue-gradient, cream-ground | references/command-colorize.md | | Enhance | layout | lead element, grouping, rhythm, order | identical-card-row, icon-tile-stack, monotonous-spacing | references/command-layout.md | | Enhance | animate | motion that explains, reduced-motion paths | missing-reduced-motion, transition-all, layout-property-motion, bounce-easing, decorative-pulse, marquee-scroll, blinking-cursor | references/command-animate.md | | Enhance | optimize | no layout jumps, readable before fonts load, smooth motion | image-missing-dimensions, font-display-missing (and the motion rules it shares with animate) | references/command-optimize.md | | Enhance | adapt | restructure for phone, tablet, print, email, other platforms | none (audit, critique) | references/command-adapt.md | | Enhance | onboard | first run, empty states, time to first value | none (critique) | references/command-onboard.md | | Enhance | delight | one considered, product-specific moment | none (owner request) | references/command-delight.md |

Routing

  • No command named: run the detector, then command_router.py --report and offer its two or three picks with one-line reasons. Never auto-run; the user confirms the pick.
  • A command named or clearly implied ("fix the type", "it's too loud"): load that command's reference and follow it. If two fit, ask once.
  • A clean scan: recommend critique. The detector proves the floor, not the design.
  • Missing context file: a narrow fix proceeds on the existing code; offer init afterwards. Anything wider (a redesign, a new surface, more than a few files) starts with init.
  • Native platform: critique and audit against references/native-platforms.md; skip the web detector.

Workflows

Workflow 1 — Refine a surface

  1. Settle target, mode and scope (Clarify First). Read interface-context.md if it exists.
  2. Scan the target and the global styles together, so project-level rules (focus-visible, reduced motion) see everything:
    python3 engineering/interface-refinement/scripts/ui_slop_detector.py src/pages/invoices.tsx src/styles --format json > detector.json
    
  3. Route: command_router.py --report detector.json --mode operate. Access-blocking work (contrast, tiny text, focus, reduced motion) comes first.
  4. Write the plan JSON: one step per command with changes, must_not_touch,

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars817
CategoryDevelopment
Updated1mo ago
Forks141

Languages

HTML

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium
interface-refinement — Universal Skill: Install & Safety Check | SkillAgent