一个 Skill 如何让大模型拥有专业 UI 能力？——ui-ux-pro-max 架构深度拆解与 Skill 设计方法论

当所有人都在抱怨大模型生成的 UI "能用但不好看"时，一个名为 ui-ux-pro-max 的 Skill 项目给出了截然不同的解法：不微调、不训练、不依赖多模态，仅凭一个 Skill 就让 AI 编码助手输出专业级 UI。它是怎么做到的？这种设计范式的本质是什么？我们又该如何设计自己的 Skill？

一、问题：大模型的 UI 能力困境

大语言模型在代码生成上已经足够强大，但一旦涉及 UI 设计，问题就暴露了：

风格选择困难：模型不知道 SaaS 产品该用 Glassmorphism 还是 Minimalism，电商该用 Vibrant Block 还是 Liquid Glass
配色凭感觉：生成的颜色组合经常违反对比度标准，暗色模式下文字不可读
字体搭配随意：标题和正文字体缺乏语义关联，视觉层次混乱
UX 规则缺失：触控目标小于 44px、缺少 focus 状态、动画时长不合理、无障碍标准被忽略
跨页面不一致：首页用了一套风格，详情页又换了另一套

这些问题的根源不是模型不够聪明，而是模型缺乏结构化的设计知识。就像一个没有设计系统的前端工程师，即使代码能力再强，产出的 UI 也难以专业。

ui-ux-pro-max 的核心洞察是：与其让模型"学会"设计，不如给模型一个可搜索的设计知识库和推理引擎。

二、ui-ux-pro-max 架构全景

2.1 项目定位

ui-ux-pro-max 是一个面向 AI 编码助手（Claude Code、Cursor、Windsurf、GitHub Copilot 等 15 种平台）的 UI/UX 设计智能工具包。它不修改模型本身，而是通过 Skill 机制将设计知识注入 AI 的工作流。

核心数据规模：

维度	数量	说明
UI 风格	67 种	从 Minimalism 到 3D Hyperrealism
配色方案	161 个	按产品类型/行业分类
字体搭配	57 种	含 Google Fonts URL 和 CSS Import
产品类型	161 种	覆盖 SaaS、电商、医疗、教育等
行业推理规则	161 条	产品类型 → 风格/配色/字体的推理链
UX 准则	99 条	含 Do/Don't 和代码示例
图表类型	25 种	含无障碍评级和库推荐
技术栈	13 种	React、Next.js、Vue、Svelte、SwiftUI 等

2.2 三层架构

整个项目采用知识层 → 推理层 → 交互层的三层架构：

复制代码

┌─────────────────────────────────────────────────┐
│              交互层 (SKILL.md + CLI)             │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ SKILL.md │  │ search.py│  │ uipro-cli     │  │
│  │ 触发规则  │  │ CLI 入口  │  │ 跨平台安装器   │  │
│  └──────────┘  └──────────┘  └───────────────┘  │
├─────────────────────────────────────────────────┤
│              推理层 (Python 搜索引擎)             │
│  ┌──────────┐  ┌──────────────┐  ┌───────────┐  │
│  │ BM25 核心 │  │ 设计系统生成器 │  │ 域自动检测 │  │
│  │ core.py  │  │design_system │  │detect_    │  │
│  │          │  │   .py       │  │domain()   │  │
│  └──────────┘  └──────────────┘  └───────────┘  │
├─────────────────────────────────────────────────┤
│              知识层 (15 个 CSV 数据库)            │
│  ┌─────┐┌──────┐┌────────┐┌────┐┌──────────┐   │
│  │style││color ││typogra-││ux  ││ui-reason-│   │
│  │.csv ││.csv  ││phy.csv ││.csv││ing.csv   │   │
│  └─────┘└──────┘└────────┘└────┘└──────────┘   │
│  ┌─────┐┌──────┐┌────────┐┌────┐┌──────────┐   │
│  │chart││land- ││product ││icon││react-    │   │
│  │.csv ││ing.  ││.csv    ││.csv││perf.csv  │   │
│  │     ││csv   ││        ││    ││          │   │
│  └─────┘└──────┘└────────┘└────┘└──────────┘   │
└─────────────────────────────────────────────────┘

