---
name: dds-to-skill
description: >
  将 DDS（详细设计说明书）/ PRD / 架构文档转换为一套可落地的 Claude Code Agent Skills（Converts DDS/PRD/Architecture docs into production-ready Agent Skills）。
  包含系统级 Skill、模块级 Skills、横切 Skills 的完整生成流程，涵盖设计细节抽取、reference 分层、frontmatter 规范、质量自检。
  触发场景 Trigger: 当用户需要将 DDS 文档转为 Skills / 需要从架构设计文档生成开发指导 Skill / 需要批量创建模块级 Skill 套件。
  关键词 Keywords: DDS, PRD, 架构说明, 设计文档, skill 生成, skill 套件, agent skill, 模块拆分, reference 抽取, 契约, API, 状态机, 事件, Schema。
argument-hint: "<dds-file-path> [--output-dir <skills-output-dir>] [--project-name <name>]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
---

# DDS-to-Skill：从设计文档生成 Agent Skills

本 Skill 指导你将一份 DDS（Detailed Design Specification）或 PRD / 架构说明文档，转换为一套**可落地、含设计细节**的 Claude Code Agent Skills 套件。

> **核心理念**：生成的不是"空洞的工作流提示词"，而是**绑定了 DDS 设计细节**、能指导真实开发/审查的 Skill 套件。

---

## Phase 0：读取与理解 DDS

### 0.1 动态注入读取（必须执行）

```bash
# 动态注入：查看源文档目录上下文
!`ls -la $(dirname "$ARGUMENTS")`

# 动态注入：读取 DDS 正文（至少 3 段，覆盖全文）
!`sed -n '1,150p' "$ARGUMENTS"`
!`sed -n '150,300p' "$ARGUMENTS"`
!`sed -n '300,500p' "$ARGUMENTS"`

# 动态注入：抽取章节标题（构建 TOC）
!`grep -nE '^(#{1,6}\s+|[0-9]+(\.[0-9]+){0,3}\s+|第[一二三四五六七八九十]+章|第[0-9]+章)' "$ARGUMENTS" | head -n 80`
```

### 0.2 设计要素定向扫描（至少执行 3 项）

```bash
# API/接口
!`grep -nE "API|接口|路径|路由|request|response|错误码|error|handler" "$ARGUMENTS" | head -n 60`

# 事件/消息/Topic
!`grep -nE "事件|event|MQTT|topic|outbox|消息|payload|幂等|retry|publish|subscribe" "$ARGUMENTS" | head -n 60`

# 数据库/Schema
!`grep -nE "表|schema|字段|索引|unique|constraint|migration|DDL|PostgreSQL|MySQL|GORM" "$ARGUMENTS" | head -n 60`

# 状态机/流程
!`grep -nE "状态机|state|transition|流转|工单|workflow|回调|补偿|lifecycle" "$ARGUMENTS" | head -n 60`

# 安全/授权
!`grep -nE "RBAC|DAC|鉴权|JWT|claim|授权|TOTP|权限|auth|token|session" "$ARGUMENTS" | head -n 60`

# 模块/服务/依赖
!`grep -nE "模块|module|service|微服务|依赖|dependency|import|gateway" "$ARGUMENTS" | head -n 60`
```

### 0.3 无法读取时的降级

若无法读取文件，**必须停止**，输出"继续所需的最小信息清单"：

1. 系统模块列表（名称 + 职责 + 关键技术）
2. 每个模块的接口/API 列表
3. 事件/Topic 定义
4. 数据库表结构
5. 状态机/流程定义
6. 授权模型
7. 模块间依赖关系

**禁止在缺少源文档的情况下臆造设计细节。**

---

## Phase 1：分析与规划

### 1.1 模块识别

从 DDS 中识别所有业务模块，生成模块清单表：

| 模块名 | 职责概述 | 关键技术 | Skill 类型 |
|--------|---------|---------|-----------|
| *从 DDS 抽取* | *从 DDS 抽取* | *从 DDS 抽取* | 系统级/模块级/横切 |

### 1.2 Skill 三层架构规划

必须生成 3 类 Skills：

**A) 系统级 Skill（1 个）**
- 跨模块一致性、依赖规则、全局变更流程
- 命名：`developing-<system-name>-system`

**B) 模块级 Skills（N 个，每模块 1 个）**
- 高频开发指导：实现步骤 + 依赖影响检查
- 命名：`developing-<module-name>`

**C) 横切 Skills（≥ 3 个）**
- 基于 DDS 内容选择，常见横切关注点：

| 横切主题 | 适用场景 | 参考命名 |
|---------|---------|---------|
| API/事件/Schema 契约 | 有跨模块接口定义 | `designing-contracts` |
| 数据库迁移 | 有 DB Schema 定义 | `managing-db-migrations` |
| 可观测性/审计 | 有日志/监控/审计需求 | `managing-observability` |
| 安全/认证 | 有 RBAC/JWT/授权体系 | `implementing-auth` |
| 前端开发规范 | 有前端架构设计 | `frontend-<framework>` |
| 后端编码规范 | 有后端技术栈规范 | `backend-<framework>` |
| 部署/运维 | 有 K8S/Docker/CI 设计 | `deploying-<target>` |

