Agent-ready Material Generation Skill

Agent-ready Material Generation Skill 帮助设计师把品牌、风格和组件范围等关键决策，转化为人能维护、智能体能理解并复用的设计物料：Figma 设计系统、Markdown 设计契约，或来自同一份规范的两套交付物。

这里的「设计物料」包含设计基础、组件、组合规则和使用契约。你决定设计方向，技能推导细节，并通过结构回读、视觉检查和验证报告说明交付是否满足要求。

一、能力与价值

| 能力 | 交付内容 | 解决的问题 | | --- | --- | --- | | 推导设计基础 | 品牌色、语义色、明暗主题、字体、间距、尺寸、圆角和阴影 | 减少重复配置，让组件共享一致的视觉基础 | | 生成 Figma 组件库 | 变量与样式绑定、组件变体、可编辑文本、实例替换、内容插槽、文档和示例 | 让组件可配置、可组合，便于设计师和智能体复用 | | 生成 Markdown 设计契约 | L0–L7 分层规范，覆盖治理、体验、原则、品牌、基础、组件、交付验证与生命周期 | 为智能体提供选用组件和实现交互的明确依据 | | 支持 AI 产品场景 | 对话消息、附件、输入区、推理过程、工具调用、来源引用、差异展示与交互卡片 | 将 AI 产品特有界面纳入同一套设计规范 | | 对齐两套交付物 | 共享规范摘要、组件映射、差异检查和联合验收报告 | 减少 Figma 与 Markdown 分别生成造成的不一致 | | 利用已有设计资产 | 限定范围的只读采集、证据对账；配套子技能支持组件库审查与规范化 | 保留已有设计决策，并明确冲突和未验证项 |

生成的材料有什么特征，为什么是 Agent-ready？

Agent-ready 的核心是让 Agent 有依据地完成「找到组件 → 理解用途 → 配置属性 → 组合界面 → 检查结果」。 生成材料将这些依据写入组件结构、语义说明和设计契约，减少 Agent 自行猜测设计意图。

| 材料特征 | 具体体现 | 对 Agent 的价值 | | --- | --- | --- | | 可发现 | 统一命名、组件索引、用途描述和关键词 | 按任务定位合适的组件与规则 | | 可理解 | 说明用途、适用与避免场景，以及组件之间的关系 | 判断什么时候使用、何时不适合 | | 可配置 | 明确变体、状态、默认值、合法属性和可编辑文本 | 在允许范围内调整组件，减少无效配置 | | 可组合 | 保留真实组件实例、内容插槽、实例替换和自动布局约束 | 将组件组合为界面，同时保持结构和复用关系 | | 可追溯、可对齐 | 设计值绑定变量与样式；双端交付共享统一规范和映射依据 | 追溯设计值来源，核对 Figma 与 Markdown 是否一致 | | 可验证 | 提供结构审计、视觉检查、重复运行和差异报告，明确未决项 | 根据证据判断结果是否满足约束，并定位需要修复的问题 |

例如，使用按钮时，Agent 可以查到它适合的场景、合法的尺寸与状态、可修改的文案和图标，以及应复用的颜色与布局规则；在交互实现模式下，还需遵循契约中的行为、键盘和焦点约束。

上述特征由所选交付模式及其验收证据确认。生成设计契约不等于已经完成目标应用的代码开发或运行时验证；实现就绪度必须结合目标项目证据单独报告。

二、组件范围

基础组件按三个完整度逐级累加，默认采用标准级；AI 产品特殊包作为扩展包单独列示，可与基础档位组合使用。所有档位均保留完整设计基础；具体属性和变体覆盖以完整度契约为准。

| 档位 / 扩展包 | 组件范围 | 适用场景 | | --- | --- | --- | | 基础级（Core，12 类） | 按钮、输入框、多行输入框、标签页、徽标、卡片、复选框、单选框、开关、轻提示、对话框、下拉菜单 | 建立基础组件闭环 | | 标准级（Normal，22 类） | 基础级全部组件，加选择器、表单字段、面包屑、头像、警告提示、进度条、文字提示、分隔线、表格、空状态 | 常规产品设计系统 | | 完整级（Pro，27 类） | 标准级全部组件，加骨架屏、滑块、日历、日期选择器、分页 | 更完整的产品组件库 | | AI 产品特殊包（11 类） | 富文本内容（Markdown）、文件消息、媒体消息、用户提问、智能体回复、交互界面（A2UI）、对话输入区（ChatBox）、推理过程（Reasoning）、工具调用（ToolCall）、来源卡片（SourceCard）、差异查看器（DiffViewer） | AI 助手、对话产品与智能体应用 |

以上按组件类别计数，不是变体数量。基础组件以组件目录为准，AI 组件以包清单为准；本次实际范围由规范锁定，不因产品类型擅自增删。

