Agent Skills 实战:把设计文档(Design)写成 Skill
本篇以 设计文档(Design Doc)为例:技能产出为按团队模板生成或补全的设计说明文档,涵盖设计目标、用户流程、交互与状态、视觉与组件、可访问性及交付物;与 PRD 衔接(PRD 定「做什么」,Design 定「怎么做、长什么样、如何交互」),或对已有设计文档做符合性评审,抄回去即用。
团队写设计文档时,若每人结构不一——有的缺交互状态与异常,有的未对齐设计系统、可访问性未写——评审难聚焦、开发难落地。把设计文档模板写进一条 Agent Skill,助手在你说「写设计文档」「按模板写 Design Doc」「生成设计说明」「审一下这份设计」时就按同一套结构输出,必填节不遗漏、交互与交付物清晰。本篇从团队设计规范到 SKILL.md 结构、可选 reference.md、可选 scripts、触发与输出和团队协作,走完一整套实战。
一、从团队设计文档规范到技能范围
先明确「写什么、怎么写」。设计文档(Design Doc)常见要素可包括:
设计目标与范围:与 PRD 目标对齐、本设计覆盖的功能/模块/端(Web/App/多端)。 用户与关键场景:目标用户、核心使用场景(可与 PRD 一致或细化到页面/步骤)。 信息架构(IA):页面/模块结构、导航层级、内容组织方式。 交互设计:关键流程(主流程、分支、返回)、状态(默认/加载/空/错)、反馈与异常处理。 视觉与组件:与设计系统对齐、关键组件与变体、响应式/多端适配说明。 可访问性(a11y):键盘导航、焦点顺序、屏幕阅读器、对比度与文案要求。 交付物:线框图/高保真链接、标注说明、动效或原型链接。
示例(可据团队裁剪):
技能的目标:助手在用户给出「PRD 摘要或设计目标」或「已有设计文档草稿」时,按上述模板生成可直接编辑、评审的设计文档(Markdown),缺项用占位提示补全;或对已有设计文档做符合性检查(缺节、交互状态不完整、未写可访问性等)并输出必改/建议清单。
二、SKILL.md 结构示例
在 .cursor/skills/design-doc/ 下建 SKILL.md。推荐目录结构:
design-doc/
├── SKILL.md
├── reference.md # 可选,完整设计模板、交互/视觉规范、示例
└── scripts/ # 可选,检查设计文档是否含必选节
└── check-design-sections.sh
示例 SKILL.md 如下:
---
name: design-doc
description: 按团队模板生成或评审设计文档(Design Doc);适用于用户说「写设计文档」「写 Design Doc」「生成设计说明」「按模板写设计」「审一下这份设计」或提及设计文档、Design Doc 时。
---
# 设计文档技能
当用户要求撰写或评审设计文档时,按以下模板与规范生成一篇完整文档,或输出符合性检查结果。
## 执行前
- **输入范围**:用户提供的 PRD 摘要、设计目标、关键场景、已有设计文档草稿或设计稿链接。若用户只说「写设计文档」「写 Design Doc」等未提供任何要点,先询问:功能/模块名称、对应 PRD 或需求、目标用户与核心场景、设计稿是否已有,再生成。
- 确认有至少**设计主题与目标(或 PRD 对应关系)**后,再按下方模板输出;缺项用 `[请补充:xxx]` 占位。
## 文档结构(必填节)
按以下顺序输出,每节必须有内容或占位说明:
1. **设计目标与范围**:与 PRD 目标/需求对齐、本设计覆盖的功能与端(Web/App/多端)。
2. **用户与关键场景**:目标用户、1~3 个核心场景及关键步骤;可列表或简短段落。
3. **信息架构**(若适用):页面/模块结构、导航关系;无则写「单页/无多级导航」或 `[请补充]`。
4. **交互设计**:主流程简述、关键状态(默认/加载/空/错误)、反馈与异常处理;列表或流程图描述。
5. **视觉与组件**:使用的设计系统组件、关键界面元素与变体、响应式/多端说明;可附设计稿链接占位。
6. **可访问性**:键盘导航与焦点顺序、屏幕阅读器考虑、对比度与文案;若无专门要求写「遵循团队 a11y 规范」或 `[请补充]`。
7. **交付物**:线框图/高保真链接、标注说明;无则写 `[请补充设计稿链接]`。
## 文档结构(可选节)
- **设计原则或约束**:与品牌/设计系统一致的原则、技术约束。
- **附录**:术语表、参考设计、变更记录。
## 设计书写规范
- **交互设计**:每个关键界面需说明「默认状态」「加载/空/错误状态」及「用户操作与反馈」,避免只写「点击后跳转」而无异常与边界。
- **组件**:写清组件名称(与设计系统一致)、变体(如按钮 primary/secondary)、使用场景。
- **可访问性**:至少列出焦点顺序与…