这种分层的精妙之处在于：知识可以独立更新，推理逻辑可以独立优化，交互方式可以独立适配。你不需要改模型，不需要重新训练，只需要更新 CSV 数据或调整推理规则，就能让 AI 的设计能力持续进化。

三、核心机制深度拆解

3.1 知识层：为什么是 CSV 而不是向量数据库？

这是一个值得深思的设计决策。在 RAG（检索增强生成）盛行的时代，ui-ux-pro-max 选择了最朴素的 CSV + BM25 方案，而非 Pinecone/Weaviate 等向量数据库。原因有三：

1) 数据规模可控，无需向量检索的规模优势

15 个 CSV 文件，总计不到 1000 条记录。BM25 在这个规模下的检索速度和准确性完全够用，引入向量数据库是过度工程。

2) 结构化数据的精确匹配优于语义模糊匹配

设计知识是高度结构化的------"SaaS 产品应该用什么风格"不是一个语义模糊匹配问题，而是一个精确的分类推理问题。BM25 的关键词匹配在这里反而比向量相似度更可控。

3) 零依赖、可移植

CSV + 纯 Python BM25 实现，不需要任何外部服务或数据库。这意味着 Skill 可以在本地离线运行，不增加任何基础设施成本。

来看 styles.csv 的实际结构（每条记录包含 22 个字段）：

csv 复制代码

No,Style Category,Type,Keywords,Primary Colors,Secondary Colors,
Effects & Animation,Best For,Do Not Use For,Light Mode ✓,Dark Mode ✓,
Performance,Accessibility,Mobile-Friendly,Conversion-Focused,
Framework Compatibility,Era/Origin,Complexity,AI Prompt Keywords,
CSS/Technical Keywords,Implementation Checklist,Design System Variables

每条风格记录不仅告诉你"是什么"，还告诉你：

Best For / Do Not Use For：适用场景和禁忌场景
Performance / Accessibility：性能和无障碍评级
AI Prompt Keywords：给 AI 的提示词关键词
CSS/Technical Keywords：技术实现关键词
Implementation Checklist：实现检查清单
Design System Variables：设计系统变量

这种多维度的结构化知识是 Skill 能产生专业输出的关键。模型不需要"理解"设计，它只需要检索到正确的知识，然后遵循。

3.2 推理层：BM25 + 行业推理规则的组合拳

BM25 搜索引擎（core.py）

项目自行实现了一个 BM25 排名算法，核心参数 k1=1.5, b=0.75（标准值）。搜索流程：

复制代码

用户查询 "fintech crypto"
    ↓
自动域检测 → domain="style"（基于关键词匹配）
    ↓
加载 styles.csv → 构建 BM25 索引
    ↓
对 search_cols 的拼接文本进行 BM25 打分
    ↓
返回 top-N 结果（默认 3 条）

域自动检测（detect_domain）是一个精巧的设计。它为 11 个搜索域各定义了一组关键词，通过正则匹配计算每个域的得分，选择得分最高的域。例如：

查询包含 "color", "palette", "hex" → color 域
查询包含 "chart", "graph", "trend" → chart 域
查询包含 "react", "suspense", "memo" → react 域

如果没有任何匹配，默认回退到 style 域。

设计系统生成器（design_system.py）

这是整个项目最核心的组件。它不是简单的搜索，而是一个多域并行搜索 + 推理规则应用 + 最佳匹配选择的复合引擎。

工作流程：

复制代码

Step 1: 搜索 product 域 → 获取产品类型（如 "SaaS"）
    ↓
Step 2: 从 ui-reasoning.csv 查找推理规则
    → style_priority: ["Glassmorphism", "Flat Design"]
    → color_mood: "Trust blue + Accent contrast"
    → typography_mood: "Professional + Hierarchy"
    → anti_patterns: "Excessive animation + Dark mode by default"
    ↓
Step 3: 多域并行搜索（product, style, color, landing, typography）
    → style 搜索注入推理规则的 style_priority 作为额外关键词
    ↓