三、核心结构

关键设计决策 + 已有证据
          ↓
统一设计规范（system-spec.json）
          ├── Figma：设计基础 → 组件 → 文档与示例 → 实时验收
          └── Markdown：契约中间表示 → 分层规范 → 包验证
                                      ↓
                         同时交付时进行一致性验收

| 模块 | 入口 | 职责 | | --- | --- | --- | | 主技能 | SKILL.md | 识别目标、推导规范、编排 Figma 生成与双端验收 | | 设计契约子技能 | 设计契约生成 | 将设计决策或已验证规范转为 Markdown 契约 | | 组件库审查子技能 | Figma 组件库审查 | 审查或规范化已有库的命名、属性、布局、变量和语义 | | 执行与验证脚本 | scripts/ | 确定性推导、编译、审计、修复和发布打包 | | 契约与资源 | references/、assets/、packages/agent/ | 提供组件规则、展示模板、图片、图标和 AI 组件契约 |

两套交付物从同一份规范投影，不各自重新决定设计值。详细生成流程及约束保存在详细执行规范，按任务模式加载。

四、使用方法

准备环境

1. 从平台下载完整 ZIP 并解压，或使用平台提供的技能安装方式；保留脚本、子技能、契约和资源目录。
2. 在支持技能和官方 Figma MCP 的客户端中加载技能。文件系统安装方法见 README 安装说明。本地验证需要 Python 3.10+ 及 requirements.txt 中的依赖，JavaScript 检查需要 Node.js 18+。
3. 完成官方 Figma 连接与授权，让智能体检查本次任务需要的工具和目标文件权限。仅在平台上传或安装本技能，不会自动获得 Figma MCP 能力。

告诉智能体你的目标

最少说明：交付目标、产品类型、品牌与风格、组件完整度、Figma 文件或本地输出位置。缺失的关键决策由智能体补充询问，其余采用有记录的默认值，无需逐个指定组件尺寸和状态色。

示例一：生成 Figma 设计系统

使用 agent-ready-material-generation-skill，为 Web 协作产品生成标准级设计系统。
品牌主色 #552FEB，现代简洁、舒适密度，支持明暗主题。
只交付 Figma，目标文件：<Figma 文件链接>。
先复用文件中兼容的变量、样式和组件，完成后提供验证报告。

示例二：为 AI 产品同时生成两套物料

使用 agent-ready-material-generation-skill，为 AI 助手生成完整级设计系统，包含 AI 产品特殊包。
品牌主色 #635BFF，支持明暗主题，同时交付 Figma 和 Markdown。
Figma 目标：<文件链接>；本地交付目录：<目录>。
Markdown 供编码智能体实现完整交互组件，目标代码库：<项目路径>。
请验证两套交付物来自同一份规范，并列出未验证项。

示例三：将已有 Figma 库转为设计契约

使用 agent-ready-material-generation-skill，读取组件库：<Figma 文件链接>。
只生成供设计智能体选用和组合组件的 Markdown 契约，不修改 Figma。
输出到：<本地目录>；请列出证据冲突和未验证的映射。

没有 Figma 来源、只生成 Markdown 时，使用包内的 design-system-contract-gen，说明设计决策或提供已验证的 system-spec.json。当前版本仍需通过下述环境检查。支持 $ 调用的客户端可以在技能名前加 $。

五、Figma MCP 能力依赖

本技能依赖官方 Figma MCP 的实际工具能力，不能仅凭「已连接 MCP」判断可用。 先验证连接来源、认证状态及工具列表，再根据任务检查额外能力。官方远程服务地址为 https://mcp.figma.com/mcp。

| 能力层 | 工具 | 在本技能中的用途与要求 | | --- | --- | --- | | 身份与认证 | whoami，或经授权的只读调用 | 验证当前会话已认证；认证成功本身不证明有写入能力 | | 读取设计上下文 | get_metadata、get_variable_defs、get_design_context | 按当前步骤需要辅助读取结构、变量或设计上下文；不能替代完整结构操作 | | 结构读写 | use_figma | 核心必需：读取和操作页面、组件、变体、变量、样式及布局；只读证据模式仅允许检查，不允许修改 | | 视觉验收 | get_screenshot | 核心必需：检查实际渲染结果，结合结构回读验证视觉质量 | | 图片资源上传 | upload_assets | 涉及头像、内容图片或 AI 媒体组件等资源写入时必需；完整含图交付需要此能力 | | 新建文件 | create_new_file | 任务需要新建目标文件时必需；已有合适文件时无需调用 |

按工具职责区分的依据见 Figma 官方工具说明；可用能力仍以当前客户端、账号和目标文件的实际权限为准。