> 实际横切 Skills 必须根据 DDS 内容动态决定，不可少于 3 个。

### 1.3 Name 候选与确认

为每个 Skill 提供 2~3 个命名候选，从中选择 1 个并说明理由。命名规则：
- 动名词形式（如 `developing-*`、`managing-*`、`implementing-*`）
- 小写字母 + 数字 + 连字符
- ≤ 64 字符
- 包含模块名或领域名

---

## Phase 2：DDS 设计细节抽取

### 2.1 章节提取与 reference 目录构建

> **详细规则见** `reference/dds-extraction-guide.md`

从 DDS 章节标题构建 `reference/` 分层目录：

```
<skill-name>/reference/
├── 01-<section-slug>/
│   ├── apis.md
│   ├── db-schema.md
│   └── events-topics.md
├── 02-<section-slug>/
│   └── state-machine.md
└── 03-<section-slug>/
    └── security-model.md
```

**目录命名规范**：
- 有序前缀 `01-`、`02-`... + slug
- slug：全小写，非字母数字字符替换为 `-`，连续 `-` 合并，≤ 48 字符

### 2.2 六类设计要素抽取（必须覆盖）

每个模块级 Skill 的 reference/ 必须覆盖**至少 3 类**：

| 要素类型 | 抽取内容 | reference 文件名 |
|---------|---------|-----------------|
| **API/接口** | 路径、方法、请求/响应字段、错误码 | `apis.md` |
| **事件/Topic** | 字段、版本、幂等键、重试语义 | `events-topics.md` |
| **DB Schema** | 字段、索引、约束、迁移策略 | `db-schema.md` |
| **状态机/流程** | 状态、转移、守卫条件、回调、补偿 | `state-machine.md` |
| **授权模型** | JWT claims、RBAC/DAC、权限层级 | `security-model.md` |
| **依赖关系** | 跨模块调用链路、协议、集成点 | `dependencies.md` |

### 2.3 reference 条目格式（强制）

每条 reference 必须包含溯源信息：

```markdown
## <设计要素名称>

- **DDS-Section**: <章节标题原文>
- **DDS-Lines**: L120-L168（或近似行号）

### Extract

<结构化内容：表格/列表/代码块>
```

### 2.4 TBD 标注

如果 DDS 中某个设计要素写得不清楚或缺失：
- **必须标注 `[TBD]`**
- 输出"最小补充信息清单"
- **禁止脑补细节**

---

## Phase 3：逐个生成 SKILL.md

### 3.1 SKILL.md 结构模板

> **详细模板见** `reference/skill-templates.md`

每个 SKILL.md 必须包含以下结构：

```markdown
---
name: <skill-name>
description: <单行，< 1024 字符，中英文混合，第三人称，含功能+触发场景+关键词>
argument-hint: "<参数格式说明>"
allowed-tools:
  - Read
  - Write  # 按需
  - Edit   # 按需
  - Glob
  - Grep
  - Bash   # 按需
---

# <Skill 标题>

<一段话概述本 Skill 的用途和适用范围>

## Quick Context
<动态注入命令，至少 2 处 !`command`>

## Plan
### 产物清单
### 决策点

## Verify
<按类别组织的 Checklist，可勾选>

## Execute
<分步骤的可操作指令>

## Pitfalls
<3~8 条与该模块/主题强相关的常见坑，至少 2 条引用 reference>

## Related References
<指向 reference/ 的链接列表，说明何时查阅>
```

### 3.2 Frontmatter 编写规则

> **详细规范见** `reference/frontmatter-spec.md`

**关键要点**：
- `description` **必须单行**，否则 skill 触发会失败
- 必须中英文混合，确保中文和英文查询都能命中
- 必须包含：功能说明 + 触发场景 + 关键词（含模块名）
- `allowed-tools` 遵循最小授权原则

### 3.3 内容编写原则

1. **删除常识**：只保留 DDS 特有设计与可操作步骤
2. **解释 Why**：对重要约束解释原因，不要堆砌 MUST/ALWAYS
3. **可执行动作**：禁止空话（如"检查 API 兼容"），必须写成具体审查动作
4. **设计细节绑定**：Pitfalls 和 Verify 中至少 2 处引用 `reference/` 的具体内容
5. **行数限制**：SKILL.md 主体 < 500 行

**示例 — 空话 vs 可执行动作**：

```
❌ "检查事件一致性"
✅ "在 reference/events-topics.md 找到 topic 列表，对照仓库 grep 出 publish/subscribe 点"

❌ "验证 JWT 安全"
✅ "校验 JWT claims 是否包含 tenant_id/project_id/role（来自 reference/security-model.md）"

❌ "检查 migration 可回滚"
✅ "migration 必须包含 down SQL；verify.sh grep 检查 `-- +migrate Down` 或回滚段落存在"
```

