UX Skills

Your AI design partner should know UX.

UX Skills is an open-source set of Agent Skills for working designers. It does not try to replace the designer or turn the agent into an autonomous design machine. It helps the designer think better, catch what they missed, work with the real design system, and carry UX intent into engineering.

Install it

From your project folder:

npx skills add Tranz007/ux-skills --all

Then run once:

setup-ux

flowchart LR
    A[Install UX Skills] --> B[Run setup-ux once]
    B --> C[Talk normally]
    C --> D[Relevant UX capability activates]

setup-ux determines whether the work is a new or existing product, captures product intent, learns the people and evidence that actually exist, finds the design system and engineering environment, and preserves the small amount of context future UX work needs.

That's the setup. After that, work normally.

Challenge this idea.

Who are we actually designing this for?

What am I missing?

Does this need a new component?

Review this before I show engineering.

If I change this, what else moves?

Get this ready for engineering.

Write the PR description.

You do not need to know which skill handles the request. The agent chooses the relevant UX Skills automatically.

The architecture in one picture

flowchart TB
    U[Designer request] --> I[Intent<br/>Why, outcome, people, scope, success]
    I --> C[Context<br/>What is true about the product and environment]
    C --> S[UX Skills<br/>Relevant practitioner capability]
    S --> W[Designer + agent do the work]

Intent tells the agent what good means. Context tells it what is true. Skills tell it how to reason about the UX problem.

That separation matters because an implementation can show what a product does without proving why it exists, and an AI can easily turn a plausible assumption into a fake product fact if the evidence is not kept explicit.

New and existing products

setup-ux has two paths under the same simple command.

flowchart TB
    A[setup-ux] --> B{New or existing?}
    B -->|New| C[Start with the idea]
    C --> D[Ask the next material question]
    D --> E[Capture intent]
    B -->|Existing| F[Inspect repo, docs, evidence, design system]
    F --> G[Reconstruct draft intent]
    G --> H[Resolve only material gaps]
    E --> I[INTENT.md]
    H --> I
    I --> J[Small project context]
    J --> K[Ready to work normally]

For a new project, setup is an adaptive conversation, not a UX questionnaire. For an existing project, it explores first and asks only what cannot be established reliably.

Four small context files

setup-ux creates or refreshes only the durable context future work needs:

.ux/
├── INTENT.md
├── CONTEXT.md
├── DESIGN-SYSTEM.md
└── DECISIONS.md

INTENT.md is the north star: why the product or capability exists, intended outcome, people affected, core experience, scope, non-goals, constraints, success, and material uncertainty.

CONTEXT.md describes the operating environment: product mechanics, evidence locations, engineering workflow, accessibility expectations, terminology, and stable project facts.

DESIGN-SYSTEM.md points to the real design system and its source-of-truth/reuse rules.

DECISIONS.md preserves consequential decisions or points to the team's existing ADR/RFC system.

The files stay small. A project can split out something like .ux/evidence/research.md or .ux/users/tasks.md later when density or repeated use actually justifies it. UX Skills does not generate empty research, persona, journey, or constraints folders just because a template could exist.

Context is loaded progressively too: read intent when purpose, outcome, scope, or success can change the answer, then load only the additional context relevant to the current task.

See it in action

A designer says:

We need an AI trip recommendation feature. Help me design it.

A useful UX Skills response starts by testing the premise instead of immediately drawing the feature:

Before designing it, two assumptions matter. I don't see evidence yet that travelers need recommendations rather than better comparison. And recommendations will only be useful if the system knows enough about the traveler to make a defensible suggestion. Define what data it uses, how confidence is shown, and what happens when it's wrong before choosing the interaction. If the design system already has recommendation or card patterns, reuse those first.

The agent may quietly use user grounding, framing, challenge, design-system fit, evidence discipline, and Clear behavior to produce that answer. The designer does not orchestrate those capabilities.

What happens in the background

UX Skills helps the agent ground work in the people affected and evidence that actually exists, challenge weak assumptions, catch missing states and accessibility concerns, reuse the existing design system before inventing new components, see downstream effects of a UX change, improve UI language, preserve consequential decisions, and carry behavior and rationale into engineering.

These are separate skills internally because narrow capabilities route and maintain more reliably than one giant "UX expert" prompt. They are not a menu the designer has to learn.

Every installed skill carries the same six background rules: Context, User, Evidence, System, Clear, and Trust. User-centered does not mean process-heavy: the skills do not introduce research, personas, or discovery work when the user and task are already clear or the missing information would not change the work.

The skills under the hood

Only setup-ux is something a designer needs to deliberately run. The rest are designed to be selected from normal language when useful.

A few rules every skill follows

Explore before asking. If the answer is already in the project, find it.

Ground in users, not UX theater. Understand the people, task, and context when they can change the design. Do not force personas, research, or discovery work onto simple tasks that do not need them.

Don't fake evidence. Known, inferred, assumed, unknown, and conflicted are not the same thing.

Use the system. Reuse and compose before adding another component.

Keep context lean. Load the smallest combination of intent, project context, and deeper references necessary for the task.

Keep it human. Lead with the useful point. Use only the structure the reader needs. No corporate AI sludge, canned praise, repetitive summaries, or documentation theater.

Don't make engineering guess. Preserve behavior, states, accessibility intent, and rationale when work crosses the design/engineering boundary.

Portable by design

UX Skills follows the open Agent Skills format. It is intended to work across agents that support the format rather than being tied to one model or one design tool.

Documentation

• Architecture — how intent, context, routing, and progressive disclosure fit together.
• Visual flows — the main UX Skills flows in one place.
• Context — what belongs in .ux/ and how it grows without becoming bureaucracy.
• Authoring — how to create or change skills without making the suite heavier.
• Roadmap — what the project is optimizing for next.
• Evaluation — how routing, evidence integrity, setup behavior, and usefulness are tested.

Principles

1. If the designer has to learn the system before it can help them, we failed.
2. The human owns the design.
3. Ask only when the answer changes the work.
4. Be user-centered without making UX process the price of simple work.
5. Prefer evidence over confidence.
6. Prefer the existing system over unnecessary invention.
7. Keep the reasoning attached to the design all the way into engineering.
8. Make the system smarter without making the designer feel more machinery.

Contributing

Read CONTRIBUTING.md. The goal is not the largest skill library. Add something only when it solves a real, repeatable practitioner problem without making the UX of UX Skills harder.

License

MIT © Tony Moura