Step 4: 从每个域的结果中选择最佳匹配
    → style: 优先匹配推理规则推荐的风格名
    → color/typography/landing: 取 BM25 得分最高的结果
    ↓
Step 5: 组装完整设计系统
    → pattern + style + colors + typography + effects + anti_patterns

推理规则（ui-reasoning.csv） 是这个流程的灵魂。来看一条实际规则：

csv 复制代码

UI_Category: SaaS (General)
Recommended_Pattern: Hero + Features + CTA
Style_Priority: Glassmorphism + Flat Design
Color_Mood: Trust blue + Accent contrast
Typography_Mood: Professional + Hierarchy
Key_Effects: Subtle hover (200-250ms) + Smooth transitions
Decision_Rules: {"if_ux_focused": "prioritize-minimalism", "if_data_heavy": "add-glassmorphism"}
Anti_Patterns: Excessive animation + Dark mode by default
Severity: HIGH

这条规则编码了专业设计师的决策逻辑：

SaaS 产品推荐 Hero + Features + CTA 的页面模式
风格优先选 Glassmorphism 或 Flat Design
配色走信任蓝 + 强调色对比
如果 UX 优先，切换到 Minimalism；如果数据密集，加入 Glassmorphism
禁止过度动画和默认暗色模式

这就是为什么一个 Skill 能解决大模型的 UI 能力问题------它不是在教模型"怎么设计"，而是在替模型做"设计决策"。

3.3 交互层：SKILL.md 作为 AI 的"操作手册"

SKILL.md 是整个 Skill 与 AI 交互的入口，它定义了：

1) 触发条件（When to Apply）

明确告诉 AI 什么时候必须使用、推荐使用、跳过这个 Skill：

Must Use：设计新页面、创建 UI 组件、选择配色/字体、审查 UI 代码
Recommended：UI "不够专业"但原因不明、可用性反馈、上线前优化
Skip：纯后端逻辑、API/数据库设计、基础设施工作

2) 优先级规则（Rule Categories by Priority）

10 个规则类别，按优先级 1→10 排列：

优先级	类别	影响级别
1	Accessibility	CRITICAL
2	Touch & Interaction	CRITICAL
3	Performance	HIGH
4	Style Selection	HIGH
5	Layout & Responsive	HIGH
6	Typography & Color	MEDIUM
7	Animation	MEDIUM
8	Forms & Feedback	MEDIUM
9	Navigation Patterns	HIGH
10	Charts & Data	LOW

每个类别下有 10-30 条具体规则，每条规则都有标准、反模式和依据来源（Apple HIG、Material Design、WCAG）。

3) 四步工作流

复制代码

Step 1: 分析用户需求 → 提取产品类型、目标受众、风格关键词、技术栈
Step 2: 生成设计系统 → --design-system（必须执行）
Step 2b: 持久化设计系统 → Master + Overrides 模式
Step 3: 补充详细搜索 → --domain 按需查询
Step 4: 技术栈指南 → --stack 查询实现细节

4) 设计系统持久化（Master + Overrides Pattern）

这是一个非常精巧的设计。当使用 --persist 参数时，系统会创建：

复制代码

design-system/
├── MASTER.md          # 全局唯一真相来源
└── pages/
    ├── dashboard.md   # 仪表盘页面覆盖规则
    ├── checkout.md    # 结账页面覆盖规则
    └── ...

检索逻辑：

构建特定页面时，先检查 pages/[page-name].md
如果存在，其规则覆盖 MASTER.md
如果不存在，严格遵循 MASTER.md

这解决了跨页面设计一致性的问题------全局规则在 MASTER.md 中定义，页面特例在 pages/ 中覆盖，而不是每个页面各自为政。

3.4 跨平台适配：模板引擎

项目通过模板引擎支持 15 种 AI 编码助手。每种平台有一个 JSON 配置文件，定义了：

安装目录结构（如 Claude Code 用 .claude/skills/，Cursor 用 .cursor/）
Frontmatter 格式（不同平台对 Skill 元数据的解析方式不同）
是否包含 Quick Reference 部分
Skill 描述文案的差异化

