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）、使用场景。
- **可访问性**：至少列出焦点顺序与键盘操作、关键文案的 a11y 要求（如错误提示可读、焦点不丢失）。

## 输出格式

- 输出为完整 **Markdown** 文档，可直接复制到 Confluence/Notion/Figma 说明或仓库。
- 标题层级：一级标题为文档标题，二级标题为上述各节；流程与状态用列表或表格。
- 占位符统一为 `[请补充：xxx]` 或 `[待确认]`。

## 示例输出（节选）

```markdown
# 设计文档：[功能/模块名称]

## 设计目标与范围
- 对齐 PRD：[需求/目标简述]
- 覆盖范围：Web 端 xxx 模块；[请补充多端说明]

## 用户与关键场景
- **目标用户**：[请补充]
- **场景 1**：… 步骤：1）… 2）…
- **场景 2**：[请补充]

## 信息架构
- 页面结构：… 或 单页，无多级导航
- 导航关系：[请补充]

## 交互设计
- **主流程**：… → … → …
- **关键状态**：默认 / 加载中 / 空状态 / 错误态；[请补充各状态说明]
- **异常与边界**：网络失败时…、无权限时…；[请补充]

## 视觉与组件
- 设计系统：沿用 [团队设计系统]；关键组件：Button、Input、Modal…
- 响应式：[请补充断点与适配说明]
- 设计稿：[请补充链接]

## 可访问性
- 键盘：Tab 顺序…、Esc 关闭…
- 焦点：弹窗打开时焦点落入…；[请补充]
- 文案与对比度：遵循 a11y 规范

## 交付物
- 线框图/高保真：[请补充链接]
- 标注：[请补充]
```

若用户提供的是**已有设计文档**并要求「检查是否符合模板」或「评审这份设计」，则输出：符合项 ✓、缺节或缺项列表、交互状态是否完整、是否提及可访问性与交付物；按 **必改 / 建议 / 可选** 分级，并给出修改建议。

可根据团队实际增删「文档结构」与「设计书写规范」；完整模板、交互与视觉规范可放到 reference.md，主文件只写「见 reference.md」。若使用 scripts/，可在 SKILL 的「执行前」中约定：评审已有 .md 时先执行 scripts/check-design-sections.sh <路径>，将脚本输出的缺节列表并入检查结果。

可选 scripts 示例

若希望助手在评审设计文档时先检查是否包含必选节，可在同目录下建 scripts/，例如：

scripts/check-design-sections.sh（检查 .md 是否含必选二级标题，输出缺失节供技能合并到评审结果）：

#!/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 文件路径并要求评审设计文档，执行前可先运行 scripts/check-design-sections.sh <路径>，将脚本输出的缺节按「必改」并入符合性检查结果。」

三、可选 reference.md

若团队有固定设计文档模板、交互/视觉规范或设计系统链接，可在同目录下增加 reference.md（与 SKILL.md 同级），例如：

• 完整设计文档模板（可直接复制首段）。
• 交互设计规范：状态完整（默认/加载/空/错）、反馈与异常、禁止/推荐模式。
• 视觉与组件：设计系统组件列表、命名与变体约定、响应式断点。
• 可访问性：键盘/焦点、WCAG 等级目标、文案与对比度。
• 链接到内部设计系统、Figma 库或设计评审流程。

SKILL.md 里写一句：「完整模板与交互/视觉规范见 reference.md。」助手会在需要时读取。

以下为 reference.md 示例，可按团队实际裁剪：

# 设计文档模板与规范参考

本文件供 design-doc 技能在需要时查阅，与 SKILL.md 中的文档结构一致并展开细节。

---

## 一、完整设计文档模板（复制用）

```markdown
# 设计文档：[功能/模块名称]

## 设计目标与范围
- 对齐 PRD / 需求：
- 覆盖范围：（Web/App/多端）

## 用户与关键场景
- 目标用户：
- 核心场景与步骤：

## 信息架构
- 页面结构 / 导航关系：

## 交互设计
- 主流程：
- 关键状态：默认 / 加载 / 空 / 错误
- 异常与边界：

## 视觉与组件
- 设计系统组件与变体：
- 响应式 / 多端：

## 可访问性
- 键盘与焦点：
- 文案与对比度：

## 交付物
- 线框图 / 高保真 / 标注链接：
```

---

## 二、交互设计规范（示例）

### 状态完整
- 每个可交互区域需说明：**默认**、**悬停/聚焦**、**加载中**、**空状态**、**错误态**（若适用）。
- 列表/表格：空数据时的展示与引导（如「暂无数据，去 xxx」）。

### 禁止 / 推荐
- 禁止：只有「点击后跳转」而无加载态、错误态、无权限态。
- 推荐：网络失败、超时、无权限时给出明确文案与可操作反馈（重试、返回、联系支持）。

---

## 三、视觉与组件

- 组件命名与设计系统一致（如 Button/Primary、Input/WithError）。
- 响应式断点（示例）：移动 < 768px、平板 768～1024、桌面 > 1024；按团队实际填写。

---

## 四、可访问性（占位）

- **键盘**：所有功能可通过键盘完成；焦点顺序符合视觉流。
- **焦点**：弹窗/抽屉打开时焦点落入首个可操作元素；关闭后焦点回退。
- **文案**：错误提示、空状态文案需可被屏幕阅读器正确朗读。
- **等级**：目标 WCAG 2.1 AA；按团队实际填写。

---

## 五、内部链接（占位）

- 设计系统 / 组件库：\[团队内部链接]
- Figma 项目 / 设计评审流程：\[团队内部链接]

四、在 Cursor 里的触发与输出

• 隐式：用户说「写设计文档」「写 Design Doc」「按模板写设计说明」「生成设计文档」「审一下这份设计」「评审这份设计文档」，助手根据 description 匹配到 design-doc 技能，按上述模板输出一篇设计文档或符合性检查结果。
• 显式：用户说「用 design-doc 技能写一份设计文档」或输入 /design-doc（若产品支持）。

输出应为可直接复制到文档系统或仓库的完整 Markdown 设计文档；若用户已提供 PRD 摘要或设计目标，相应节应已填充，缺项用 [请补充：xxx] 标出。若为评审模式，输出为必改/建议/可选清单，每条带位置（章节）与修改建议。

五、团队协作：统一技能与 Review 他人写的 Skill

• 统一技能目录：建议把 design-doc 等团队技能放在项目内 .cursor/skills/，随仓库提交，产品与设计拉代码即有一致模板。
• Review 他人写的 Skill：新技能或改动可走 PR，重点看：description 是否覆盖常见说法（设计文档、Design Doc、设计说明）、文档结构是否与团队共识一致、交互与可访问性要求是否清晰；必要时在对话里实际触发一次做验收。

小结：从团队设计文档规范到 SKILL.md（执行前 + 文档结构 + 设计书写规范 + 输出格式 + 示例）、可选 reference（完整模板、交互/视觉/可访问性规范）、可选 scripts（检查必选节）、触发方式与团队协作，就完成了一条可复用的设计文档技能。把团队规范清单化 → SKILL → reference（+ scripts）→ 触发与协作；本篇与 Agent Skills PRD 篇衔接：PRD 定「做什么」→ Design 定「怎么做、长什么样、如何交互」，兼具「生成草稿」与「符合性评审」两种用法。