UI Director Skill

一个面向 Claude Code / Codex 等 Coding Agent 的 UI/UX Orchestrator Skill。

它不试图成为第五套 UI 方法论，而是把四类 specialist 能力组合成一条可维护的生产工作流：

• UI UX Pro Max：设计探索 / 行业模式 / 风格、配色、字体参考
• Jakub Krehel Skills：Layout / Typography / Color / Accessibility / UX Writing / Interface polish
• Frontend Design System Skill：已有项目组件、Token、Theme、Design System 约束
• Impeccable：Audit / Critique / Distill / Polish

为什么这样设计

直接把四个 Skill 全部安装成宽触发 Skill，容易出现：

1. 多个 Skill 同时抢同一个 UI 请求。
2. 已有项目被外部“漂亮模板”覆盖掉原有设计语言。
3. Skill 上游更新后目录或命令变化，Orchestrator 失效。
4. 四个上游版本无法复现或回滚。

UI Director 使用 单入口 + Capability Registry + Adapter + 外部 Provider 架构。

                    UI Director
                         │
                 Capability Router
                         │
        ┌────────────────┼────────────────┐
        │                │                │
     Research       Design Eng.        Quality
        │                │                │
 UI UX Pro Max     Jakub Skills      Impeccable
                         │
                  Project System
                         │
             Frontend Design System