模板渲染流程：

复制代码

platforms/claude.json + templates/base/skill-content.md
    ↓
renderSkillFile() → 替换 {{TITLE}}, {{DESCRIPTION}}, {{SCRIPT_PATH}} 等占位符
    ↓
生成 .claude/skills/ui-ux-pro-max/SKILL.md
    ↓
复制 data/ 和 scripts/ 到 Skill 目录（自包含安装）

CLI 安装器（uipro-cli）还支持自动检测当前项目使用的 AI 平台，交互式选择安装目标。

四、为什么这样设计？------设计决策分析

4.1 为什么用 BM25 而不是向量检索？

维度	BM25	向量检索
依赖	零（纯 Python）	需要嵌入模型 + 向量数据库
精确匹配	强（关键词精确命中）	弱（语义近似可能偏离）
可解释性	高（可追溯匹配词）	低（嵌入空间不可解释）
部署成本	零	高（GPU/云服务）
离线能力	完全支持	有限
规模扩展性	千级以下最优	万级以上最优

对于设计知识库这种小规模、高结构化、需精确匹配的场景，BM25 是更务实的选择。

4.2 为什么用 CSV 而不是数据库？

可读性：任何人都可以用 Excel 或文本编辑器查看和编辑
版本控制：CSV 是纯文本，Git diff 友好
零配置：不需要安装和运维数据库
可移植性：一个文件就是一个数据表，复制即用

4.3 为什么推理规则是 CSV 而不是硬编码？

ui-reasoning.csv 的 161 条推理规则以数据而非代码的形式存在，这意味着：

非程序员（设计师）可以编辑推理规则
规则的增删改不需要修改代码
规则可以独立 review 和版本控制

4.4 为什么 SKILL.md 要包含 Quick Reference？

SKILL.md 中的 10 个规则类别、200+ 条具体规则，看起来冗长，但这是刻意的设计：

减少搜索调用：常见问题可以直接在 SKILL.md 中找到答案，不需要每次都调用 Python 脚本
降低延迟：SKILL.md 是 AI 上下文的一部分，读取零延迟
保证底线质量：即使 Python 环境不可用，SKILL.md 中的规则仍然能指导 AI 避免最基本的 UI 错误

五、这种设计的优势与局限

5.1 优势

1) 即插即用，零训练成本

不需要微调模型，不需要准备训练数据，不需要 GPU。安装 Skill 后 AI 立刻获得设计能力。

2) 知识可独立迭代

发现新的设计趋势？添加一条 style 记录。发现推理规则不合理？修改 ui-reasoning.csv。知识的更新不需要重新训练模型，也不需要等待模型厂商更新。

3) 决策过程可追溯

每一条设计建议都可以追溯到具体的 CSV 记录和推理规则。这比模型"凭感觉"生成的设计建议更可信，也更容易 debug。

4) 跨平台兼容

一套知识库 + 推理引擎，通过模板引擎适配 15 种 AI 编码助手。知识投资的一次编写，到处使用。

5) 离线可用

不依赖任何云服务或 API。Python + CSV 就能运行，适合企业内网和离线环境。

5.2 局限

1) 知识库的覆盖度有限

161 种产品类型、67 种风格------对于主流场景足够，但长尾场景（如工业控制界面、车载 HMI）可能没有覆盖。扩展知识库需要人工整理和录入。

2) BM25 的语义理解能力有限

BM25 基于关键词匹配，无法理解同义词和语义关联。例如搜索"科技感"可能匹配不到" futurism"风格。detect_domain 的关键词列表也是硬编码的，不够灵活。

3) 推理规则是静态的

ui-reasoning.csv 中的推理规则是预定义的，无法根据上下文动态调整。例如 "SaaS → Glassmorphism" 是一条静态规则，但实际项目中 SaaS 产品的风格选择还受品牌调性、用户群体、竞品分析等因素影响。

4) 缺乏反馈闭环

系统没有收集 AI 实际输出的质量反馈。如果 AI 基于 Skill 的建议生成了糟糕的 UI，这个信号无法回流到知识库来改进推理规则。

5) CSV 的表达力有限