---

## Phase 4：生成 Supporting Files

### 4.1 目录结构

每个 Skill 遵循标准目录模板：

```
<skill-name>/
├── SKILL.md              # 主文件（< 500 行）
├── reference/             # 设计细节（按章节分层）
│   ├── 01-<section>/
│   │   ├── apis.md
│   │   ├── db-schema.md
│   │   └── ...
│   └── 02-<section>/
│       └── ...
├── examples/              # 骨架代码示例
│   └── ...
└── scripts/               # 验证脚本
    └── verify.sh          # 必须提供
```

### 4.2 verify.sh 编写要求

每个 Skill 必须至少包含 1 个 `verify.sh`：

```bash
#!/bin/bash
# verify.sh - <skill-name> Skill 结构与内容验证
set -e

PASS=0; FAIL=0
check() {
  if eval "$2"; then
    echo "✅ PASS: $1"; ((PASS++))
  else
    echo "❌ FAIL: $1"; ((FAIL++))
  fi
}

SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"

# 结构检查
check "SKILL.md 存在" "test -f '$SKILL_DIR/SKILL.md'"
check "reference/ 目录存在" "test -d '$SKILL_DIR/reference'"
check "SKILL.md < 500 行" "[ $(wc -l < '$SKILL_DIR/SKILL.md') -lt 500 ]"

# 内容检查
check "frontmatter 包含 name" "head -20 '$SKILL_DIR/SKILL.md' | grep -q '^name:'"
check "frontmatter 包含 description" "head -20 '$SKILL_DIR/SKILL.md' | grep -q '^description:'"
check "包含 Plan 章节" "grep -q '## Plan' '$SKILL_DIR/SKILL.md'"
check "包含 Verify 章节" "grep -q '## Verify' '$SKILL_DIR/SKILL.md'"
check "包含 Execute 章节" "grep -q '## Execute' '$SKILL_DIR/SKILL.md'"
check "包含 Pitfalls 章节" "grep -q '## Pitfalls' '$SKILL_DIR/SKILL.md'"

# reference 检查
check "reference 有章节子目录" "find '$SKILL_DIR/reference' -maxdepth 1 -type d -name '0*' | grep -q ."
check "reference 文件含 DDS-Section" "grep -rq 'DDS-Section:' '$SKILL_DIR/reference/' 2>/dev/null"

echo ""
echo "=== 结果: $PASS PASS / $FAIL FAIL ==="
[ $FAIL -eq 0 ] && exit 0 || exit 1
```

### 4.3 examples/ 编写要求

- 只放**骨架与关键接口签名**，不放完整实现
- 与模块职责强相关
- 注释说明关键设计决策

---

## Phase 5：全局自检

### 5.1 输出顺序（必须遵守）

1. **Skills 清单表**：系统级 / 模块级 / 横切，含最终 name 与理由
2. **总目录树**：Unix 路径风格
3. **每个 SKILL.md**：完整内容
4. **Supporting files**：按 `文件路径 → 文件内容` 逐个输出
5. **全局自检结果**：逐条 PASS/FAIL + 修复建议

### 5.2 自检 Checklist

按以下维度逐条检查：

**结构完整性**
- [ ] 系统级 Skill 存在（1 个）
- [ ] 模块级 Skills 数量 = 模块数
- [ ] 横切 Skills ≥ 3 个
- [ ] 每个 Skill 都有 SKILL.md + reference/ + scripts/verify.sh

**Frontmatter 规范**
- [ ] description 为单行
- [ ] description < 1024 字符
- [ ] 中英文混合
- [ ] 包含触发场景和关键词
- [ ] allowed-tools 最小授权

**内容质量**
- [ ] SKILL.md < 500 行
- [ ] 包含 Plan/Verify/Execute/Pitfalls 四个章节
- [ ] ≥ 2 处 `!command` 动态注入
- [ ] Pitfalls ≥ 2 条引用 reference
- [ ] 无空话（"检查 XX 一致性"这类无具体动作的描述）

**Reference 质量**
- [ ] 每个模块 Skill 覆盖 ≥ 3 类设计要素
- [ ] reference 有章节分层目录（非扁平）
- [ ] 每条 reference 含 DDS-Section + DDS-Lines 溯源
- [ ] DDS 缺失内容标注 [TBD]
- [ ] 无脑补设计细节

---

## Quick Reference

| 需要了解... | 查阅... |
|------------|--------|
| DDS 抽取的详细方法 | `reference/dds-extraction-guide.md` |
| SKILL.md 模板（系统/模块/横切） | `reference/skill-templates.md` |
| Frontmatter 详细规范 | `reference/frontmatter-spec.md` |
| 质量自检的完整清单 | `reference/quality-checklist.md` |
| 成功案例的目录结构 | `examples/` |
