Agent skill

UX Walkthrough

by XiaoMi in XiaoMi/hiui

体验走查 skill。适用于代码库、URL、截图三种输入,输出结构化体验问题报告,并同步生成本地 docx 报告。触发词:体验走查、UX review、交互走查、界面审查、体验问题。

MITAuto-check passedFrontend & Design

Install UX Walkthrough

skills CLI
$ npx skills add XiaoMi/hiui --skill ux-walkthrough -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install XiaoMi/hiui ux-walkthrough --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/XiaoMi/hiui.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/hiui-workflow/ux-walkthrough .claude/skills/ux-walkthrough && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
ux-walkthrough
GitHub stars
877
Token cost
~1.3k tokens
SKILL.md length
351 words
Files
56 (incl. scripts, references)
Skills in repo
5
Repo updated
First seen
Licence
MIT

At a glance

体验走查 skill。适用于代码库、URL、截图三种输入,输出结构化体验问题报告,并同步生成本地 docx 报告。触发词:体验走查、UX review、交互走查、界面审查、体验问题。

  • Works in 2 steps: 若 A 返回 try_url_walkthrough 或启动 dev 后拿到本地… → 若 dev 启动失败或 A 返回…
  • Tasks that involve Word documents
  • SKILL.md covers 路径约定, 角色与标准, 交付边界 and 输入 → 模式, plus 6 more sections
  • Calls python3

What it does

UX Walkthrough is an agent skill from XiaoMi/hiui. 体验走查 skill。适用于代码库、URL、截图三种输入,输出结构化体验问题报告,并同步生成本地 docx 报告。触发词:体验走查、UX review、交互走查、界面审查、体验问题。

Its SKILL.md is about 1.3k tokens, which your agent loads only when the skill is triggered. The skill folder holds 60 other files, including scripts and reference files (for example `README.md`, `agents/openai.yaml` and `docs/onboarding/execution-sop.md`).

It sits in Frontend & Design, covering Word documents, UX design and Design systems. It works with Microsoft Word. The repository describes itself as: HIUI is a solution that is adequate for the fomulation and implementation of interaction and UI design standard for front, middle and backend. The licence is MIT.

When your agent uses it

  • Tasks that involve Word documents
  • Tasks that involve UX design
  • Tasks that involve Design systems

Example prompts

  • “/ux-walkthrough”

Requirements

  • Python 3

Workflow steps

2 steps, taken from the first numbered list in SKILL.md.

  1. 若 A 返回 try_url_walkthrough 或启动 dev 后拿到本地 URL → 切换 url 模式:浏览器截图 + 标注图,report.json 的 source=url
  2. 若 dev 启动失败或 A 返回 fallback_code_walkthrough → source=code,附录注明「未启动项目,结论基于代码推断」;只强报 code 可确定的体验问题

What it can do on your machine

Read from SKILL.md and the folder at commit f056c80. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/, which the agent can run.

    Shell commands in SKILL.md call:

    • python3

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

UX Walkthrough loads about 1.3k tokens when it runs, and up to ~33k if it reads all its reference files. Until then it costs about 27 tokens; SKILL.md has 351 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~27
When it runs · the whole SKILL.md, loaded when a task matches
~1.3k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~33k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from XiaoMi/hiui at commit f056c80, republished under its MIT licence (© XiaoMi). 351 words, ~1,308 tokens.

