设计 Skill 的用法，是把一类 UI 任务的步骤、规范引用和检查方法整理成 SKILL.md，在 Codex 或 Cursor 处理相关页面时调用。先准备真实组件与规范，再写清“读什么、怎样改、如何检查”，最后用新增页面、局部修改和异常状态三种任务测试。它不是换一个模型，也不是把“做得高级”写得更长。
例如团队反复制作表单，每次都要提醒 AI 沿用按钮、保留输入、补失败状态，就适合整理成 Skill。需要读取 Pixso 中的实际图层、组件与变量时，可以通过Pixso MCP 连接设计资产；Skill 负责约定做事方法，连接工具负责提供可访问的对象，两者配合才能把规则落到具体界面。
先分清：这次需求、项目约定和Skill分别放什么
假设要为公司做一张员工报销表单，包含报销类型、发生日期、金额、用途说明、附件和提交操作。公司已经有按钮、输入框、错误提示和页面布局规范。现在的问题不是“AI 能不能画表单”，而是它每次生成的输入框高度、提交反馈和错误位置都不一样。
不要把本次需求和所有长期规则都塞进一个巨型提示词。表单有哪些字段，是本次任务；项目用什么框架、怎样运行测试，是工程约定；如何读取规范、复用组件、覆盖状态并检查页面，才是一套可复用的设计 Skill。
| 信息 | 适合放在哪里 | 报销表单中的例子 |
|---|---|---|
| 这一次要做什么 | 任务描述与相关需求文件 | 新增报销类型，保留现有审批说明 |
| 项目一直遵守什么 | AGENTS.md、项目说明或Cursor Rules | 沿用现有组件目录，不改接口权限逻辑 |
| 一类任务怎样完成 | 设计Skill | 先读组件映射，再实现状态，最后打开页面检查 |
| 真实设计对象是什么 | 设计文件、组件库及授权工具连接 | 主按钮组件、金额输入框、错误样式及变量 |
Codex 的AGENTS.md 说明与 Cursor 的Rules 文档都提供了项目约定的组织方式。Skill 不需要替代这些约定，而应在它们之上处理一种具体任务。已有格式检查器、测试命令能够完成的检查，也无需再用长篇文字模拟一遍。
一个简单判断是：下次换成请假申请页，这条要求还适用吗？“失败后保留已填写内容”通常适用；“默认选中差旅报销”就只属于当前页面。前者可以沉淀，后者不应该污染所有表单。
把“好看、统一”改成能检查的UI要求
设计 Skill 最容易写成形容词集合：“简洁、专业、有层次、符合品牌”。这些话并非错误，但不足以决定 AI 下一步如何做。真正有用的要求要指向对象、动作和结果。
例如，把“按钮风格统一”改成“沿用项目主按钮组件及 primary 变体；表单提交中保持按钮宽度并阻止重复提交；不要在局部页面另写一套主按钮色值”。把“报错友好”改成“字段校验失败时，错误信息靠近对应字段；网络提交失败时保留全部输入，提供重试路径”。
| 抽象要求 | 可执行的改写 | 检查时看什么 |
|---|---|---|
| 金额区域要专业 | 金额标签、输入和单位清楚分离；保留项目已有金额格式与校验逻辑 | 长金额不溢出，不因视觉修改改变数值含义 |
| 页面简洁 | 首次填写只突出字段和提交；审批说明放在相关位置，不新增无关数据卡片 | 用户能否快速找到下一项需要填写的内容 |
| 交互完整 | 覆盖未填写、校验失败、提交中、提交失败与成功结果 | 每个状态是否有明确反馈与继续操作的路径 |
| 适配手机 | 标签和输入不互相挤压；附件名可换行；主要操作不遮挡错误信息 | 窄屏、长文件名与键盘导航是否仍可用 |
不要把每次发现的问题都变成一条永不删除的禁令。例如某次页面卡片过多，并不等于今后所有界面都不能用卡片。应该记录“一个分组是否帮助用户理解或操作”，再给出适合本项目的正例。规则服务任务，不应为了避开模板感而禁止所有常见组件。
规范必须连到真实组件，不能只写“使用主按钮”
同一团队可能有多个叫 Button 的对象：设计库组件、旧项目组件、第三方组件以及某个页面临时写的按钮。Skill 如果只说“使用 Button”，AI 仍要猜哪一个才是正确选择。
可以先准备一份 references/ui-map.md，记录设计组件、代码对象和使用方法的对应关系。下面的路径与变量名是表单项目的写法示例，实际使用时替换为自己仓库中存在的对象。没有找到对应项，就明确标出缺项，先不要让 Agent 创建另一套同名组件。
| 界面对象 | 设计侧确认 | 代码侧确认 | 本页要求 |
|---|---|---|---|
| 提交报销 | 主按钮的默认、禁用与加载状态 | 项目已有按钮组件及loading属性 | 提交中不重复触发，文字长度变化不引起明显跳动 |
| 金额输入 | 输入框、标签、辅助文案与错误样式 | 现有金额输入组件与校验方法 | 复用原有数值处理，不另写金额算法 |
| 附件列表 | 文件名、上传状态、移除操作 | 现有上传组件与状态类型 | 上传失败和表单提交失败分别处理 |
| 表单间距 | 字段组、分区与按钮区的间距规范 | 项目spacing变量或布局组件 | 优先引用已有变量，不到处添加近似像素值 |
Pixso 的设计系统管理提供组件与代码对应关系的配置入口。已经有设计系统时，让 Skill 引用现有规范和映射，比把所有颜色、字号、组件定义抄进一份文件更容易维护。设计系统更新一次，规则仍然可以沿着同一入口读取，而不是多个副本分别过期。
同时约定冲突怎么处理：如果设计稿的按钮状态与代码组件不一致，先列出差异，由团队决定改设计还是改组件；不要悄悄新增一个“差不多”的版本。Skill 可以帮助发现差异，但不应该自行改变团队的业务规则。
一份能开始使用的设计Skill，先写到这个程度
在项目中创建 .agents/skills/ui-form-design/，把主文件命名为 SKILL.md。当前 Codex 与 Cursor 都支持项目级 .agents/skills；Cursor 也支持自己的 .cursor/skills。把团队文件放在项目里，更容易跟随代码一起版本管理。
主文件只负责说明适用任务和执行顺序，组件细节放在参考文件里。下面这份模板可以直接改用，保存前把它引用的 ui-map.md 准备好：
---
name: ui-form-design
description: 按项目现有设计规范实现或检查业务表单，包括组件复用、字段反馈、提交状态和窄屏布局；不用于修改审批政策、金额算法或后端权限。
---
# 业务表单设计与实现
## 开始前
- 阅读本次需求、目标设计链接和 references/ui-map.md。
- 查看项目现有表单、组件与启动说明。
- 确认修改范围；缺少组件映射时列出具体缺项，不猜测。
## 实现顺序
1. 保留已确认字段、业务文案和校验逻辑。
2. 复用已有输入、按钮和反馈组件，不另造同名组件。
3. 补齐本次需要的空值、校验失败、提交中、失败和成功状态。
4. 一轮完成一个明确改动，不顺手改无关页面。
## 检查
- 按项目既有命令运行相关测试。
- 打开页面，检查宽屏、窄屏、长文字和操作失败。
- 检查键盘可达、可见焦点和错误后的继续操作。
- 修改后重新走一遍此前通过的主流程。
## 交付
说明修改文件、实际检查结果、截图和未完成接口。
没有执行的测试明确写未执行，不把预期结果写成已通过。name 要简短且容易识别；description 需要同时说清“什么时候用”和“不负责什么”。不要只写“优秀设计专家”，那样难以判断这次任务是否应该调用它。OpenAI 的Skill 文档说明了这种目录、元数据与按需加载结构。
引用文件可以保持很小。先写真实设计库链接、已有表单页面、组件路径和检查命令的出处，再补常见状态。访问令牌、用户资料和真实报销票据不应进入共享 Skill。它们不是规范的一部分，也没有必要为了演示交给模型。
不要急着给第一版加自动部署脚本。先让指令型 Skill 在两个页面上稳定工作，确有重复的机械动作时再加入脚本。脚本仍需要可用依赖与授权，放进 Skill 目录不会自动获得执行权限。
在Codex和Cursor中调用，注意入口并不完全一样
保存文件后，先在当前工具的技能入口确认它能被发现，再发起一次范围很小的任务。Codex CLI 与 IDE 扩展可以通过 /skills 或 $ 提及技能；Cursor 可以输入 / 查找 Skill，也支持按上下文选用。桌面应用的入口可能有所不同，使用当前界面列出的技能，不要把命令写进聊天却从未确认是否加载。
在 Codex CLI 或 IDE 中，可以这样调用：
$ui-form-design 检查员工报销表单。先读取现有组件与ui-map.md，本轮只补提交失败状态：保留全部字段和附件列表，在提交区显示失败原因与重试操作，不修改金额计算和审批逻辑。完成后打开页面检查，不只返回代码。
在 Cursor 中，从技能选择列表调用 /ui-form-design，再附上同一任务和相关文件即可。详细的发现路径和使用方式可以看Cursor Agent Skills 文档。本地文件可见，不意味着远程或云端任务必然能访问；切换执行环境时，要重新确认项目和 Skill 是否都在该环境中。
使用 Pixso 时，还可以结合官方工具 Skill。官方提供的设计读取、设计编辑、设计转代码等技能，负责帮助 Agent 选择合适工具；你自己的表单 Skill 则规定公司如何组织字段、状态和检查。它们不必互相替代，也不必把官方工具参数完整复制到团队文件里。
安装 Pixso 官方插件时，Codex 与其他 IDE 使用不同仓库，且 Release 需要匹配当前客户端，入口见Pixso MCP Skill 文档。日常只做 UI 规则修改时，不需要反复重装插件；先判断问题来自团队规则、素材读取还是工具连接。
用三条任务试它，比问“你读过了吗”更可靠
Agent 回复“已遵循规范”，只是一个自述。真正的检查要看它修改了什么、使用了哪些对象，以及实际页面有什么变化。员工报销表单可以用以下三条任务试用同一份 Skill：
- 新增一个字段。增加“费用归属项目”，检查标签、间距、输入组件和错误信息是否沿用现有规则；原来的金额和附件逻辑不应一起被重写。
- 改一条长文案。把用途说明改成较长提示，检查窄屏是否自然换行、是否挤压输入区、是否影响键盘顺序。不要以缩小字号到难读来换取一行放下。
- 让提交失败。检查已填金额、用途和附件是否保留，错误是否说明下一步，重试是否会重复提交。演示环境可用明确的测试返回值触发，不要为测试向真实财务系统反复提交。
把结果分成三种：规则没有被调用、调用后内容理解错了、规则本身写得不清楚。第一种查发现路径与作用范围；第二种补具体对象、输入和输出；第三种改规则或补一个正例。不要把三种问题都处理成“再加二十条禁止项”。
例如失败后表单被清空，原规则只有“友好处理错误”，就应改成“提交失败不清空已填字段；重试前保留当前值；成功后再按产品流程处理”。如果规则已经清楚，而实现没有遵守，就让 Agent 指出相关代码和测试证据，再修对应部分，不必重写整份 Skill。
检查也要允许例外。若项目已有原生移动端方案，窄屏规则就不应强制改成桌面表单缩小版；若某字段涉及业务校验，设计 Skill 应读取既有规则，而不是自行推断。
让规则能更新，而不是越积越厚
先用一个 Skill 覆盖一种稳定任务，比把几十份“顶级设计技能”全部装进去更容易管理。表单、数据列表、营销页的目标和检查方法不同，只有当使用频率与差异确实需要时，再拆成独立技能。
团队维护时关注三件事：引用是否仍然有效，重复规则是否互相矛盾，检查是否真的发生。组件库迁移后更新映射；项目改了测试命令，优先更新对应工程说明；两处规则说法相反，就保留一个明确来源，不让 AI 在多个副本之间猜。
规则也应该随实践删减。某个问题已经由组件本身或自动测试稳定解决，就不必继续占据 Skill 主文件。把阅读成本留给需要判断的地方，例如错误后如何恢复、复杂字段如何分组、局部修改怎样保留既有行为。
如果还没有完整的实现流程，可以先按设计师 Vibe Coding 的单页工作流做一次设计、实现与浏览器修改，再从真正重复的动作中提炼 Skill。这样写出来的规则来自工作，而不是从一开始就假设团队需要一套庞大的流程。
好的设计 Skill，不是让每个页面长得一样，而是让每次修改都有可靠的依据。设计规范仍然在设计系统中，页面需求仍然属于具体任务，Skill 把读取、执行和检查连起来。先让一张报销表单经得住新增字段、长内容与失败状态，再把同样的方法用到下一张表单上。