CSV 是扁平结构，难以表达设计知识之间的复杂关系（如"风格 A 和风格 B 互斥"、"配色方案 C 只适用于暗色模式"）。这些关系目前只能通过自然语言描述在字段中表达。

6) 单一搜索引擎实例

每次搜索都会重新加载 CSV 并构建 BM25 索引，没有缓存机制。在高频调用场景下可能存在性能问题。

六、为什么一个 Skill 就能解决大模型的 UI 能力？

这个问题的答案揭示了 Skill 范式的本质：

6.1 大模型的 UI 问题不是能力问题，而是知识问题

大模型已经具备了生成 HTML/CSS/JS 的能力，也理解设计概念的含义。它缺的不是"能力"，而是结构化的、可检索的设计决策知识。

类比：一个熟练的木匠（大模型）不缺手艺，缺的是设计图纸（Skill）。给他图纸，他就能做出专业的家具；不给图纸，他只能凭记忆和感觉做。

6.2 Skill 的本质是外部化的专家决策系统

ui-ux-pro-max 做的事情，本质上是把一个资深 UI/UX 设计师的决策过程外部化、结构化、可检索化：

复制代码

设计师的决策过程：
  看到需求 → 识别产品类型 → 调用经验规则 → 选择风格/配色/字体 → 检查反模式

ui-ux-pro-max 的决策过程：
  解析查询 → 搜索产品类型 → 应用推理规则 → 多域搜索选择最佳 → 输出反模式警告

两者是同构的。Skill 不是在增强模型的"智能"，而是在替模型做"决策"。

6.3 关键洞察：设计决策比设计执行更重要

大模型擅长执行（写代码），但不擅长决策（选什么风格、用什么配色）。Skill 的价值在于把决策和执行分离：

Skill 负责决策：基于知识库和推理规则，输出设计系统
模型负责执行：基于设计系统，生成代码

这种分离让两者各司其职，发挥各自的优势。

七、真正的 Skill 应该怎么设计？------Skill 设计方法论

基于对 ui-ux-pro-max 的深度拆解，我总结出一套通用的 Skill 设计方法论。

7.1 第一步：识别"知识密集型决策"场景

不是所有场景都适合用 Skill。Skill 最适合的场景特征：

特征	说明
决策依赖专业知识	模型凭自身知识做不出正确决策
知识可结构化	专业知识可以整理为表格/规则/流程
决策有标准答案	存在行业共识或最佳实践
错误代价高	错误决策导致严重后果（如无障碍违规）
知识需要频繁更新	模型训练数据会过时，Skill 知识可以随时更新

ui-ux-pro-max 完美符合所有特征：UI 设计决策依赖专业知识、设计知识可结构化为 CSV、有 Apple HIG/Material Design 等行业标准、无障碍违规后果严重、设计趋势不断变化。

7.2 第二步：构建知识层

原则：知识应该是结构化的、多维度的、可检索的。

以 ui-ux-pro-max 的 styles.csv 为例，一条风格记录包含 22 个字段，覆盖了"是什么、适用于什么、不适用于什么、怎么实现、怎么验证"五个维度：

复制代码

是什么    → Style Category, Type, Keywords
适用于什么 → Best For, Framework Compatibility
不适用于什么 → Do Not Use For, Anti-Patterns
怎么实现  → CSS/Technical Keywords, Implementation Checklist, Design System Variables
怎么验证  → Performance, Accessibility, Implementation Checklist

设计你自己的知识层时，问自己：

我的知识有哪些维度？（风格、配色、字体、交互、无障碍...）
每条知识需要哪些字段才能支持完整决策？
哪些字段用于搜索（search_cols），哪些用于输出（output_cols）？
知识之间有没有推理关系？（如产品类型 → 风格推荐）

7.3 第三步：设计推理层

原则：推理应该是显式的、可追溯的、可覆盖的。

ui-ux-pro-max 的推理层有三个关键设计：

1) 推理规则数据化

推理规则不是硬编码在代码中，而是存储在 ui-reasoning.csv 中。每条规则包含：

复制代码

