LoveUI Skills

LoveUI Skills is a skill pack for AI coding agents.

It tells the agent how to build, review, and improve LoveUI interfaces. The pack does not add React components to your app. Instead, it gives the agent design rules, workflow steps, quality checks, and specialist skills it can follow while editing your code.

Use it when you want an agent to build a page, polish a screen, audit a design, improve copy, fix responsive behavior, or make a LoveUI project feel more complete.

What the skill pack does

The pack starts with a main SKILL.md file.

That file gives the agent a repeatable workflow:

Understand the product, audience, framework, and existing design system.
Read only the reference files needed for the task.
Use the LoveUI registry as the source of truth for components and examples.
Choose one clear visual direction.
Pick a layout blueprint.
Build the UI with reusable structure.
Check the result before calling it done.

The goal is to make the agent slower in the right places without flooding its context. It should inspect the project, make deliberate design choices, and verify the result instead of dropping in generic UI.

What is included

The pack has three main parts:

Root skill: the main instructions in SKILL.md.
Reference files: five condensed guides for design, interaction, structure, content/accessibility, and implementation quality.
Specialist skills: eight focused workflows for building, auditing, polishing, adapting, hardening, clarifying, extracting, and learning project conventions.

The root skill routes the agent to the right supporting material based on the request.

Reference files

Reference files are included with the installed skill pack.

They explain the standards the agent should apply while working:

design-system.md covers visual direction, typography, color, spacing, layout rhythm, imagery, and common AI design anti-patterns.
interaction-states.md covers controls, forms, loading, empty/error/success states, feedback, motion, and agent Plan -> Preview -> Apply flows.
structure-architecture.md covers semantic layout, responsive behavior, navigation, component APIs, state boundaries, and reuse.
content-accessibility.md covers UX writing, labels, errors, empty states, keyboard support, contrast, ARIA, touch targets, and resilient text.
implementation-quality.md covers LoveUI MCP lookup, page blueprints, screenshot translation, testing strategy, and final quality gates.

The agent does not need every file for every task. For example, a copy task can use content-accessibility.md and interaction-states.md, while a broad redesign should also use design-system.md, structure-architecture.md, and implementation-quality.md.

Specialist skills

Specialist skills are included with the installed skill pack.

Each one handles a narrower kind of work:

build creates or redesigns production-quality pages, dashboards, product surfaces, and app workflows.
audit reviews interface quality and returns prioritized findings with severity, impact, and recommended fixes.
polish fixes spacing, hierarchy, consistency, restraint, visual impact, and final details.
adapt improves responsive behavior, density, viewport support, and alternate usage contexts.
harden improves accessibility, errors, performance, i18n, long content, and production edge cases.
clarify improves labels, instructions, validation messages, empty states, onboarding copy, and UX writing.
extract turns repeated patterns into reusable components, variants, tokens, or design-system rules.
teach-loveui gathers project design context once and summarizes reusable guidance for future sessions.

When the pack is installed, the agent should choose one primary specialist and add a second only when the task clearly crosses concerns. For example, "make this form easier to understand" should route to clarify, while "make this dashboard production ready" may use audit first and polish after fixes.

How it changes agent behavior

Without the skill pack, an agent may jump straight into code.

With LoveUI Skills, the agent is expected to:

Read the existing code before editing.
Preserve the product's current design system.
Choose one visual direction instead of mixing styles.
Use LoveUI components and registry items intentionally.
Design desktop and mobile together.
Include important UI states, not just the happy path.
Keep interactions accessible with keyboard and focus support.
Use simple, specific product copy.
Run quality checks before finishing.

This makes the agent act more like a careful product engineer and less like a code generator.

Agent workflow

A good LoveUI Skills run usually follows this path:

Scope the work. The agent identifies the screen, users, core actions, and constraints.
Read references. The agent opens the files that match the task.
Inspect LoveUI options. If the LoveUI MCP server is available, the agent checks the live registry before choosing components.
Pick a direction. The agent chooses one visual direction that fits the product, audience, and workflow.
Pick a blueprint. The agent starts from a page pattern, such as docs, dashboard, settings, workspace, or agent workflow.
Implement carefully. The agent builds reusable structure, keeps semantics correct, and handles key states.
Verify. The agent runs checks, reviews the UI, and fixes issues before reporting back.

Agent UI requirements

The skill pack has extra rules for agent-powered interfaces.

If the UI lets an agent suggest changes, generate work, or apply edits, it should include:

Plan: a short explanation of what will change, why, and what will not change.
Preview: diffs, screenshots, or a structured change summary before applying risky work.
Apply: visible progress, completion status, and a final summary.
Undo: a recovery option for reversible actions.
History: restore points for high-impact changes.
Why this?: a place to explain why a suggestion was made.
Provenance: clear source labels, such as "From LoveUI registry".

These rules help users trust the agent before it changes real code or data.

How to use it

LoveUI Skills ships with the love-ui npm package.

Add it from your project root with the LoveUI CLI:

npm

npx love-ui@latest add loveui-skills

The CLI asks which tool you want to target. Choose codex, claude, cursor, github, or all.

For scripts, CI, or any place where you do not want an interactive prompt, pass the target directly:

npm

npx love-ui@latest add loveui-skills codex

npm

npx love-ui@latest add loveui-skills claude

npm

npx love-ui@latest add loveui-skills cursor

npm

npx love-ui@latest add loveui-skills github

To install every supported target at once:

npm

npx love-ui@latest add loveui-skills all

You can also use the long option form:

npm

npx love-ui@latest add loveui-skills --agent codex

What the CLI writes

Different tools read instructions from different places.

The CLI installs the same LoveUI skill pack, but places it where each tool expects to find it:

Codex: copies the skill pack to ~/.codex/skills/loveui-skills.
Claude: copies the skill pack to ~/.claude/skills/loveui-skills.
Cursor: copies the skill pack to .cursor/loveui-skills and adds .cursor/rules/loveui-skills.mdc.
GitHub Copilot: copies the skill pack to .github/loveui-skills and adds .github/instructions/loveui-skills.instructions.md.
All: runs every target above.

For Codex and Claude, restart or reload the tool after installing so it can find the new skill.

For Cursor and GitHub Copilot, commit the generated project files if you want the instructions to travel with the repo.

The installed skill pack keeps this shape:

loveui-skills/
  SKILL.md
  references/
  skills/

After installation, ask your agent to use loveui-skills for LoveUI work.

Example prompts:

Use loveui-skills to redesign this settings page.

Use loveui-skills build to create the workspace view.

Use loveui-skills audit on the dashboard and list the issues by severity.

Use loveui-skills polish to fix spacing, alignment, and responsive behavior.

Use loveui-skills clarify to improve the form labels and validation messages.

Use loveui-skills harden on this billing flow before launch.

Use loveui-skills teach-loveui to learn this project's design rules.

When to use it

Use LoveUI Skills for:

New app screens.
Docs pages and marketing pages.
Dashboards and admin tools.
Settings, onboarding, forms, and empty states.
Design polish before shipping.
Accessibility and responsive reviews.
Agent workflows that need plan, preview, apply, undo, and history.

It is especially useful when the work is visual, interactive, or user-facing.

When not to use it

You usually do not need the skill pack for:

Pure backend changes.
Small dependency updates.
Simple typo fixes.
One-line code edits with no UI impact.
Tasks where the user has already provided exact implementation instructions.

For those tasks, the agent can work normally.

Best practices

For the best results:

Give the agent the user goal, not only the component name.
Mention the page or route that should change.
Say whether the work should be bold, quiet, dense, playful, or conservative.
Ask for an audit before a large redesign if you are unsure what is wrong.
Ask for polish after implementation so the agent checks the details.
Ask the agent to verify mobile and desktop behavior.

Clear prompts help the agent choose the right specialist skill and references.

LoveUI setup: Get Started
Component usage: Component Guide

LoveUI Skills

On this page