| 交付模式 | Figma 内容操作 | 能力要求 | | --- | --- | --- | | 仅 Figma / Figma 与 Markdown 同时交付 | 按范围读写 | use_figma + get_screenshot；含图片另需 upload_assets，新建文件另需 create_new_file | | 基于已有 Figma 生成 Markdown | 主技能只读采集，契约子技能不访问 Figma 内容 | 同样需通过核心工具检查；不得为取证临时写入组件或示例 | | 无 Figma 来源的纯 Markdown | 不读取、不修改 Figma 设计内容 | 当前产品门禁仍要求已认证的官方连接，以及 use_figma + get_screenshot 可用；这不是 Markdown 渲染本身的技术依赖 |

只有 get_design_context、get_metadata 等只读工具的连接，无法满足当前完整生成流程。网页转设计、截图导入等能力也不能替代本技能要求的变量绑定和原生组件构建。工具缺失时报告具体缺项，不得以静态图层或本地预检代替完成验收。

完整检查流程见环境检查与依赖。Figma 执行还需加载官方 figma-generate-library、figma-use，新建文件时加载 figma-create-new-file；这些由宿主中的官方 Figma 插件或技能提供，不包含在本 ZIP 内。不同宿主的工具命名可不同，需检查实际对应能力。支持技能安装不代表已经验证了 Figma 写入兼容性。

六、给执行智能体的导航

选择任务模式

| 用户目标 | 执行入口与模式 | 必读材料 | | --- | --- | --- | | 新建或扩展 Figma 系统 | 主技能，FIGMA_ONLY | 详细执行规范的全局约束、阶段 0–8 与交付要求 | | 同时交付 Figma 和 Markdown | 主技能，COMBINED | 同上，加阶段 9、设计契约子技能 | | 以已有 Figma 为证据生成 Markdown | 主技能，MARKDOWN_WITH_FIGMA_EVIDENCE | 详细执行规范中的全局约束与只读分支、证据对账规则、设计契约子技能 | | 只根据决策或规范生成 Markdown | 设计契约子技能，MARKDOWN_STANDALONE / MARKDOWN_FROM_SPEC | 设计契约子技能及其模式引用 | | 只审查或规范化已有 Figma 库 | 组件库审查子技能 | 审查子技能及其阶段规则 |

必须遵守的执行顺序

1. 先检查环境。 在收集输入、推导、检查设计或生成前执行共享环境门禁；复用本会话已验证的结果。纯 Markdown 模式不因检查连接而获得设计内容访问授权。
2. 定位完整技能包。 以本 SKILL.md 所在目录作为包根目录；脚本和资源采用绝对路径，不依赖用户当前工作目录。子技能未单独注册时直接加载包内入口。
3. 加载对应规则。 进入主技能生成流程前，读取详细执行规范中的全局约束、所选模式及适用阶段；随后按阶段加载引用文件。摘要和示例不能替代具体契约。
4. 冻结唯一规范。 复用用户已有选择，只追问会影响结果的缺项。推导并验证 system-spec.json；需要冻结时记录原始字节与 SHA-256，两个投影不得擅自改写。
5. 通过统一生成链执行。 Figma 使用 scripts/emit_figma_library.py，调用工具前加载对应官方技能；全部写入顺序执行。图片使用已登记的压缩运行版本，图标保留原始矢量文件；严格核对契约指定的尺寸与摘要，生成时不得再次压缩或替换资源。
6. 完成实际验收。 Figma 必须进行目标文件实时回读、截图检查和重复运行验证；Markdown 必须进行原生包验证及重复渲染；同时交付时再执行联合验收。只通过本地规范预检不能宣布 Figma 已完成。
7. 报告结果与边界。 分别报告文档就绪、实现就绪、验证失败、豁免和未决项；缺少实际证据时不得声明已通过。

本入口负责介绍和路由；具体设计数值、结构、样式、资源、验证规则以详细执行规范和其引用契约为准。保留 figma-design-system-gen.* 等历史机器标识以兼容已有产物。用户的明确请求和宿主权限边界优先。

<a id="deliverables"></a>

七、交付与验收

| 交付类型 | 核心产物 | 验收重点 | | --- | --- | --- | | Figma | 组件库、统一规范、运行清单、生成计划、实时审计和验证报告 | 组件可编辑、变量与样式正确绑定、视觉检查通过、重复运行结果一致 | | Markdown | contract-ir.json、design-system-contract/、contract-manifest.json | 内容与规范一致、结构和语义验证通过、重复渲染结果一致 | | 基于 Figma 的 Markdown | 上述契约产物及 figma-spec-reconciliation.json | 证据可追溯、冲突有记录、Figma 未被修改 | | 同时交付 | 两套产物及 combined-acceptance-report.json | 两侧独立通过，并确认规范摘要和范围内映射一致 |

下游智能体从生成包的 design-system-contract/AGENT.md 进入，再按组件索引读取当前任务需要的规则。完整文件清单与完成条件见详细交付要求。