用Agent Skill统一团队设计文档，告别格式混乱
团队里写设计文档，每个人一个写法。有人写得细，交互状态、异常情况都写到了。有人只写了个大概，设计系统没对齐，可访问性也没提。评审的时候大家不知道看什么，开发拿到手也不知道怎么做。
把设计文档的模板写进一条Agent Skill就能解决。你只要跟助手说“写设计文档”“按模板写Design Doc”“生成设计说明”或者“审一下这份设计”，它就按同一套结构输出。该写的节不会漏，交互和交付物也写得清楚。
这篇文章从团队设计规范到SKILL.md怎么写，再到怎么用、怎么团队协作，从头到尾说一遍。
一、先定好设计文档要写什么
要让AI按模板写，首先得明确模板长什么样。一份设计文档通常包括下面这些内容：
设计目标与范围：跟PRD目标对齐，说清楚这次设计覆盖什么功能、什么端（Web、App还是多端）
用户与关键场景：谁用、在什么情况下用、核心操作步骤是什么
信息架构：页面和模块怎么组织、导航怎么走、内容怎么放
交互设计：主要流程、分支怎么走、怎么返回、各种状态（默认、加载、空数据、报错）怎么处理
视觉与组件：用什么组件、跟设计系统对不对得上、不同屏幕尺寸怎么适配
可访问性：键盘能不能操作、焦点怎么走、屏幕阅读器能不能读、对比度够不够
交付物：线框图或高保真链接、标注说明在哪
每家公司可以根据自己情况增删。有的项必须写，有的建议写，有的可选。定下来之后，这就是AI生成和检查的依据。
二、SKILL.md怎么写
在.cursor/skills/design-doc/目录下建SKILL.md文件。目录结构大概这样：
design-doc/
├── SKILL.md
├── reference.md
└── scripts/
└── check-design-sections.shSKILL.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）、使用场景。
- 可访问性：至少列出焦点顺序与键盘操作、关键文案的 a11y 要求（如错误提示可读、焦点不丢失）。
## 输出格式
- 输出为完整 Markdown 文档，可直接复制到 Confluence/Notion/Figma 说明或仓库。
- 标题层级：一级标题为文档标题，二级标题为上述各节；流程与状态用列表或表格。
- 占位符统一为 [请补充：xxx] 或 [待确认]。
## 示例输出（节选）
```markdown
# 设计文档：[功能/模块名称]
## 设计目标与范围
- 对齐 PRD：[需求/目标简述]
- 覆盖范围：Web 端 xxx 模块；[请补充多端说明]
## 用户与关键场景
- 目标用户：[请补充]
- 场景 1：… 步骤：1）… 2）…
- 场景 2：[请补充]
## 信息架构
- 页面结构：… 或 单页，无多级导航
- 导航关系：[请补充]
## 交互设计
- 主流程：… → … → …
- 关键状态：默认 / 加载中 / 空状态 / 错误态；[请补充各状态说明]
- 异常与边界：网络失败时…、无权限时…；[请补充]
## 视觉与组件
- 设计系统：沿用 [团队设计系统]；关键组件：Button、Input、Modal…
- 响应式：[请补充断点与适配说明]
- 设计稿：[请补充链接]
## 可访问性
- 键盘：Tab 顺序…、Esc 关闭…
- 焦点：弹窗打开时焦点落入…；[请补充]
- 文案与对比度：遵循 a11y 规范
## 交付物
- 线框图/高保真：[请补充链接]
- 标注：[请补充]若用户提供的是已有设计文档并要求检查是否符合模板或评审这份设计，则输出：符合项 ✓、缺节或缺项列表、交互状态是否完整、是否提及可访问性与交付物；按必改/建议/可选分级，并给出修改建议。
可选reference.md
如果团队有完整的设计文档模板、交互规范、视觉规范，可以在同目录下新建reference.md。SKILL.md里只需要写一句“完整模板与交互/视觉规范见reference.md”，助手需要时会自己读。
reference.md的内容可以是完整模板、交互设计规范（状态要全、禁止和推荐的做法）、视觉组件规范（命名、断点）、可访问性要求（键盘、焦点、文案、WCAG等级）、内部链接（设计系统、Figma项目）。
可选scripts脚本
如果想在评审时自动检查文档有没有缺必选节，可以建一个scripts/check-design-sections.sh脚本。内容如下：
#!/usr/bin/env bash
# 用法: ./scripts/check-design-sections.sh <design.md 路径>
# 输出缺失的必选节，供 design-doc 技能并入符合性检查。
FILE="${1:-}"
if [ -z "$FILE" ] || [ ! -f "$FILE" ]; then
echo "Usage: $0 <path-to-design.md>"
exit 1
fi
echo "=== 设计文档必选节检查 ==="
for section in 设计目标与范围 用户与关键场景 交互设计 视觉与组件 可访问性 交付物; do
if grep -qE "^## *$section" "$FILE" 2>/dev/null; then
echo "✓ $section"
else
echo "✗ 缺失: $section"
fi
done在SKILL.md的评审模式里，可以写“若用户提供的是.md文件路径并要求评审，先运行scripts/check-design-sections.sh，把输出的缺节按必改并入检查结果”。
五、在Cursor里怎么触发
隐式触发：用户说“写设计文档”“写Design Doc”“按模板写设计说明”“生成设计文档”“审一下这份设计”“评审这份设计文档”，助手根据description自动匹配到design-doc技能，按模板输出。
显式触发：用户说“用design-doc技能写一份设计文档”或者输入/design-doc。
输出应该是完整的Markdown设计文档，能直接复制到Confluence、Notion或者代码仓库里。用户提供了PRD摘要或设计目标，相应节就填上具体内容，缺的用[请补充：xxx]标出来。如果是评审模式，输出必改、建议、可选三个级别的清单，每条带位置和修改建议。
六、团队怎么协作
把design-doc这类技能放在项目的.cursor/skills/目录下，随仓库一起提交。产品和设计同事拉代码就有一样的模板，不会出现各写各的的情况。
新技能或者改动要走PR（拉取请求）评审。重点看几件事：description是不是覆盖了常见说法（设计文档、Design Doc、设计说明），文档结构跟团队共识是不是一致，交互和可访问性要求清不清楚。最好在对话里实际触发一次试试，验收完再合进去。
小结
从定团队规范，到写SKILL.md（执行前检查、文档结构、书写规范、输出格式、示例），再加reference.md存完整模板和规范，加scripts做自动检查，最后说清楚怎么触发和协作。这一套走下来，团队写设计文档就能统一了。
这和Agent Skills PRD那篇文章的思路是衔接的：PRD定做什么，Design定怎么做、长什么样、怎么交互。这个技能既能生成草稿，也能做符合性检查，两种用法都实用。
本文内容仅供个人学习、研究或参考使用，不构成任何形式的决策建议、专业指导或法律依据。未经授权，禁止任何单位或个人以商业售卖、虚假宣传、侵权传播等非学习研究目的使用本文内容。如需分享或转载，请保留原文来源信息，不得篡改、删减内容或侵犯相关权益。感谢您的理解与支持！
