Docs Authoring Skill

# 添加新 SKILL

> **目标**：创建一个新的 SKILL 并注册到索引中
>
> **完成后**：必须执行 [SYNC_INDEX.md](./SYNC_INDEX.md) 同步索引

---

## 快速步骤

```
1. 确定目录位置
1.5 选择 SKILL 模板（Type A vs Type B）
2. 创建目录和 SKILL.md
3. 同步索引 → [SYNC_INDEX.md](./SYNC_INDEX.md)
4. 验证 → [VALIDATE_SKILL_AND_INDEX.md](./VALIDATE_SKILL_AND_INDEX.md)
```

---

## Step 1: 确定目录位置

| 目录 | 适用范围（Scope） |
|------|----------------|
| `requirements/` | REQUIREMENTS（需求） |
| `design/` | DESIGN（设计） |
| `implementation_planning/` | IMPLEMENTATION_PLANNING（实施规划） |
| `execspec_compile/` | EXECSPEC_COMPILE — Compile ExecSpec（编译 ExecSpec） |
| `execspec_fulfill/` | EXECSPEC_FULFILL — Fulfill ExecSpec（落实 ExecSpec） |
| `common_normal/` | COMMON（全阶段通用：基础原则） |
| `common_advanced/` | COMMON（全阶段通用：高级原则） |
| `special/` | SPECIAL（领域特定：按需启用） |


**选择依据**：
- 只在一个阶段使用 → 放入对应阶段目录
- 多个阶段通用 → 放入 `common_normal/`（基础原则）或 `common_advanced/`（高级原则）
- 领域特定（如 Web/Mobile）→ 放入 `special/`

### SKILL 类别说明（8 个类别）

**单一事实来源（SSOT）**：以 `spec_stage_skill/_INDEX_ALL.md` 为准（不要在本文硬编码数量）。

| 类别 | 位置 | 用途 |
|------|------|------|
| **requirements** | `spec_stage_skill/requirements/` | 需求阶段的质量检查、转换增强 |
| **design** | `spec_stage_skill/design/` | 设计阶段的覆盖检查、一致性验证 |
| **implementation_planning** | `spec_stage_skill/implementation_planning/` | 实施规划阶段的覆盖链路、粒度检查 |
| **EXECSPEC_COMPILE** | `spec_stage_skill/execspec_compile/` | Compile ExecSpec（编译 ExecSpec）支撑（约束/依赖/节奏/环境等） |
| **EXECSPEC_FULFILL** | `spec_stage_skill/execspec_fulfill/` | Fulfill ExecSpec（落实 ExecSpec）支撑（TDD节奏/质量门禁/审查/重构） |
| **common_normal** | `spec_stage_skill/common_normal/` | 通用基础原则（INVEST、KISS、DRY） |
| **common_advanced** | `spec_stage_skill/common_advanced/` | 通用高级原则（SOLID、SoC、YAGNI） |
| **special** | `spec_stage_skill/special/` | 特定技术栈思维模式 |

### common 目录分裂说明

**为什么 common 分裂成两个目录？**

