# SKILL.md 模板库

本文档包含系统级 Skill、模块级 Skill、横切 Skill 的 SKILL.md 模板，供 DDS-to-Skill 转换时参照。

---

## 1. 系统级 Skill 模板

```markdown
---
name: developing-<system>-system
description: >
  指导 <系统名> 系统级开发决策与跨模块一致性（Guides system-level development for <system>）。
  包含：架构总览、模块注册、依赖规则、全局变更流程、版本兼容策略、技术栈规范。
  触发场景 Trigger: 新增模块 / 跨模块变更 / 全局架构决策 / 技术栈选型。
  关键词 Keywords: <system>, system, architecture, 架构, 模块, 依赖, 兼容, cross-module。
argument-hint: "<module-name|change-type> - 指定涉及的模块名或变更类型"
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---

# Developing <System> System

<一段话描述系统整体架构、技术栈、模块组成>

## Quick Context

```bash
# 动态注入：查看系统模块结构
!`ls -la <project-root>/`

# 动态注入：搜索模块间依赖
!`grep -rnE "import|module|service" <project-root>/ | head -30`
```

## Architecture Overview

<ASCII 架构图或层次说明>

## Module Registry

| 模块 | 职责 | 技术 | Skill |
|------|------|------|-------|
| ... | ... | ... | `developing-<module>` |

## Plan

### 产物清单
- [ ] 确定变更涉及的模块列表
- [ ] 确认是否涉及跨模块通信
- [ ] 确认是否涉及契约变更
- [ ] 确认是否需要数据库迁移

### 决策点
1. 变更是否影响多个模块？
2. 是否需要版本兼容处理？
3. 是否需要全局配置变更？

## Verify

- [ ] 模块间依赖无循环
- [ ] 共享契约版本一致
- [ ] 全局配置项完整
- [ ] 技术栈版本对齐

## Execute

### 添加新模块
1. 在项目根目录创建模块目录...
2. 注册到路由/网关...
3. 更新模块依赖图...

### 跨模块变更
1. 列出所有受影响模块...
2. 按依赖顺序逐个修改...
3. 运行集成测试...

## Pitfalls

1. **循环依赖**: 模块间禁止直接 import，必须通过共享接口定义
2. **版本不一致**: 修改共享结构需同步更新所有消费方
3. ...

## Related References

- [模块依赖关系](reference/dependencies.md)
- [技术栈规范](reference/tech-stack.md)
```

---

## 2. 模块级 Skill 模板

```markdown
---
name: developing-<module>
description: >
  指导 <module> 模块的开发（Guides development of <module> module）。
  包含：<模块职责概述>、API 实现、数据库操作、状态管理、安全校验。
  触发场景 Trigger: 开发/修改 <module> 相关功能 / <模块特定场景>。
  关键词 Keywords: <module>, <技术关键词>, <业务关键词>。
argument-hint: "<action> <target> - e.g., 'create handler', 'add api', 'update schema'"
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
---

# Developing <Module>

<一段话描述模块职责、技术栈、在系统中的位置>

## Quick Context

```bash
# 动态注入：查看模块结构
!`find . -name "*.go" -path "*/<module>/*" | head -20`

# 动态注入：查看现有接口
!`grep -rn "func.*Handler\|func.*Service" ./<module>/ | head -20`
```

## Plan

### 产物清单
- [ ] <根据 DDS 列出具体产物>

### 决策点
1. <从 DDS 抽取的关键决策>
2. ...

## Verify

### <验证类别 1>
- [ ] <具体检查项，引用 reference>

### <验证类别 2>
- [ ] <具体检查项>

## Execute

### 1. <步骤标题>
```bash
# 具体操作命令
```

### 2. <步骤标题>
```go
// 关键代码骨架
```

## Pitfalls

1. **<坑名>**: <描述>（参考 `reference/<file>.md`）
2. ...（至少 3 条，至少 2 条引用 reference）

## Related References

- [API 定义](reference/01-<section>/apis.md)
- [数据库 Schema](reference/02-<section>/db-schema.md)
```

---

## 3. 横切 Skill 模板

```markdown
---
name: <crosscut-skill-name>
description: >
  <横切关注点>的统一规范与实现指导（Guides <crosscut concern> across all modules）。
  包含：<具体内容列表>。
  触发场景 Trigger: <触发场景列表>。
  关键词 Keywords: <关键词列表>。
argument-hint: "<module-name|file-path> - 指定要应用规范的模块或文件"
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
---

# <横切 Skill 标题>

<描述这个横切关注点在系统中的重要性和适用范围>

## Quick Context

```bash
# 动态注入
!`<扫描所有模块中与该横切主题相关的文件>`
```

## Plan

### 产物清单
- [ ] <横切维度的产物>

### 决策点
1. <跨模块的统一决策>
2. ...

## Verify

- [ ] <跨模块一致性检查>
- [ ] <规范合规检查>
- [ ] ...

## Execute

### 全局规范
<适用于所有模块的规则>

### 模块适配
<各模块的特殊处理>

## Pitfalls

1. **<跨模块一致性问题>**: <描述>
2. ...

## Related References

- [全局规范定义](reference/<global-spec>.md)
```

---

## 4. 模板使用注意事项

### 4.1 必须自定义的部分

- `<尖括号>` 中的所有占位符
- Plan 的产物清单和决策点必须来自 DDS
- Verify 的检查项必须与模块设计细节对应
- Pitfalls 必须与模块/主题强相关，不可用通用建议填充

### 4.2 禁止照搬模板

模板是结构参考，不是内容来源。以下行为将导致自检 FAIL：
- 产物清单中出现模板占位符
- Pitfalls 与模块无关（如：在前端 Skill 中出现数据库 Pitfall）
- Verify 中没有引用任何 reference

### 4.3 按 DDS 内容增减

- 如果 DDS 中没有状态机，模块 Skill 可以不包含状态机相关 Verify
- 如果 DDS 中有额外的关注点（如性能优化、缓存策略），应增加对应章节
- 横切 Skill 的数量和主题必须由 DDS 内容决定