Download SKILL.mdSave it as .claude/skills/ux-walkthrough/SKILL.md (or your agent's skills folder). This skill also uses 55 other files; get the full folder from GitHub.
name
ux-walkthrough
description
体验走查 skill。适用于代码库、URL、截图三种输入,输出结构化体验问题报告,并同步生成本地 docx 报告。触发词:体验走查、UX review、交互走查、界面审查、体验问题。
version
1.0.2

UX Walkthrough

对产品进行系统性体验走查,输出结构化报告与生成本地 .docx。

路径约定

<SKILL_ROOT> = 本 skill 目录的绝对路径。

bash
python3 <SKILL_ROOT>/scripts/<脚本>.py ...

角色与标准

  • 角色:资深 B 端体验设计专家;给可执行建议,不是主观吐槽
  • 主标准:references/ux-checklist.md(UX 体验规则)
  • HiUI 典型页:references/hiui-template-baseline.md(Delta 走查;模板库全部典型页型,见该文页型索引)
  • 辅助:Nielsen、WCAG、品牌规范;冲突时以效率、理解成本、错误恢复、专业感为准
  • 优先级:以 references/severity-rubric.md 为准,不用 checklist 预设 P 级代替

交付边界

  • 本 skill 的正式完成面只包括:完整 Markdown 报告、结构化 report.json、标注校验和本地 .docx
  • 本 public skill 不定义 usage stats、telemetry closeout、网络补传或授权重试 after-hook
  • 若上游 workflow 需要统计或发布态补传,必须由页面生成 / 发布 skill 自己定义和承担,不得默认追加到本 skill
  • 生成 .docx 依赖 Python 包 python-docx;若环境缺失,该任务只能报告 docx_generation 失败,不能宣称完整完成

输入 → 模式

输入模式文档
本地项目目录codereferences/mode.md#code
http(s) URLurlreferences/mode.md#url
图片screenshotreferences/mode.md#screenshot

无法判断时,只问一句最小必要澄清。


三阶段主流程

A 前置检查 → B 走查与报告 → C 生 docx 与完成自检
阶段 A:前置检查
bash
python3 <SKILL_ROOT>/scripts/precheck_walkthrough.py <输入> --json
  • 只读 next_action、mode、status、gate;code 模式额外读 runtime_probe
  • continue_walkthrough → 进入 B;否则补证据 / 澄清 / 失败说明,不写完整报告
  • code 输入且 gate 通过后,next_action 可能被 runtime 探测改写:
    • try_url_walkthrough → 对 runtime_probe.reachable_urls[0] 再跑 URL precheck,阶段 B 按 url 走
    • start_dev_server_then_url_walkthrough → 先启动 runtime_probe.suggested_dev_command;成功则 URL precheck,失败则收窄 code
    • fallback_code_walkthrough → 阶段 B 按 code 走,但须遵守体验边界(见 mode-code.md § 体验边界)
阶段 B:走查与报告

code 运行时优先(混合走查):

  1. 若 A 返回 try_url_walkthrough 或启动 dev 后拿到本地 URL → 切换 url 模式:浏览器截图 + 标注图,report.json 的 source=url
  2. 若 dev 启动失败或 A 返回 fallback_code_walkthrough → source=code,附录注明「未启动项目,结论基于代码推断」;只强报 code 可确定的体验问题

顺序(不可变):

  1. HiUI 前置(若适用):识别页型 → 读 references/hiui-template-baseline.md 对应节(页型索引列全量页型)
  2. 分批逐项走查:按 references/walkthrough-worksheet.md 的 Batch 1→4 顺序,逐条对照 references/ux-checklist.md 判断;每批填完工作表再进下一批
  3. 命中条目且需参考时,读该条 related_examples 指向的锚点(禁止通读 issue-examples/*.md 全文);HiUI 页先问是否与 baseline 合规默认一致
  4. references/ignore-list.md(含 §5 HiUI)→ 去掉误报
  5. references/severity-rubric.md → 定 P0/P1/P2

输出: 对话中完整 Markdown 报告(references/report-template.md)

整理 report.json 前,必须为 全部 17 条 填写 checklist_coverage(见 report-json.md):

  • pass 必须写 pass: <验证证据,>=8 字>,禁止裸 pass

  • issue / pending:... / n/a:... 规则见 report-json.md

  • 禁止在交付报告中输出「HiUI 模板对齐」模块(HiUI Delta 仅走查阶段内部使用;issue 描述可保留 [HiUI-偏离] / [业务域] 标签)

  • 标题格式:序号. [P级]标题

  • URL/截图模式:确定 issue 须有标注图与 images[].bbox

  • 证据不足 → 标「待确认 / 待交互验证」,不写确定问题;仍不足则回到阶段 A,不硬写完整报告

Show full SKILL.md (130 more words)Show less
阶段 C:生 docx 与完成自检
  1. 标注(screenshot / url 必做):禁止手估 --box;须用 annotate_issue.py(或 locate_in_screenshot.py + preview_bbox.py + annotate.py),输出到 output/annotations/*-annotated.png(流程见 annotation-style.md § 标注流程)
  2. 按 references/report-json.md 整理 report.json;URL/截图模式的 issues[].images[] 须指向标注版、设 "annotated": true,并记录 "bbox": [x,y,w,h]
  3. 校验 checklist 覆盖门禁:
bash
python3 <SKILL_ROOT>/scripts/validate_checklist_coverage.py --report-json <report.json> --json
  1. 校验标注门禁:
bash
python3 <SKILL_ROOT>/scripts/validate_report_annotations.py --report-json <report.json> --json
  1. 执行:
bash
python3 <SKILL_ROOT>/scripts/generate_docx.py \
  --report-json <report.json> \
  --output <SKILL_ROOT>/output/<项目名>-ux-report-<YYYYMMDD>.docx \
  --json
  • 命名、嵌图与交付边界:references/report-json.md § DOCX
  • screenshot / url:generate_docx.py 默认校验 checklist 覆盖与标注;未通过则不得 success 完成判断
  • 标注图:references/annotation-style.md(先 § 标注流程,再 § 样式);推荐工具:annotate_issue.py
  • 失败 → 说明卡住位置和直接原因,不能说已完整完成

完成定义(缺一不可)

  1. A:precheck 已通过,或已明确说明无法继续的原因
  2. B:对话中已输出完整报告(非摘要)
  3. C:success 路径 docx 已 generated;失败路径已说明失败阶段和原因

已分析 / 已出报告 / 已生 json 均不等于完成,docx 未生成不算完整完成。


分阶段读文档

阶段必读按需
Amode.md 对应锚点gates.md § 阶段 A
Bwalkthrough-worksheet, hiui-template-baseline(HiUI 时), checklist, ignore-list, severity-rubric—
Creport-template, report-json, annotation-styleannotate_issue.py, validate_checklist_coverage.py, validate_report_annotations.py

默认不读: 底层脚本源码及与单次走查无关的维护说明


底层脚本(仅单层调试)

bash
python3 <SKILL_ROOT>/scripts/detect_input_mode.py <输入> --json
python3 <SKILL_ROOT>/scripts/probe_dev_server.py <项目路径> --json
python3 <SKILL_ROOT>/scripts/check_evidence_gate.py --source <mode> ... --json

交付前自检

  • 报告完整,非摘要
  • 每问题有:位置、描述、改进建议
  • 标题:序号. [P级]标题
  • 已按 walkthrough-worksheet Batch 1→4 逐项检查
  • checklist_coverage 17 条均已填写,且 pass 均含 >=8 字验证证据
  • validate_checklist_coverage.py 已通过
  • URL/截图:每问题有标注图,且 images[].bbox 已记录
  • validate_report_annotations.py 已通过
  • docx 已生成,或已说明失败原因
  • 末尾附 docx 绝对路径(success 时)

附录

  • 门禁与完成判断:docs/onboarding/gates.md
  • 检查清单:references/ux-checklist.md
  • 分批工作表:references/walkthrough-worksheet.md
  • 报告模板:references/report-template.md
  • 标注规范:references/annotation-style.md

© XiaoMi, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 55 other files (scripts, references) in skills/hiui-workflow/ux-walkthrough of XiaoMi/hiui.

  • SKILL.md
  • .gitignore
  • README.md
  • agents/openai.yaml
  • docs/onboarding/execution-sop.md
  • docs/onboarding/gates.md
  • references/annotation-style.md
  • references/changelog.md
  • references/hiui-template-baseline.md
  • references/ignore-list.md
  • references/issue-examples/flow.md
  • references/issue-examples/interaction.md
  • references/issue-examples/visual.md
  • references/mode-code.md
  • references/mode-screenshot.md
  • references/mode-url.md
  • … and 40 more

Open the folder on GitHubat commit f056c80

Compare with similar skills

UX Walkthrough next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

UX Walkthrough compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
UX Walkthrough this skillXiaoMi/hiui877—~1.3kAutomated safety check: PassMIT
Impeccablebestofjs/bestofjs3.1k27 repos~2.6kAutomated safety check: PassMIT
Color Auditrome-os/rome725—~2.7kAutomated safety check: PassMIT
Edit Figma Designwarpdotdev/warp65k1 repos~2.4kAutomated safety check: PassAGPL-3.0
Super UI UX Designsyahiidkamil/Software-Engineer-AI-Agent-Atlas401—~9kAutomated safety check: PassNone
Intentghaida/intent206—~11kAutomated safety check: PassCC0-1.0

Similar skills

  • Impeccable

    bestofjs/bestofjs

    A skill your agent uses when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a…

    3.1k GitHub starsUsed in 27 repos~2.6k tokens
    Frontend & DesignAuto-check passed
  • Color Audit

    rome-os/rome

    Audit a design system's color palette against measurable color-science disciplines — WCAG/APCA contrast of declared token pairs, perceptual (OKLCH) ramp uniformity, color-blindness safety of…

    725 GitHub stars~2.7k tokensUpdated today
    Frontend & DesignAuto-check passed
  • Edit Figma Design

    warpdotdev/warp

    Creates or revises Figma designs from a written description using the Figma MCP authoring tools, in a new blank file or an existing one.

    65k GitHub starsUsed in 1 repo~2.4k tokens
    Frontend & DesignAuto-check passed
  • Super UI UX Design

    syahiidkamil/Software-Engineer-AI-Agent-Atlas

    Complete UI/UX design capability — a wiki-style knowledge map of design theory (UX laws, Nielsen heuristics, usability, visual hierarchy, typography, contrast/WCAG, design systems…

    401 GitHub stars~9k tokensUpdated 3 mo ago
    Frontend & DesignAuto-check passed
  • Intent

    ghaida/intent

    The entry point for Intent, a UX and design strategy system.

    206 GitHub stars~11k tokensUpdated 2 mo ago
    Frontend & DesignAuto-check passed
  • Penpot Uiux Design

    github/awesome-copilot

    Official

    Comprehensive guide for creating professional UI/UX designs in Penpot using MCP tools.

    40k GitHub starsUsed in 1 repo~3k tokens
    Frontend & DesignAuto-check passed

More from XiaoMi/hiui

  • Hiui

    XiaoMi/hiui

    A skill your agent uses when the user's task involves HiUI (@hi-ui/) — writing HiUI components, debugging HiUI issues, querying HiUI props/docs, migrating from HiUI V4 to V5, or setting up React 19…

    877 GitHub stars~1.9k tokensUpdated 2 mo ago
    Auto-check passed
  • Hiui Refine

    XiaoMi/hiui

    可作为 hiui-page-workflow 等更大页面工作流的标准 S0 前置 skill,专注 B 端中后台与 HiUI 页面生成前的需求细化。将模糊或抽象的后台/管理台/运营台/配置台/审批流需求细化为可执行的产品方案、MVP 范围、用户流程、业务规则、可追踪页面清单、产品 PRD、全局生成上下文、页面级提示词和 HiUI 交接包。适用于澄清后台产品想法、把粗略需求转成 PRD…

    877 GitHub stars~9.8k tokensUpdated 2 mo ago
    Auto-check passed
  • 用于 React / HiUI 页面从需求细化到端到端生成与验收。适用于从模糊产品需求生成并验收页面、 HiUI 页面提测前检查、页面生成后做体验走查、页面从需求到实现再到 UX 验收闭环等任务。

    877 GitHub stars~3.1k tokensUpdated 2 mo ago
    Auto-check passed
  • Hiui Design

    XiaoMi/hiui

    在 React 项目中接入、生成、修改、联调或验收 HiUI 典型页与非典型页面时使用。适用于 数据统计表、普通表格、树形表格、左树右表、数据可视化、异常反馈页、抽屉表单/详情、 全页编辑/详情、不规范原型截图转规范页、老旧系统截图/URL/源码现代化转译,以及 host-integration、rules-only、legacy-host-compatible 等场景。

    877 GitHub stars~3.3k tokensUpdated 2 mo ago
    Auto-check passed

Works with

Questions about UX Walkthrough

What does UX Walkthrough do?

体验走查 skill。适用于代码库、URL、截图三种输入,输出结构化体验问题报告,并同步生成本地 docx 报告。触发词:体验走查、UX review、交互走查、界面审查、体验问题。. UX Walkthrough is an agent skill from XiaoMi/hiui.

When should I use UX Walkthrough?

UX Walkthrough fits situations like: tasks that involve Word documents; tasks that involve UX design; tasks that involve Design systems.

How do I install UX Walkthrough in Claude Code?

Run `npx skills add XiaoMi/hiui --skill ux-walkthrough -a claude-code`. Or copy the skill folder (skills/hiui-workflow/ux-walkthrough in XiaoMi/hiui) into .claude/skills/ux-walkthrough in your project. Claude Code loads it when a task matches its description.

How do I install UX Walkthrough in Codex?

Run `npx skills add XiaoMi/hiui --skill ux-walkthrough -a codex`. Or copy the skill folder (skills/hiui-workflow/ux-walkthrough in XiaoMi/hiui) into .agents/skills/ux-walkthrough in your project. Codex loads it when a task matches its description.

Can I use UX Walkthrough in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add XiaoMi/hiui --skill ux-walkthrough -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/ux-walkthrough, .gemini/skills/ux-walkthrough, .github/skills/ux-walkthrough and .opencode/skills/ux-walkthrough in your project.

What does UX Walkthrough need to run?

Going by SKILL.md and its folder, UX Walkthrough needs the command-line tools its instructions call (python3). Our summary lists: Python 3.

Does UX Walkthrough access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is UX Walkthrough safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does UX Walkthrough use?

UX Walkthrough is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does UX Walkthrough use?

About 1.3k tokens (SKILL.md is roughly 5.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 31k tokens, read only when the agent opens those files.

What are the alternatives to UX Walkthrough?

Skills that share tags, products or a category with UX Walkthrough: Impeccable (bestofjs/bestofjs, 3.1k stars), Color Audit (rome-os/rome, 725 stars), Edit Figma Design (warpdotdev/warp, 65k stars) and Super UI UX Design (syahiidkamil/Software-Engineer-AI-Agent-Atlas, 401 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains UX Walkthrough?

XiaoMi (a GitHub organization) maintains it in XiaoMi/hiui, which has 877 GitHub stars. The repository holds 5 skills in this directory. The repository was last updated on July 24, 2026.

Source: XiaoMi/hiui on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.