ux-researcher-skill
A Claude Code skill that turns a loose product description (in any language) into a structured English UX Spec ready to hand off to a visual-design agent like huashu-design.
The technical skill identifier (in SKILL.md frontmatter) is ux-planner. The repo is named ux-researcher-skill because the skill's job is closer to UX research / product framing than visual planning.
What it does
You describe what you want to build:
"Хочу приложение для трекинга привычек"
"I need a SaaS dashboard for screening resumes"
The skill runs an 8-phase workflow:
- Phase 0 — detects product archetype (1 of 7), creates a TaskCreate plan to track progress
- Phase 1 — asks a single batch of 5 framing questions (audience, JTBD, platform, design context). Skipped automatically if the project already has
context-map.md / CLAUDE.md / project memory describing the product
- Phase 2 — drafts features, flows, and screens from archetype defaults so you edit instead of answering 30 atomic questions
- Phase 2.5 — single yes/no question: do you want a mobile/responsive UX track? If yes, a dedicated §10 Mobile Block is added to the spec with per-screen mobile adaptation, touch interactions, and mobile-only states
- Phase 3 — adaptive follow-ups about gaps (auth, monetization, empty states, notifications, etc.). Hard-capped at 5 questions per round, max 2 rounds, ≤8 total
- Phase 4–5 — synthesizes per-screen briefs (information hierarchy, key elements, states, position-4 answers for huashu)
- Phase 6 — generates the spec, runs a mandatory self-review checklist (sequential IDs, brief-count match, density type set, etc.)
- Phase 7 — outputs a hand-off code block ready to paste into huashu, and saves an auto-memory pointer so the next session keeps context
When the description is too vague, the skill switches into advisor mode and proposes 2–3 differentiated archetypes with tradeoffs.
Why it exists
Without this skill, every time you go to a visual-design agent like huashu you re-answer its 10 standard questions (design context, variations, fidelity, scope, tweaks, position-4 per screen, density type, brand assets). The spec produced by ux-planner pre-answers all of them in §8 "Hand-off to huashu-design" — so huashu skips its interview and goes straight to design.
It also forces you to think about edge states (empty / loading / error / success) per screen — the most common gap in AI-assisted product design.
Output
A markdown file at <project>/ux-spec-<YYYY-MM-DD>-<slug>.md with 9–10 sections:
- Product Framing
- Functional Scope
- User Flows
- Screen Inventory
- Per-Screen Briefs
- Constraints & Context (with per-breakpoint feature parity table)
- Design Context (for huashu)
- Hand-off to huashu-design (the critical section)
- Open Questions & Assumptions (with §9.4 Product Risks)
- Mobile / Responsive Design Block (conditional, only if confirmed in Phase 2.5)
Plus a hand-off message — a fenced code block — you paste into a fresh huashu-design session.
Scope
✅ Mobile apps (utility, content)
✅ Web apps (productivity, dashboards)
✅ Internal tools / admin panels
✅ Landing / marketing sites
✅ Browser extensions
✅ Redesigning existing products (reads context-map.md / CLAUDE.md / memory and skips Phase 1)
❌ Slide decks, animations, infographics — those go directly to huashu-design
❌ PRDs, business cases, market sizing — out of scope
❌ Visual design execution — that's huashu's job
Installation
Global (recommended)
Clone into ~/.claude/skills/:
git clone https://github.com/kyzdes/ux-researcher-skill.git ~/.claude/skills/ux-planner
The folder name on disk should be ux-planner (matching the skill identifier in SKILL.md frontmatter), even though the repo is named ux-researcher-skill.
Per-project
Drop the folder into a project's local skills directory if your harness supports it.
Trigger phrases
The skill triggers on (Russian): хочу приложение, нужен dashboard, сделай UX, помоги придумать, продумай интерфейс, сделай app, разработать продукт.
The skill triggers on (English): design a, build me, I want an app for, need a dashboard, make a SaaS, feature spec for, UX spec, user flows for.
Test it
In a fresh Claude Code session (with the skill installed):
Хочу сделать сервис записи к врачу онлайн
Expected behavior: detect mobile/web borderline archetype → issue 5-question batch → draft features/flows/screens → ask the mobile-track question → adaptive follow-ups → save English spec → output hand-off code block.