前提条件（UI_Category）→ 推荐结论（Pattern, Style_Priority, Color_Mood...）
→ 条件分支（Decision_Rules）→ 禁忌（Anti_Patterns）→ 严重程度（Severity）

2) 多域并行搜索 + 优先级融合

不是单一搜索，而是同时搜索多个域（product, style, color, landing, typography），然后用推理规则的优先级来融合结果。

3) 最佳匹配选择

从多个搜索结果中，基于推理规则的优先级关键词选择最佳匹配，而不是简单取第一个。

设计你自己的推理层时，问自己：

我的领域有哪些决策链？（A 类型的需求 → B 方案 → C 参数）
决策链中的条件分支是什么？（如果 X，则选 Y；如果 Z，则选 W）
多个知识域的结果如何融合？有没有优先级？
推理规则是否需要非技术人员（如领域专家）编辑？

7.4 第四步：设计交互层

原则：交互应该是触发式的、分步的、可降级的。

1) 触发条件明确

SKILL.md 的 "When to Apply" 部分明确定义了 Must Use / Recommended / Skip 三种场景。这让 AI 知道什么时候该用、什么时候不该用，避免过度触发。

2) 分步工作流

不是一次性输出所有信息，而是分步引导：

复制代码

Step 1: 分析需求（轻量，不需要搜索）
Step 2: 生成设计系统（核心，必须执行）
Step 3: 补充搜索（按需，可选）
Step 4: 技术栈指南（按需，可选）

这种分步设计减少了不必要的搜索调用，也降低了 token 消耗。

3) 可降级

即使 Python 环境不可用，SKILL.md 中的 Quick Reference 仍然能提供基本的规则指导。即使搜索脚本失败，AI 仍然可以基于 SKILL.md 中的规则避免最基本的错误。

设计你自己的交互层时，问自己：

AI 在什么场景下应该自动触发这个 Skill？
哪些步骤是必须的，哪些是可选的？
如果搜索/推理失败，AI 应该怎么做？（降级策略）
输出格式应该如何优化以减少 token 消耗？

7.5 第五步：设计持久化策略

原则：持久化应该是分层的、可覆盖的、上下文感知的。

ui-ux-pro-max 的 Master + Overrides 模式是一个优秀的参考：

复制代码

MASTER.md（全局规则）
    ↑ 覆盖
pages/dashboard.md（仪表盘特例）
    ↑ 覆盖
pages/checkout.md（结账页特例）

这种模式解决了两个问题：

一致性：全局规则确保跨页面一致
灵活性：页面覆盖允许特例存在

设计你自己的持久化策略时，问自己：

哪些规则是全局的，哪些是上下文相关的？
上下文相关的规则如何与全局规则交互？
持久化的数据如何被 AI 在后续对话中检索？

7.6 第六步：设计跨平台适配

原则：知识一次编写，交互按平台适配。

ui-ux-pro-max 的做法是：

知识层（CSV）和推理层（Python）是平台无关的
交互层（SKILL.md）通过模板引擎按平台生成
每个平台的差异通过 JSON 配置文件描述

设计你自己的跨平台适配时，问自己：

哪些 AI 平台需要支持？它们的 Skill/Rule 格式是什么？
知识和推理是否可以保持平台无关？
平台差异点有哪些？（目录结构、元数据格式、触发机制）

八、Skill 设计实战教程：从零构建一个 API 设计 Skill

为了让你更直观地理解 Skill 设计方法论，我们来实战构建一个"API 设计规范 Skill"。

8.1 识别场景

特征	API 设计规范
决策依赖专业知识	RESTful/GraphQL/gRPC 选型、状态码使用、分页策略
知识可结构化	规则可整理为表格
决策有标准答案	HTTP 语义、OpenAPI 规范
错误代价高	API 设计不当导致客户端集成困难
知识需要频繁更新	新的 API 模式和最佳实践不断出现

符合 Skill 场景特征，继续。

8.2 构建知识层

创建 data/api-styles.csv：

csv 复制代码