- **common_normal/**：基础原则，适合所有级别（L1/L2/L3）使用
  - `principle-invest` - INVEST 原则
  - `principle-kiss` - KISS 原则
  - `principle-dry` - DRY 原则
  - `document-quality` - 文档质量检查

- **common_advanced/**：高级原则，主要面向 L2/L3 级别
  - `principle-solid` - SOLID 原则
  - `principle-soc` - 关注点分离原则
  - `principle-yagni` - YAGNI 原则

这样的分裂便于：
1. 新用户快速找到基础原则 SKILL
2. 高级开发者快速找到进阶原则 SKILL
3. 工具索引能精准导航

---

## Step 1.5: 选择 SKILL 模板（Type A vs Type B）

**依据**：[STRUCTURE.md Section 2](./_reference/STRUCTURE.md) - Type A/B 结构对比

### 判断标准

| 判断维度 | Type A (Validator) | Type B (Generator) |
|---------|-------------------|-------------------|
| **主要功能** | 检查、验证、审计 | 生成、增强、转换 |
| **命名特征** | check / detect / validator / principle | generator / to / enrich / explain / thinking |
| **输出性质** | 覆盖率报告 + 问题清单 | 新生成的 artifacts 或增强后的 artifacts |
| **数量占比** | 27 个（60%） | 18 个（40%） |

### Type A (Validator) - 8段式结构

**适用场景**：检查清单、质量门禁、合规验证

**标准章节**（8个）：
1. 描述
2. 适用场景
3. 输入
4. 输出
5. 执行策略
6. 价值
7. **验收标准**（必须分 L1/L2/L3）
8. >> 命令（可选）

**真实样本**：
- `examples/real_samples/2_design_vs-coverage-check.md` - 简洁8段式示例
- `examples/real_samples/3_impl_goal-sc-coverage-check.md` - 多级覆盖链示例

### Type B (Generator) - 10段式结构

**适用场景**：内容生成、转换增强、解释分析

**标准章节**（10个）：
1. 描述
2. 适用场景
3. 输入
4. 输出
5. **执行步骤**（Type B 特有，给 AI 的指令）
6. **快速开始**（Type B 特有，给人类的指南）
7. **使用说明**（Type B 特有，详细的输入/输出说明）
8. 价值
9. 质量检查（可选）
10. 限制条件（可选）

**真实样本**：
- `examples/real_samples/1_requirements_us-enrich-context.md` - 完整10段式示例

### 选择建议

```
如果主要功能是【检查/验证/审计】
  → 使用 Type A (Validator)
  → 参考 real_samples/2 或 3
  → 必须包含"验收标准"章节

如果主要功能是【生成/增强/转换】
  → 使用 Type B (Generator)
  → 参考 real_samples/1
  → 必须包含"执行步骤"、"快速开始"、"使用说明"章节
```

### description 写作模式

**Type A (Validator)** - 模式1：What + When + Avoid
```yaml
description: 检查每个US是否有对应的VS，生成覆盖率报告和修复建议。当设计文档创建后、CONSTRAINT验收前使用，避免US→VS覆盖率<100%导致验收失败。
```

**Type B (Generator)** - 模式2：What + Who + When + Help
```yaml
description: 为精炼的User Story增加真实场景描述、用户心理和具体对话，让US对PM/客户更亲切易懂。适合在US初稿完成后、需要向客户展示理解或准备验收时使用，当US格式正确但缺乏场景感时。帮助不熟悉敏捷的PM/BA、需要对外沟通的团队，通过丰富的场景感让需求文档更容易被理解和接受。
```

**📚 完整参考**：[_reference/PATTERN_LIBRARY.md](./_reference/PATTERN_LIBRARY.md)
- Section 二：10 种命名模式（check, validator, to, enrich, generator...）
- Section 三：3 种 description 写作模式（含真实案例）
- Section 四：Type A/B 完整结构模板

---

## Step 2: 创建目录和 SKILL.md

```bash
# 示例（bash）：在 requirements 目录下新增 SKILL
mkdir -p spec_stage_skill/requirements/my-skill/
```

**SKILL.md 模板**：

```yaml
---
name: my-skill-name
description: 简要描述做什么。何时使用此 Skill。
# 可选字段（按需添加）：
# stage: REQUIREMENTS
# level_supported: [L1-STREAMLINED, L2-BALANCED, L3-RIGOROUS]
---

# My Skill Name

## 概述

**能力定位**：
- 功能1
- 功能2

**适用场景**：
- 场景1
- 场景2

## L1-STREAMLINED

### 检查清单
- [ ] 检查项1
- [ ] 检查项2
- [ ] 检查项3
- [ ] 检查项4

### 通过标准
- 通过率 ≥95%（4 项中至少 4 项通过）
- 必过项：检查项1（格式）
```

### 命名规则

| 要求 | 示例 |
|------|------|
| 使用 kebab-case | `my-skill-name` ✓ |
| 小写字母 + 数字 + 连字符 | `draft-create` ✓ |
| 最多 64 字符 | - |
| 禁止：大写、下划线、空格 | `MySkill` ✗, `my_skill` ✗ |

### description 规则

必须包含两部分：
1. **What**：做什么
2. **When**：何时用

```yaml
# 正确 ✓
description: 验证用户故事的 INVEST 合规性。需求定稿前使用。
#            ^^^^^^^^^ What ^^^^^^^^^    ^^^^ When ^^^^

# 错误 ✗ （只有 What，没有 When）
description: 验证需求
```

---

## Step 3: 同步索引

**必须执行**：[SYNC_INDEX.md](./SYNC_INDEX.md)

需要更新的文件：
1. 底层索引：`{category}/_INDEX.md`
2. 上层索引：`_INDEX_STAGE_*.md`
3. 全局索引：`_INDEX_ALL.md`

> 📌 **运行时上下文**：请确认新 SKILL 能在 [SKILL_CONTEXT_CONTRACT.md](./_reference/SKILL_CONTEXT_CONTRACT.md) 定义的 `CURRENT_STAGE/WORKING_DIR/USER_INTENT` 上下文中处理路径和输入。必要时在 SKILL.md 中说明它期望的 WORKING_DIR 或输入格式。

---

## Step 4: 验证

执行 [VALIDATE_SKILL_AND_INDEX.md](./VALIDATE_SKILL_AND_INDEX.md) 检查：
- YAML frontmatter 格式正确
- name/description 存在
- 索引路径正确

---

## 检查清单

提交前确认：

- [ ] 目录名符合 kebab-case
- [ ] 已选择 Type A (Validator) 或 Type B (Generator) 模板
- [ ] Type A 包含"验收标准"章节，Type B 包含"执行步骤"、"快速开始"、"使用说明"章节
- [ ] SKILL.md 存在
- [ ] frontmatter 有 name 和 description
- [ ] description 包含 What + When
- [ ] 至少有 L1 检查清单（4-6 项）
- [ ] 已执行 [SYNC_INDEX.md](./SYNC_INDEX.md)
- [ ] 已执行 [VALIDATE_SKILL_AND_INDEX.md](./VALIDATE_SKILL_AND_INDEX.md)

**🔍 避坑检查**：[_reference/ANTI_PATTERNS.md](./_reference/ANTI_PATTERNS.md) Section 五
- 快速检查清单（命名/description/结构/YAML/LLM友好性 5个维度）
- 如发现问题，查阅相应章节了解修复方法

---

## 详细规范（可选阅读）

- YAML frontmatter 规范：[_reference/YAML_SPEC.md](./_reference/YAML_SPEC.md)
- SKILL.md 正文结构：[_reference/STRUCTURE.md](./_reference/STRUCTURE.md)
- SKILL 构建流程指南：[_reference/SPEC_SKILL_BUILD_GUIDE.md](./_reference/SPEC_SKILL_BUILD_GUIDE.md)
- 提交前质量检查：[_reference/QUALITY_CHECKLIST.md](./_reference/QUALITY_CHECKLIST.md)

---

## AI Coding Agent 命令

```
请帮我创建一个新的 SKILL：
- 名称：story-validation
- 目录：requirements/
- 功能：验证用户故事的 INVEST 合规性
- 需要包含 L1 和 L2 级别

请：
1. 创建目录和 SKILL.md
2. 填写 frontmatter
3. 生成基础检查清单
4. 同步所有相关索引
5. 验证正确性
```