UI Skills 落地：用文件资产与校验脚本稳住 Agent 生成界面

UI Skills 这个概念提出来有一阵子了真正在自己项目里跑通的人却不多。我见过的典型情况是设计规范写了厚厚一份文档组件库也整理得挺干净交给 Agent 生成界面出来的东西第一眼还行多生成几屏就开始跑偏——圆角忽大忽小间距全凭感觉同一个按钮在不同页面长成两个样子。问题不在模型不会写 CSS而在于它的“技能上下文”是断的规范躺在文档里、令牌躺在配置文件里、真实用法躺在老代码里Agent 每次都要靠猜。我后来把 UI Skills 拆成可被稳定加载的文件资产配合 Claude Code 的文件读取、命令执行和结果回看能力这套流程才算稳下来。下面我把三条接入路线的差异、实测数据和踩过的坑完整摊开讲适合正在把设计规范往 Agent 工作流里塞的前端、设计工程师和团队技术负责人参考也适合刚接触 Skills 机制、想知道它到底和“往提示词里塞规范”有什么区别的同学。1. UI Skills 反复失效的三个卡点1.1 规范存在但 Agent 的读取路径是断的最常见的失败不是规范写得差而是规范从来没被真正读到过。团队把色板、字号阶梯、圆角规则写进一份 Markdown然后在对话开头贴一段“请遵循以下设计规范”后面跟三百行内容。模型确实看了但上下文一长、任务一多这段内容就被压缩、被遗忘或者被后续的工具返回结果挤到边缘。更麻烦的是这种“贴进去”的知识没有版本概念改一次规范要手工同步到每个人的提示词模板里半个月后没人知道线上跑的到底是第几版。UI Skills 想要解决的就是这件事把规范变成文件系统里可以被按需读取的资产而不是一次性灌进上下文的文本。文件有路径、有版本、有归属Agent 需要的时候去读读多少由它判断。这个转变听起来只是形式上的实际效果差得很远。1.2 单次生成像样多次生成不成体系我在一个后台管理系统的项目里做过对照。同一个 Agent同一个需求描述让它连续生成五个列表页。第一版视觉上没问题第二版开始把卡片阴影调深了一档第三版把表头背景换成了浅灰而不是规范里的透明第五版的按钮高度和第一版差了 4px。单看每一屏都能交付放在一起就是“五个人各写各的”。原因是提示词里的约束是软的。模型每生成一次都是一次独立采样软约束在采样过程中会被稀释。要让它稳定约束必须变成可被验证的硬条件——要么是它必须读取的令牌文件要么是它跑完必须通过的校验脚本。这就是为什么我把 UI Skills 的落点放在“文件 脚本”而不是“文档 说明”。1.3 改完看不到结果反馈环是断的这条最容易被忽略。很多接入方式里Agent 生成代码之后就结束了它不知道这段代码渲染出来是什么样。间距写错了、层级塌了、暗色模式下文字糊了它一概不知。人来验收人来提修改意见Agent 再改一轮下来十几分钟。凡是能把“写完能跑起来、跑起来能截图、截图能回看”这条链打通的接入方式收敛速度都会快一个量级。这也是我在三条路线里最看重的一项能力后面实测部分会给出具体耗时对比。2. 三条接入路线的能力边界2.1 路线A项目内文件式 Skill靠目录发现这是最轻的一条路。在项目根目录下建一个约定好的目录把 Skill 描述文件和配套的规范、令牌、模板放进去Agent 启动时扫描目录把每个 Skill 的名称和简短描述加载进来真正需要时再读正文。目录大概长这样.claude/ skills/ ui-design-system/ SKILL.md tokens/ color.json spacing.json typography.json rules/ layout.md states.md templates/ card.tsx table.tsx scripts/ lint-tokens.mjsSKILL.md头部是一小段元信息正文才是详细说明--- name: ui-design-system description: 生成或修改任何界面组件、页面布局、样式时使用。包含色板、间距栅格、字号阶梯、状态规范与组件模板。 ---这条路线的优点很直接零额外服务、零网络依赖、跟着代码仓库走谁 clone 下来谁就有。缺点是能力受限于 Agent 本身的工具集——它能读文件、能跑命令就能用如果它只能对话这套东西就是死文件。2.2 路线B把 UI 资产做成服务通过工具协议暴露第二条路是把设计系统做成一个本地服务通过工具协议MCP 这类把能力暴露出去。Agent 连上来之后看到的不是一堆文件而是若干可调用的工具查询令牌、检索组件、生成脚手架、跑视觉回归。// 伪代码暴露给 Agent 的工具定义 server.tool(get_tokens, { category: color }, async ({ category }) { return await readTokenFile(category); }); server.tool(find_component, { name: card }, async ({ name }) { return await searchComponentIndex(name); });这条路的优势在于封装。团队不需要让每个人都理解令牌文件的组织方式Agent 也不需要知道文件在哪调用工具就行。检索类能力也更强组件多了以后模糊匹配比让模型自己翻目录靠谱。代价是要维护一个服务进程要考虑启动、端口、日志、异常团队协作时多了一层环境依赖。2.3 路线C无头模式嵌进流水线由脚本驱动第三条路完全不面向人对话而是把 Agent 当成一个函数调用。CI 里跑一条命令传入需求描述和目标路径Agent 在无头模式下完成任务、跑校验、输出结果。claude -p 按 .claude/skills/ui-design-system 的规范实现 src/pages/dashboard 的卡片区域完成后运行 npm run lint:tokens \ --allowedTools Read,Write,Edit,Bash \ --output-format json这条路适合批量任务和回归场景一次生成二十个页面或者每次设计令牌变更后重新校验全站。它的短板是调试不直观出问题只能翻日志也缺少人在环里的即时纠偏需求描述写歪了它会一本正经地歪着做完。2.4 三条路的关键维度对照维度文件式 Skill工具协议服务无头模式嵌入启动成本极低建目录即可中需维护服务进程中需配置流水线上下文开销低按需读取中工具描述常驻低单次任务团队共享随仓库走天然共享需统一服务地址需统一脚本与环境调试直观度高能看到读了什么中需看工具调用日志低只能看输出批量能力弱需人触发中可脚本调用强天生批量结果回看依赖 Agent 工具集可封装截图能力需自行接出产物适用场景日常开发、单人提效大团队、组件资产多CI 校验、批量生成这张表不是让你三选一。我实际的用法是 A 打底、B 补检索、C 做回归三者共用同一套令牌和规范文件避免知识分叉。3. Claude Code 在 Skill 链路上的四个机制3.1 描述字段决定触发率正文写得再好也没用Skill 能不能被用上几乎全看description那一行。Agent 启动时只看到名称和描述它要根据这两项判断“当前任务要不要加载这个技能”。我见过太多人把描述写成“UI 设计规范文档”触发率低得可怜——因为这句话没告诉模型什么时候用它。有效的写法是把触发条件写进去涉及哪些动作、哪些文件类型、哪些关键词。比如“生成或修改任何界面组件、页面布局、样式、主题时使用”就比“UI 设计规范”强得多。这件事的收益比优化正文大十倍因为正文再好没被加载就等于不存在。我一般会让描述覆盖三类信号动作生成、修改、重构、对象组件、页面、样式、主题、边界不涉及纯逻辑改动时不用。3.2 文件系统就是上下文读多少由任务决定传统做法是把规范全量塞进提示词几千字常驻占着预算还容易被压缩。文件式 Skill 的逻辑完全不同正文可以写得很长但只有在需要时才被读取。我那份layout.md有四百多行包含栅格、断点、密度模式、留白规则日常改个按钮根本不会读它。这个机制的价值在长任务里尤其明显。一个持续半小时的重构任务如果规范全量常驻中途被压缩几乎是必然的而按需读取的话Agent 在每一步都能重新拿到准确的那一段。代价是它得知道去哪读——所以SKILL.md正文里必须写清楚索引比如“间距规则见 tokens/spacing.json布局规则见 rules/layout.md”把目录结构当成导航用。3.3 工具闭环写完能跑、跑完能看这是我认为 Claude Code 在这件事上最占优的地方。它不只是读文件和写文件还能执行命令、拿到输出、根据输出继续改。生成一个卡片组件之后它可以跑类型检查、跑 lint、跑构建看到报错再回头修。更进一步如果项目里有截图脚本它可以把渲染结果落成图片再读回来。我常用的做法是在scripts/下放一个截图脚本用无头浏览器渲染指定路由并输出 PNG然后在 Skill 正文里写明“改完布局后运行node scripts/shot.mjs /dashboard并检查输出”。这一步加上之后间距错位、文字溢出这类问题在提交前就能被抓到而不是等人来提。3.4 会话记忆与压缩长任务里怎么不丢约束长会话里上下文会被压缩这是所有 Agent 都要面对的现实。压缩策略通常会保留最近的操作和关键结论丢掉中间的细节。对于 UI 任务来说被丢掉的往往是“规范里的某一条”。应对办法有两个。一是把最硬的约束下沉到脚本变成必须通过的检查这样即使模型忘了脚本也会拦下来。二是把关键约束写进项目里的固定文件并让 Skill 正文明确要求“每次修改样式前先读 tokens/color.json”。前者是兜底后者是主动。两条一起用实测在超过二十轮的会话里样式漂移的概率能压到很低。4. 同一个需求的三路实测4.1 先把需求和验收标准钉死为了让对比有意义我用同一个需求跑三条路线在后台系统里实现一个“数据概览卡片”包含标题、副标题、一个主数值、一个环比标签、一个趋势小图占位、一个操作按钮。验收标准列了六条不靠感觉判断圆角使用令牌--radius-lg不出现硬编码数值卡片内边距取 8 的倍数且与表格卡片一致主数值字号取字号阶梯中的display-sm环比标签的正负状态颜色取自语义色令牌不直接写红绿按钮使用组件库已有组件不自造暗色模式下对比度不低于 4.5:1。这六条里1、2、3、4 可以脚本校验5、6 需要人工确认加脚本辅助。4.2 路线A 的实测记录文件式 Skill 的流程最顺我把需求描述和目标目录给它它先读了SKILL.md然后按索引读了tokens/spacing.json和tokens/typography.json接着读了模板templates/card.tsx作为结构参考最后写文件、跑类型检查、跑令牌校验脚本。中途出了一次偏差它一开始把内边距写成了20px令牌校验脚本报错它回头读了间距令牌改成--space-524px后通过。整个过程我干预了零次从下达需求到六条标准全部满足用时约四分钟。这个案例说明一件事校验脚本是这套流程里性价比最高的投入。Agent 不怕犯错怕的是犯了错没人告诉它。脚本就是那个告诉它的人。4.3 路线B 的实测记录工具协议服务版本Agent 先调用find_component找卡片组件拿到组件签名和示例代码再调用get_tokens拿间距和颜色。工具的返回是结构化的比读文件更省 token也更准确。优势体现在组件检索上。项目里有三十多个组件让它自己翻目录容易翻错工具一次调用就定位到了。劣势也暴露了我改了一个令牌的值之后服务没有热更新Agent 拿到的是旧的导致生成结果和实际渲染不一致排查花了七八分钟才发现是缓存问题。另外工具描述本身要占常驻上下文。我挂了九个工具描述加起来一千多字在短任务里这个开销显得有点重。后来精简到五个情况好转。4.4 路线C 的实测记录无头模式跑同一条需求命令执行、生成、校验全部自动完成用时约两分半比路线A快因为没有人机交互的等待。但输出质量上六条标准满足了五条第 6 条暗色模式对比度没达标——它没做暗色模式下的验证因为它不知道要验证。这条路线的问题就在这里需求描述里的隐含要求它不会主动补。要让它补得在 Skill 正文里明确写“暗色模式下必须验证对比度使用scripts/contrast.mjs检查”把隐式知识全部显式化。改完之后重跑六条全过用时三分出头。所以路线C的正确用法不是“省掉人”而是“把人写的判断固化成检查项”然后让它反复跑。4.5 三路结果对照指标路线A 文件式路线B 工具协议路线C 无头首次通过条数5/6脚本纠偏后 6/65/6缓存导致 4/6 后修复5/6补规则后 6/6总耗时约 4 分钟约 7 分钟含排查约 3 分钟人工干预次数010上下文占用低中低可复现性高中依赖服务状态极高结论不是谁最好而是三条路的成本结构完全不同。文件式把成本压在“写规范的功夫”上工具协议把成本压在“维护服务”上无头模式把成本压在“把判断写成检查”上。选哪条看你团队愿意在哪一头投入。5. 五种“Skill 写了但没生效”的排查5.1 描述写成了文档标题触发率极低症状是 Agent 完全不去读那个技能目录直接凭自己的理解生成。原因八成在description上。把“UI 设计系统”改成“生成或修改界面组件、页面布局、样式、主题色时使用包含令牌、栅格与组件模板”同一个任务重跑触发率立刻上来。排查方法很简单在会话里直接问它“你用了哪个技能”看它有没有把名称说出来。说不出来就是没加载跟正文质量无关。5.2 正文太长关键段落被挤到后面我把四百行布局规则全堆在一个文件里结果 Agent 只读了前面一部分就开始动手后面的断点规则压根没看。原因是读取也有成本模型倾向于读够用就停。解决办法是拆分加索引。把文件按主题切成三四个每个不超过一百五十行然后在SKILL.md里写清楚“改布局读 rules/layout.md改状态读 rules/states.md”。模型拿到明确指引按需读取命中率明显提升。5.3 样式覆盖顺序错乱令牌被硬编码吃掉这个坑很隐蔽。Agent 按规范用了令牌变量但组件里已有的行内样式优先级更高视觉上还是错的。它看到代码“符合规范”就通过了实际渲染没变。我的处理是把覆盖检查加进校验脚本扫描目标文件检查是否存在硬编码的颜色和间距值命中就报错并指出行号。// scripts/lint-tokens.mjs 的核心逻辑简化 const HARDCODED_COLOR /#[0-9a-fA-F]{3,8}\b/g; const HARDCODED_SPACE /(?:margin|padding)[^:]*:\s*\dpx/g; for (const file of targets) { const src await readFile(file, utf8); const hits [...src.matchAll(HARDCODED_COLOR), ...src.matchAll(HARDCODED_SPACE)]; if (hits.length) { console.error(${file} 存在硬编码值${hits.map(h h[0]).join(, )}); process.exitCode 1; } }这个脚本只有二十来行但它把“规范”从建议变成了门槛。5.4 组件幻觉引用了不存在的组件Agent 会“记得”某个组件库里有StatCard然后直接import。构建一跑就报错。这类问题在工具协议路线里少很多因为组件检索是调工具拿的不是凭记忆。文件路线要防这个得把可用组件清单放进技能里并约定“引入任何组件前先读 components/index.md”。清单不需要写全量 API写清组件名、路径、一句话用途就够。5.5 无头模式下缺交互验证无头模式容易漏掉交互态hover 颜色、focus 描边、禁用态透明度。这些在静态截图里看不出来。补法是给截图脚本加交互指令在渲染时触发对应状态再截图。await page.hover([data-teststat-card] button); await page.screenshot({ path: shots/card-hover.png });然后把这三张图默认、hover、focus一起交给 Agent 检查。多花十几秒省掉一轮返工。6. 把 UI Skills 做成团队资产的落地做法6.1 目录分层规范、令牌、模板、校验各归各位我在几个项目里最后收敛出来的结构是四层职责不混层内容谁维护变更频率令牌层颜色、间距、字号、圆角、阴影设计低规则层栅格、断点、密度、状态、暗色策略设计 前端中模板层卡片、表格、表单、空态的参考实现前端中校验层令牌扫描、对比度检查、截图对比前端低分层的好处是变更影响面清楚。改令牌只动一层Agent 下次读取自然生效改规则不动模板避免连锁反应。6.2 让“不合规”变成硬失败而不是一句提醒规范只有变成失败才算数。我把校验挂进package.json的脚本里Agent 完成修改后必须跑跑不过就得改。人提交前也跑同一套标准一致。{ scripts: { lint:tokens: node scripts/lint-tokens.mjs, check:contrast: node scripts/contrast.mjs, verify:ui: npm run lint:tokens npm run check:contrast } }这套东西的价值在于它把“资深前端的眼睛”沉淀成了可执行文件。新人接手、Agent 接手标准都不变。6.3 版本与回归截图基线怎么管视觉回归我用最土的办法把关键页面的截图存成基线每次改完重新截做像素对比超过阈值就报出来。基线文件跟着仓库走改动需要人工确认后才更新。这里有个经验阈值别设太死。字体渲染在不同环境下有微小差异阈值太严会天天报假警报多了就没人看了。我一般设 0.3% 的像素差异容忍度实测既能抓住真的布局错位又不会被抗锯齿干扰。6.4 权限边界Agent 能改什么不能改什么这条容易被跳过但很重要。我的约定是令牌文件和规则文件只读Agent 可以读、不可以改组件和页面可以写。原因很简单令牌是设计决策的结果让 Agent 自己调令牌等于让它改设计标准一次两次看不出来累积起来设计系统就散了。落到配置上就是工具白名单只给读和写在指定目录的权限令牌目录排除在外。多花两分钟配置省掉后面无数次“为什么这个颜色和设计稿对不上”的扯皮。最后分享一个我在实际项目里养成的小习惯每次新增一条规范我都会顺手问自己一句“这条能不能写成脚本”。能写成脚本的就不写进文档。文档会被压缩、会被跳过、会被误读脚本不会——它要么过要么不过清清楚楚。这半年下来我们那套 UI Skills 的文档反而越写越薄因为大部分内容都下沉成了可执行的检查剩下的文档只负责解释“为什么这么定”这部分 Agent 不需要每次都读人需要。