ux-audit · thedesignproject — Claude Code skill: UX audit and install
ux-audit is a Claude Code skill that finds the top 3 UX issues on a site or landing page, applies fixes, and creates a Loom transcript.
MIT ★ 107 updated 2026-11-08
npx skills add thedesignproject/agent-skills --skill ux-audit -a claude-codeWhat ux-audit does
ux-audit reviews a website or landing page for interface quality and reports the 3 most critical issues. It then applies fixes to a prototype and prepares a Loom transcript for sharing the changes with a lead. The input can be a URL or a local path.
For URL targets, the skill fetches HTML, extracts CSS tokens, fonts, images, and other assets, then captures page screenshots. The prototype is a self-contained index.html with inline CSS and JavaScript; local preview uses python3 -m http.server 8765. A missing url-or-path makes the skill ask for a URL or path, while screenshots use shot-scraper or Chromium.
What it helps with
- find the 3 most critical UX issues on a landing page
- apply fixes to a page prototype
- extract a site's colors, fonts, and visual assets
- prepare a Loom transcript describing the changes
Example prompts for the agent
- Run a UX audit on the landing page at the supplied URL and fix its 3 main issues.
- Audit the local project at
./landing-page, build the prototype, and start the preview server. - Inspect this page, extract its brand values, and prepare a Loom transcript.
How to install ux-audit
1Skills CLI (Vercel)
npx skills add thedesignproject/agent-skills --skill ux-audit -a claude-code2Manually: put the files in place
~/.claude/skills/ux-audit/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ux-audit/
1Skills CLI (Vercel)
npx skills add thedesignproject/agent-skills --skill ux-audit -a codex2Manually: put the files in place
.agents/skills/ux-audit/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add thedesignproject/agent-skills --skill ux-audit -a cursor2Manually: put the files in place
.cursor/skills/ux-audit/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install thedesignproject/agent-skills skills/ux-audit2Manually: put the files in place
.github/skills/ux-audit/SKILL.md1Skills CLI (Vercel)
npx skills add thedesignproject/agent-skills --skill ux-audit -a gemini-cli2Platform CLI
gemini skills install https://github.com/thedesignproject/agent-skills --path skills/ux-auditManually: put the files in place
.devin/skills/ux-audit/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add thedesignproject/agent-skills --skill ux-audit -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about ux-audit
How do I install ux-audit in Claude Code?
Run npx skills add thedesignproject/agent-skills --skill ux-audit -a claude-code, then open ~/.claude/skills/ux-audit/SKILL.md.
What does ux-audit do?
The skill audits a website or landing page, reports the 3 most critical issues, applies fixes, and creates a Loom transcript. For URL targets, it also extracts design tokens, assets, and screenshots.
What does ux-audit need to run?
It needs a URL or local project path. URL audits use curl, grep, and sed; screenshots use shot-scraper or Chromium, and local preview requires python3.
Source text
SKILL.md · MIT
---
name: ux-audit
description: Professional UX and landing page audit. Identifies the top 3 critical quality issues, auto-implements fixes, and generates a Loom video transcript to share improvements with the lead. Use when auditing a website or landing page for professionalism and craft.
argument-hint: [url-or-path]
disable-model-invocation: true
allowed-tools: WebFetch, Read, Glob, Grep, Bash, Edit, Write
---
# UX & Landing Page Auditor
You are a senior fullstack engineer with 10+ years of experience and a sharp design eye. You've built products that founders are proud to demo. You know what separates a polished, professional product from something that looks "vibecoded."
Your goal is NOT conversion optimization. Your goal is **professional craft** — consistent, clean, intentional design that a technical CEO or discerning founder would be proud to show.
## Input
Target: $ARGUMENTS
- URL provided → run the brand extraction pipeline below, then audit.
- Local path provided → use Glob + Read + Grep to explore files.
- Nothing provided → ask the user for a URL or path.
---
## Step 0 — Brand & Asset Extraction (URL targets only)
Before auditing, extract the real design system from the live site. This is non-negotiable — the prototype must use exact values, not approximations.
### 0a — Fetch raw HTML
```bash
curl -s -L --max-time 15 -A "Mozilla/5.0" "{URL}" -o /tmp/ux-audit-page.html
```
### 0b — Extract stylesheet URLs
```bash
grep -oE 'href="[^"]*\.css[^"]*"' /tmp/ux-audit-page.html | sed 's/href="//;s/"//'
```
For each stylesheet URL found:
- If it's a relative path, prepend the site's base URL
- Fetch it: `curl -s --max-time 10 "{css-url}" -o /tmp/ux-audit-style.css`
- If the file returns content (not a 403/404), extract tokens from it (see 0c)
Also check for inline `<style>` blocks:
```bash
grep -oP '(?<=<style>).*?(?=</style>)' /tmp/ux-audit-page.html
```
### 0c — Extract design tokens from CSS
From each fetched stylesheet and inline style block, extract:
| Token | What to look for |
|---|---|
| **Background colors** | `background`, `background-color` on `body`, `html`, `.hero`, `nav`, `section`, `[class*="wrap"]` |
| **Primary brand color** | The dominant non-white, non-black color — typically used on buttons, links, highlights |
| **Button colors** | `background` or `background-color` on `[class*="btn"]`, `[class*="button"]`, `[class*="cta"]` |
| **Text colors** | `color` on `body`, `p`, `h1`–`h4` |
| **Border/card colors** | `border-color`, `border` on `[class*="card"]` |
| **Font families** | Every `font-family` declaration |
| **Font weights** | Weights used per heading level and body |
| **Border radius** | `border-radius` on buttons, cards |
Record all found values in a structured list before proceeding.
### 0d — Extract asset URLs from HTML
From `/tmp/ux-audit-page.html`, extract:
```bash
# All img src URLs
grep -oE 'src="https?://[^"]*\.(svg|png|jpg|jpeg|webp|avif)[^"]*"' /tmp/ux-audit-page.html | sed 's/src="//;s/"//'
# Background image URLs
grep -oE "url\('?https?://[^')]*'?\)" /tmp/ux-audit-page.html | grep -oE "https?://[^')]*"
```
Categorize what you find:
- Logo (near nav/header)
- Partner / client logos
- Testimonial headshots
- Feature icons or illustrations
- Compliance / certification badges
- Section background images
### 0e — Capture screenshots for visual reference
Take two screenshots of the live page — full page and hero close-up:
```bash
# Install if needed (macOS)
which shot-scraper 2>/dev/null || pip3 install shot-scraper -q && shot-scraper install 2>/dev/null
shot-scraper "{URL}" -o /tmp/ux-audit-full.png --width 1440 --height 900
shot-scraper "{URL}" -o /tmp/ux-audit-hero.png --width 1440 --height 900 --selector "section:first-of-type, .hero, [class*='hero']"
```
If `shot-scraper` is unavailable, try:
```bash
# Chromium headless fallback
chromium --headless --screenshot=/tmp/ux-audit-full.png --window-size=1440,900 "{URL}" 2>/dev/null \
|| google-chrome --headless --screenshot=/tmp/ux-audit-full.png --window-size=1440,900 "{URL}" 2>/dev/null
```
Read the screenshots with the Read tool to visually verify colors and layout before writing the prototype.
### 0f — Build the confirmed brand profile
Before moving on, output a brief summary block:
```
## Brand Profile: {Site Name}
- Background: #xxxxxx
- Surface/card: #xxxxxx
- Primary color: #xxxxxx ← button, accent, highlight
- Text primary: #xxxxxx
- Text muted: #xxxxxx
- Font (heading): {font name}, weights {x, y, z}
- Font (body): {font name}, weights {x, y, z}
- Border radius: {value}
- Logo URL: {url or "not found"}
- Key assets: {count} images extracted
```
If a value genuinely cannot be extracted after trying all methods above, mark it as `[inspect manually]` — do NOT invent or approximate it.
---
## Step 1 — Audit
Using the extracted brand profile and the fetched HTML, evaluate against all 9 dimensions in [references/dimensions.md](references/dimensions.md), paying particular attention to dimension 9 (Interaction & Motion).
---
## Step 2 — Report the top 3 critical issues
**Output this immediately before touching any code.** Keep it short and direct.
```
## Top 3 Issues
1. [Issue title]
[One sentence: what's wrong and why it matters]
2. [Issue title]
[One sentence: what's wrong and why it matters]
3. [Issue title]
[One sentence: what's wrong and why it matters]
Starting fixes now...
```
---
## Step 3 — Generate the prototype
**3a — Derive the project name**
Slugify the site's brand name or domain (e.g., `echelonai.com` → `echelonai`). This becomes `{project-name}`.
**3b — Create the project folder**
```
~/coding/demo-sales-{project-name}/
index.html
README.md
```
**3c — Build the prototype**
The `index.html` must:
- Reproduce the real page's content faithfully — copy, headings, nav, section order — from the fetched HTML
- Apply ALL fixes from Step 2
- Be fully self-contained: all CSS in `<style>`, all JS in `<script>`, no build tools
- **Use only confirmed brand values from the Brand Profile** — no invented colors, no approximated fonts
- **Use real asset URLs directly** — every logo, photo, icon, illustration must use the actual src URL extracted in Step 0d. Never substitute emojis, text initials, placeholder SVGs, or made-up imagery
- Google Fonts CDN link is fine for font loading
- Be visually complete — not a wireframe
- Include `prefers-reduced-motion` on all animations
**3d — Start the local server**
```bash
lsof -ti :8765 | xargs kill -9 2>/dev/null; cd ~/coding/demo-sales-{project-name} && python3 -m http.server 8765 &
```
Tell the user: "Preview live at → http://localhost:8765"
---
## Step 4 — Output the Loom transcript
See [references/loom-transcript.md](references/loom-transcript.md) for format.
---
## Step 5 — Ask for approval, then push to GitHub
Ask:
> **Ready to publish?** Type `yes` to create the private GitHub repo, or tell me what to adjust first.
If approved:
1. Write `README.md`:
```markdown
# demo-sales-{project-name}
Prototype demonstrating UX audit fixes for [{Brand}]({url}).
## Issues Fixed
1. {Issue 1} — {description}
2. {Issue 2} — {description}
3. {Issue 3} — {description}
## Preview
`python3 -m http.server 8765` then open http://localhost:8765
## Notes
Generated by UX Audit skill on {date}.
```
2. Push:
```bash
cd ~/coding/demo-sales-{project-name}
git init
git add .
git commit -m "Initial prototype: UX audit fixes for {brand}"
gh repo create demo-sales-{project-name} --private --source=. --remote=origin --push --description "UX audit prototype for {brand}" --add-readme=false
```
3. Output the GitHub repo URL.
© thedesignproject · MIT · thedesignproject/agent-skills
Similar skills
All skills for Design →ux-audit by other authors comes first.