No,API_Style,Type,Keywords,Best_For,Do_Not_Use_For,Performance,Versioning_Strategy,
Error_Handling,Authentication,Implementation_Checklist
1,RESTful,General,"resources, verbs, stateless, cacheable, uniform interface",
CRUD-heavy applications, public APIs, mobile backends,
Real-time streaming, binary protocols, high-frequency trading,
Good,URL path (/v1/) or header,
RFC 7807 Problem Details,OAuth 2.0 / API Key,
"☐ Resources are nouns not verbs, ☐ Proper HTTP methods, ☐ Consistent status codes, ☐ HATEOAS links if needed"
2,GraphQL,Query,"schema, types, resolver, single endpoint, flexible queries",
Complex data graphs, frontend-driven queries, aggregation APIs,
Simple CRUD, binary data upload, caching-critical systems,
Variable,Schema evolution with @deprecated,
User-facing error array,Bearer token,
"☐ Schema defined with types, ☐ N+1 query prevention, ☐ Depth limiting, ☐ Introspection disabled in production"
3,gRPC,RPC,"protobuf, streaming, bidirectional, code-gen, high-performance",
Microservice internal, real-time streaming, low-latency systems,
Browser clients, public APIs, rapid prototyping,
Excellent,Protobuf field numbers,
Status codes with details,mTLS / Service mesh,
"☐ .proto files defined, ☐ Streaming patterns correct, ☐ Deadlines propagated, ☐ Health checks implemented"

创建 data/api-reasoning.csv：

csv 复制代码

No,API_Category,Recommended_Style,Style_Priority,Error_Strategy,Auth_Strategy,
Decision_Rules,Anti_Patterns,Severity
1,CRUD Application,RESTful,RESTful + GraphQL,RFC 7807 Problem Details,OAuth 2.0,
{"if_realtime": "switch-to-grpc", "if_complex_queries": "add-graphql"},
Verb-in-URL + Non-standard status codes + No pagination,HIGH
2,Real-time System,gRPC,gRPC + RESTful for public,Stream errors with details,mTLS,
{"if_browser_client": "add-rest-or-graphql-bridge", "if_public_api": "add-rest-wrapper"},
Polling + REST for real-time + No deadline propagation,CRITICAL

8.3 设计推理层

python 复制代码

# api_skill/core.py
import csv
from pathlib import Path
from math import log
from collections import defaultdict

DATA_DIR = Path(__file__).parent.parent / "data"

class BM25:
    # ... (与 ui-ux-pro-max 相同的 BM25 实现)

def search(query, domain, max_results=3):
    # ... (与 ui-ux-pro-max 相同的搜索逻辑)

def generate_api_design(query, project_name=None):
    """生成 API 设计规范"""
    # Step 1: 搜索 API 风格
    style_result = search(query, "api-styles", 3)
    
    # Step 2: 应用推理规则
    reasoning = find_reasoning_rule(query)
    
    # Step 3: 选择最佳匹配
    best_style = select_best_match(style_result, reasoning.style_priority)
    
    # Step 4: 组装输出
    return {
        "style": best_style,
        "reasoning": reasoning,
        "checklist": best_style.implementation_checklist
    }

8.4 设计交互层

创建 SKILL.md：

markdown 复制代码

---
name: api-design-pro
description: "API design intelligence for RESTful, GraphQL, and gRPC. 
Includes style selection, error handling, authentication, and versioning 
strategies. Actions: plan, design, review, fix API code."
---

# API Design Pro - Design Intelligence

## When to Apply

### Must Use
- Designing new API endpoints or services
- Choosing API style (REST, GraphQL, gRPC)
- Reviewing API code for consistency and best practices
- Implementing error handling, authentication, or versioning

### Skip
- Pure frontend development
- Database schema design only
- Infrastructure/DevOps work

## Rule Categories by Priority

| Priority | Category | Impact |
|----------|----------|--------|
| 1 | HTTP Semantics | CRITICAL |
| 2 | Error Handling | CRITICAL |
| 3 | Authentication | HIGH |
| 4 | Versioning | HIGH |
| 5 | Pagination | MEDIUM |
| 6 | Rate Limiting | MEDIUM |

## How to Use