UI Director 本身只认 layout、typography、audit 这类逻辑能力，不依赖第三方目录结构。第三方结构变化由 adapters/*.json 消化。

最简单的使用方式

1. 解压

将压缩包解压到任意目录。

2. 安装 ui 命令

在解压目录执行：

npm install -g .

也可以开发模式：

npm link

安装后验证：

ui --help

3. 初始化项目

进入你的项目：

cd /path/to/project
ui init

ui init 会：

• 在 .ui-director/providers/ 拉取四个官方上游仓库
• 如果项目已有 .ui-director/skills.lock.json，优先复现其中锁定的 commit
• 首次初始化时写入 .ui-director/skills.lock.json（包含 provider commit 与 Git tree hash）
• 校验 adapters/capabilities
• 将 ui-director Skill 安装到：
  • .agents/skills/ui-director/（Codex / 通用 Agent Skills）
  • .claude/skills/ui-director/（Claude Code）

第三方 Skill 不会复制进 UI Director 包，所以不会因为这个压缩包变旧而锁死版本。

发布 npm

npm 发布由 .github/workflows/publish-npm.yml 执行。发布一个 GitHub Release 时，workflow 会：

1. 检查 Release 使用的稳定标签是否为 vX.Y.Z，并且与 package.json 的版本完全一致。
2. 运行 npm test 和 npm pack --dry-run。
3. 优先使用 npm Trusted Publishing 的 GitHub OIDC 发布 ui-director-skill；如果配置了 NPM_TOKEN，则仅用于首次 bootstrap 发布。

首次发布前，npm 包尚不存在，必须先在仓库的 Settings → Secrets and variables → Actions 新建 NPM_TOKEN，值为具备该包发布权限的短期 granular token。只为 v0.1.0 bootstrap 使用，完成后应删除 Secret。

首次发布成功后，在 npm 包设置中添加 Trusted Publisher：GitHub Actions、用户 matrixhawk、仓库 ui-director-skill、workflow 文件名 publish-npm.yml，允许 npm publish。然后删除 NPM_TOKEN Secret，后续发布就使用 OIDC，不再依赖 90 天 token。Trusted Publisher 必须在包首次存在后配置；当前 GitHub 仓库为私有仓库，因此 npm 不会生成 provenance。若需要 provenance，需要将仓库改为公开。

当前版本发布示例：

gh release create v0.1.0 \
  --repo matrixhawk/ui-director-skill \
  --title v0.1.0 \
  --generate-notes

后续版本先更新并提交 package.json 的版本，再创建匹配的 Release：

npm version patch
git push origin main --follow-tags
gh release create "v$(node -p "require('./package.json').version")" \
  --repo matrixhawk/ui-director-skill \
  --generate-notes

预发布标签不会触发 npm 发布；失败的稳定版本可以从 Actions 页面用同一个标签手动重新运行 workflow。npm token 和 Trusted Publishing 的说明见 npm access tokens 与 npm Trusted Publishing。

Agent 使用

Codex/支持显式 Skill 的环境可以直接要求：

$ui-director 给当前后台增加一个模型管理页面

Claude Code 也可以直接自然语言指定 ui-director。

如果你的环境支持自定义 slash command，可以把 /ui 映射到 ui-director；UI Director 本身不依赖 slash-command 标准，因此跨 Agent 更稳定。

CLI

日常只需要记两个：

ui
ui update

完整命令：

ui init                  # 初始化当前项目
ui status                # 查看当前 provider 版本
ui update                # 更新全部 provider，并自动验证
ui update jakub-skills   # 只更新一个 provider
ui doctor                # 完整健康检查
ui diff                  # 查看上游变化
ui rollback              # 回滚全部可回滚 provider
ui rollback impeccable   # 回滚指定 provider
ui resolve layout        # 内部/高级：解析逻辑能力到真实文件

更新设计

Provider 存放在：

.ui-director/providers/
├── ui-ux-pro-max/
├── jakub-skills/
├── design-system/
└── impeccable/

版本记录：

.ui-director/skills.lock.json

更新流程：

ui update
   ↓
   git fetch origin
   ↓
保存 previous ref
   ↓
切换到新版本
   ↓
Adapter validation
   ↓
Capability validation
   ↓
FAIL ──→ 自动恢复旧版本
   │
  PASS
   ↓
更新 lockfile

所以 ui update 不会直接把已工作的 Skill 覆盖坏。

Provider 内容会作为 Agent 的 specialist 指令读取。请把它们视为外部不可信输入；ui doctor 会检查配置来源、锁定 commit 和 tree hash，发现不一致时应先停止并人工确认。

上游变化如何兼容

例如 Jakub 将：

skills/better-layout/SKILL.md

改成：

skills/interface-layout/SKILL.md

只需修改：

adapters/jakub-skills.json

而不是修改 UI Director 的路由方法论。

路由原则

新项目、没有视觉方向

Research
→ Interface/Layout/Typography/Color
→ Implementation
→ Accessibility
→ Audit
→ Distill
→ Polish

已有项目新增页面

Design System
→ Relevant Design Engineering
→ Implementation
→ Audit
→ Polish

默认不会调用 UI UX Pro Max，以免破坏已有视觉语言。

小问题

只选择最窄能力，例如：

字体层级问题 → typography
间距/层级问题 → layout
键盘/焦点问题 → accessibility
文案问题 → writing
视觉细节 → interface

Audit

Audit
→ Identify defects
→ Targeted remediation

不会先把页面重做一遍。

目录说明

ui-director-skill/
├── SKILL.md                 # Agent Orchestrator 核心
├── README.md                # 本说明
├── INSTALL.md               # 安装/升级/卸载说明
├── package.json             # 提供 ui / ui-director 命令
├── bin/
│   └── ui.mjs               # CLI
├── lib/
│   └── core.mjs             # Provider 管理、校验、回滚
├── config/
│   ├── providers.json       # 四个官方上游
│   └── capabilities.json    # 逻辑能力注册表
├── adapters/
│   ├── ui-ux-pro-max.json
│   ├── jakub-skills.json
│   ├── design-system.json
│   └── impeccable.json
├── references/
│   ├── routing.md
│   ├── project-inspection.md
│   └── quality-gates.md
└── examples/
    └── usage.md

官方上游

本包 不包含第三方 Skill 内容，初始化时从官方仓库获取：

• https://github.com/nextlevelbuilder/ui-ux-pro-max-skill
• https://github.com/jakubkrehel/skills
• https://github.com/chrometaphore/design-system-skill
• https://github.com/pbakaus/impeccable

各第三方项目继续遵循它们自己的许可证和使用条款。

设计目标

UI Director 的目标不是让 Agent “多调用 Skill”，而是：

在正确的时间，只加载最少且最合适的 UI/UX 专业知识。

最终效果应该是：外部使用极简，内部可更新、可验证、可回滚、可替换。