# DWS Skill 内容框架合同

> 本分支权威合同：`skills/mono` / `skills/multi` 的**内容组织**与 zip 内容树形状。  
> 不做安装/升级行为约定。质检见 [skill-mono-multi-qa.md](skill-mono-multi-qa.md)。  
> 安装、升级与模式迁移见
> [DWS 预制 Skill 安装、升级与模式迁移 RFC](rfc-skill-installation-and-upgrade.md)。

## 1. 两棵内容树

| 树 | 路径 | 角色 |
|---|---|---|
| **mono**（单 skill） | `skills/mono/` | 单一 `SKILL.md` 入口 + `references/products/*` 产品面 + 全局协议 |
| **multi**（多 skill） | `skills/multi/` | 平铺 `dingtalk-*` 产品 skill + 必选 `dingtalk-shared` |

Agent / 安装面选哪棵树由**行为分支**决定；本文件只规定树内合同。

## 2. Multi 目录合同（如何新增一个产品 skill）

新建 `skills/multi/<name>/` 时必须满足：

1. **命名**
   - 产品 skill：`dingtalk-<product>`（小写、连字符）
   - 共享 skill：仅允许 `dingtalk-shared`
2. **根文件**
   - 必有 `SKILL.md`（YAML frontmatter + 正文）
   - `references/` 推荐；无 reference 的 skill（如极简 profile）须在质检 omit 表登记
   - `scripts/` 可选；脚本须被本 skill 树内某 `.md` 引用，或进入 orphan allowlist
3. **Frontmatter 最小集**（产品 / shared）
   - `name`：与目录名一致
   - `description`：非空，含触发意图与边界
   - `metadata.category`：`product` 或 `shared`（允许历史写法把 `cli_version` 放在 frontmatter 顶层）
   - `metadata.requires.bins`：含 `dws`
4. **契约块**
   - 产品 skill 推荐内嵌 `<!-- DWS_RUNTIME_CONTRACT_START -->…END -->` **或** 明确 PREREQUISITE 指向 `dingtalk-shared`
   - `dingtalk-shared` 承载跨产品路由与全局协议落点
5. **与 mono 映射**
   - 每个 mono `references/products/<stem>`（文件或目录）必须在
     `skills/content-qa/mono-multi-coverage.yaml` 有 `coverage` 或 `omit_coverage` 行

### 2.1 推荐骨架

```text
skills/multi/dingtalk-example/
├── SKILL.md
├── references/
│   ├── example.md          # 主产品面
│   └── …                   # 子章节 / 意图表
└── scripts/                # 可选；须被 md 引用
    └── example_helper.py
```

## 3. Mono 目录合同（质检对照基准）

```text
skills/mono/
├── SKILL.md
├── references/
│   ├── products/           # 覆盖质检主源
│   ├── error-codes.md      # 全局协议示例
│   ├── error-codes.md
│   └── …
└── scripts/
```

- `references/products/` 下每个顶层 stem（`.md` 去后缀或子目录名）计入覆盖索引。
- 同 stem 的 `.md` + 子目录视为同一产品面（如 `doc.md` + `doc/`）。

## 4. 共享内容（`dingtalk-shared`）

| 职责 | 落点 |
|---|---|
| 跨产品路由 / 工作流 | `references/routing.md`、`workflow-routing.md`、`intent-guide.md` |
| 运行时最小契约长文 | `references/runtime-contract.md`（受 context-budget 约束） |
| 全局协议（确认门禁 / Schema 教学等） | `references/`；见质检基线 |
| 与 mono 全局文同名迁移 | `error-codes`、`url-patterns`、`capability-limits`、`channel-login`、`global-reference`、`recipes/`（`conventions.md`、`meta.md`、`lite-catalog.md`） |

产品专属规则（如 AI 表格 `field-rules`）允许下沉到对应 `dingtalk-*`，须在覆盖表注明。

## 5. Zip 内容布局合同（形状，非安装默认）

发布物 `dws-skills.zip`（及 embed 同源）内容树形状：

| Zip 路径 | 含义 |
|---|---|
| `<root>/` | mono 内容副本（兼容旧面） |
| `<root>/mono/` | 与 `skills/mono/` 同构 |
| `<root>/multi/` | 与 `skills/multi/` 同构 |

质检可断言源树形状；**不**断言安装器默认解压哪棵。

## 6. 变更流程

1. 改 / 增内容 → 更新 `skills/content-qa/mono-multi-coverage.yaml`（coverage 或 omit）  
2. 跑 `make skill-mono-multi-content`（该独立门禁不包含在默认 `make policy` 中）
3. 失败则修内容或更新 reviewed omit（disposition + 原因），**禁止**用安装默认值绕过