### Step 1: Analyze Requirements
- API type: CRUD, Real-time, Query-heavy, Mixed
- Clients: Browser, Mobile, Microservice, Public
- Performance: Latency requirements, throughput

### Step 2: Generate API Design
python3 skills/api-design-pro/scripts/search.py "<api_type> <requirements>" --design-system

### Step 3: Supplement with Domain Searches
python3 skills/api-design-pro/scripts/search.py "<keyword>" --domain error-handling

8.5 完整目录结构

复制代码

api-design-pro/
├── .claude/skills/api-design-pro/
│   ├── SKILL.md
│   ├── data/
│   │   ├── api-styles.csv
│   │   ├── api-reasoning.csv
│   │   ├── error-codes.csv
│   │   └── auth-patterns.csv
│   └── scripts/
│       ├── core.py
│       ├── design_system.py
│       └── search.py
└── src/
    └── api-design-pro/        # 唯一真相来源
        ├── data/
        ├── scripts/
        └── templates/

九、总结：Skill 范式的本质

9.1 Skill 不是 Prompt Engineering

Prompt Engineering 是给模型写更好的指令，期望模型凭自身知识给出更好的回答。Skill 是给模型外挂一个知识库和推理引擎，让模型的决策基于结构化知识而非参数化记忆。

维度	Prompt Engineering	Skill
知识来源	模型参数	外部知识库
知识更新	重新训练/微调	更新 CSV/数据库
决策过程	黑盒	可追溯
可靠性	不稳定（受上下文影响）	稳定（基于规则）
扩展性	受 token 限制	知识库可无限扩展

9.2 Skill 不是 RAG

RAG 是通用的检索增强方案，适合开放域问答。Skill 是领域专用的决策增强方案，适合结构化决策场景。

维度	RAG	Skill
检索目标	事实性知识	决策性知识
检索方式	向量相似度	BM25/精确匹配
输出	相关文档片段	结构化决策结果
推理	无（依赖模型）	有（推理规则）
适用场景	开放域问答	专业领域决策

9.3 Skill 的本质是"外部化的专家决策系统"

一个优秀的 Skill 应该做到：

知识结构化：把领域专家的隐性知识转化为显性的、可检索的结构化数据
推理显式化：把专家的决策过程转化为可追溯的推理规则
交互标准化：把专家的工作方式转化为 AI 可执行的标准化流程
持久化分层：把专家的记忆模式转化为 Master + Overrides 的分层存储
跨平台复用：把专家的知识转化为平台无关的、可移植的资产

ui-ux-pro-max 证明了：当知识足够结构化、推理足够显式、交互足够标准时，一个 Skill 就足以让大模型在特定领域达到专家水平。

这不是因为模型变聪明了，而是因为我们把"聪明"外化了。

附录：关键源码索引

文件	作用	关键行
`src/ui-ux-pro-max/scripts/core.py`	BM25 搜索引擎核心	L89-148: BM25 实现
`src/ui-ux-pro-max/scripts/core.py`	域自动检测	L183-203: detect_domain()
`src/ui-ux-pro-max/scripts/design_system.py`	设计系统生成器	L37-236: DesignSystemGenerator
`src/ui-ux-pro-max/scripts/design_system.py`	推理规则应用	L88-120: _apply_reasoning()
`src/ui-ux-pro-max/scripts/design_system.py`	智能页面覆盖	L914-1017: _generate_intelligent_overrides()
`src/ui-ux-pro-max/scripts/design_system.py`	Master+Overrides 持久化	L491-539: persist_design_system()
`src/ui-ux-pro-max/scripts/search.py`	CLI 入口	L56-114: argparse 命令定义
`src/ui-ux-pro-max/data/styles.csv`	67 种 UI 风格	22 个字段/条
`src/ui-ux-pro-max/data/ui-reasoning.csv`	161 条推理规则	10 个字段/条
`.claude/skills/ui-ux-pro-max/SKILL.md`	Skill 交互定义	659 行，10 个规则类别
`cli/src/utils/template.ts`	模板渲染引擎	L118-143: renderSkillFile()

本文原创，原创不易，如需转载，请联系作者授权。