---
name: "skill-version-registry"
version: "1.0.0"
origin: "captured"
generation: 0
parent_skill_ids: []
status: "stable"
description: "Skill 版本注册表。为所有 Skill 建立版本 DAG、演进族谱、内容快照和回滚能力。借鉴 OpenSpace SkillStore 的版本管理（lineage_parents + content_snapshot + content_diff）机制，在文件系统层面实现。"
trigger_phases: ["closure"]
applicable_agents: ["Copilot Orchestrator", "Copilot Architect", "Copilot Drift Check"]
priority: 10
---

# Skill Version Registry — Skill 版本注册表

> **来源**：OpenSpace `SkillStore`（1495 行）的 `skill_records` + `skill_lineage_parents` 表，实现版本 DAG、快照与回滚。
> **实现方式**：中心化注册表文件 + 每个 Skill 目录下的 `.versions/` 快照子目录。

## 何时触发

| 触发条件 | 说明 |
|---|---|
| Skill 创建时 | 注册新条目，generation=0 |
| Skill 演进时（FIX/DERIVED/CAPTURED） | 更新版本号、记录父子关系、保存快照 |
| Orchestrator Quick Command `/skill-lineage` | 查看指定 Skill 的演进族谱 |
| Orchestrator Quick Command `/rollback-skill` | 回滚 Skill 到指定版本 |
| Drift Check 校验时 | 验证注册表与实际文件一致性 |

## 谁来调用

| Agent | 职责 |
|---|---|
| **Copilot Orchestrator** | 管理注册表更新、触发回滚 |
| **Copilot Architect** | 评估 Skill 体系版本健康度 |
| **Copilot Drift Check** | 校验注册表与文件系统一致性 |
| **skill-evolution-protocol** | 每次演进后自动更新注册表 |

---

## §1 Skill 元数据标准

### 1.1 SKILL.md Frontmatter 规范

每个 Skill 的 SKILL.md 文件头部必须包含以下 YAML frontmatter：

```yaml
---
name: "skill-name"                    # Skill 标识（目录名）
version: "1.0.0"                      # 语义化版本号（semver）
origin: "imported | fixed | derived | captured"  # 创建方式
generation: 0                          # 演进代数（0 = 原始版本）
parent_skill_ids: []                   # 父 Skill 列表（演进来源）
status: "stable | trial | deprecated"  # 当前状态
description: "..."                     # 一句话描述
trigger_phases: ["architecture"]       # 适用的 Orchestrator 阶段
applicable_agents: ["Copilot Architect"]  # 适用的 Agent 列表
priority: 10                           # 同阶段多 Skill 时的加载优先级（数值越小越先）
---
```

**字段说明**：

| 字段 | 类型 | 含义 | 规则 |
|---|---|---|---|
| `name` | string | Skill 标识 | 必须与目录名一致 |
| `version` | semver | 版本号 | FIX → patch +1，DERIVED → minor +1，重大重构 → major +1 |
| `origin` | enum | 创建方式 | `imported`=手工创建/外部导入，`fixed`=修复演进，`derived`=派生增强，`captured`=模式捕获 |
| `generation` | int | 演进代数 | 初始=0，每次演进 +1 |
| `parent_skill_ids` | string[] | 父 Skill | FIX=[self前版本]，DERIVED=[源Skill]，CAPTURED=[] |
| `status` | enum | 生命周期状态 | `trial`=演进后待验证，`stable`=经验证确认，`deprecated`=已废弃 |
| `trigger_phases` | string[] | 适用阶段 | `all` / `design-review` / `architecture` / `planning` / `implementation` / `review` / `validation` / `closure` |
| `applicable_agents` | string[] | 适用 Agent | Agent 全名列表，Orchestrator 据此精准路由 Skill |
| `priority` | int | 加载优先级 | 1=最高，同阶段多 Skill 按此排序，数值越小越先加载 |

### 1.2 版本号规则

| 演进类型 | 版本变化 | 示例 |
|---|---|---|
| FIX（原地修复） | PATCH +1 | 1.0.0 → 1.0.1 |
| DERIVED（派生增强） | MINOR +1 | 1.0.1 → 1.1.0 |
| 重大结构重构 | MAJOR +1 | 1.1.0 → 2.0.0 |
| CAPTURED（新 Skill） | 1.0.0 | — |

### 1.3 生命周期状态机

```
                    ┌─────────┐
    CAPTURED ──────▶│  trial  │
                    └────┬────┘
                         │ 3+ 次有效使用
                         ▼
                    ┌─────────┐
    IMPORTED ──────▶│  stable │◀─── FIX/DERIVED 验证通过
                    └────┬────┘
                         │ FIX/DERIVED 演进
                         ▼
                    ┌─────────┐
                    │  trial  │─── 验证失败 → rollback
                    └─────────┘
                         
    stable ────────▶ deprecated（手动废弃 或 合并到其他 Skill）
```

---

## §2 中心化注册表

### 2.1 注册表文件

**文件路径**：`.github/skills/SKILL-REGISTRY.md`

```markdown
# Skill Registry — 版本注册表

## 最后更新: {ISO timestamp}
## 活跃 Skill 数: {N}
## 总版本数: {N}

## 活跃版本汇总

| Skill ID | Version | Origin | Gen | Status | Parents | Last Modified | Health |
|---|---|---|---|---|---|---|---|
| agent-execution-governance | 1.0.0 | imported | 0 | stable | — | 2026-04-17 | 🟢 |
| agent-hook-lifecycle | 1.0.0 | imported | 0 | stable | — | 2026-04-17 | 🟢 |
| constraint-first-protocol | 1.0.0 | imported | 0 | stable | — | 2026-04-16 | 🟢 |
| cross-doc-consistency-check | 1.0.0 | imported | 0 | stable | — | 2026-04-17 | 🟢 |
| design-doc-completeness-check | 1.0.0 | imported | 0 | stable | — | 2026-04-17 | 🟢 |
| design-doc-to-page-coverage-check | 1.0.0 | imported | 0 | stable | — | 2026-04-16 | 🟢 |
| fk-field-detection | 1.0.0 | imported | 0 | stable | — | 2026-04-16 | 🟢 |
| industrial-form-field-grouping | 1.0.0 | imported | 0 | stable | — | 2026-04-16 | 🟢 |
| industrial-page-standard | 1.0.0 | imported | 0 | stable | — | 2026-04-16 | 🟢 |
| model-component-coverage-check | 1.0.0 | imported | 0 | stable | — | 2026-04-16 | 🟢 |
| physical-data-model-review | 1.0.0 | imported | 0 | stable | — | 2026-04-16 | 🟢 |
| slice-parallel-safety | 1.0.0 | imported | 0 | stable | — | 2026-04-17 | 🟢 |
| test-pattern-registry | 1.0.0 | imported | 0 | stable | — | 2026-04-16 | 🟢 |
| skill-effectiveness-tracker | 1.0.0 | captured | 0 | stable | — | 2026-04-17 | 🟢 |
| structured-execution-recording | 1.0.0 | captured | 0 | stable | — | 2026-04-17 | 🟢 |
| post-execution-analysis | 1.0.0 | captured | 0 | stable | — | 2026-04-17 | 🟢 |
| skill-version-registry | 1.0.0 | captured | 0 | stable | — | 2026-04-17 | 🟢 |
| skill-evolution-protocol | 1.0.0 | captured | 0 | stable | — | 2026-04-17 | 🟢 |
| skill-safety-scanner | 1.0.0 | captured | 0 | stable | — | 2026-04-17 | 🟢 |

## 废弃版本

| Skill ID | Version | Deprecated Date | Reason | Successor |
|---|---|---|---|---|
| — | — | — | — | — |

## 演进族谱索引

> 按最新版本的 generation 降序排列。初始版本（generation=0）不列出。

| Skill ID | Current Gen | Lineage Chain |
|---|---|---|
| — | — | — |
```

### 2.2 注册表更新规则

| 事件 | 更新操作 |
|---|---|
| 新 Skill 创建 | 添加一行到「活跃版本汇总」 |
| FIX 演进 | 更新该 Skill 的 Version/Gen/Last Modified + 记录快照 |
| DERIVED 演进 | 新增一行（新 Skill）+ 在「演进族谱索引」记录父子关系 |
| CAPTURED 捕获 | 新增一行 + status=trial |
| 废弃 | 从「活跃版本汇总」移到「废弃版本」 |
| 回滚 | 恢复旧版本、更新 Version/Gen |

---

## §3 版本快照

### 3.1 快照存储

每个 Skill 目录下维护 `.versions/` 子目录存放历史快照：

```
.github/skills/{skill-name}/
  ├── SKILL.md              # 当前活跃版本
  └── .versions/
      ├── v1.0.0.md         # 初始版本快照
      ├── v1.0.1.md         # FIX 后快照
      └── v1.0.1.diff.md    # FIX 变更差异
```

### 3.2 快照协议

| 步骤 | 动作 |
|---|---|
| 1. 演进前 | 复制当前 `SKILL.md` 到 `.versions/v{current}.md` |
| 2. 记录差异 | 生成 `.versions/v{new}.diff.md`（变更摘要 + 关键 diff） |
| 3. 应用演进 | 更新 `SKILL.md`（内容 + frontmatter 版本号） |
| 4. 更新注册表 | 同步更新 `SKILL-REGISTRY.md` |

### 3.3 差异文件格式

```markdown
# Diff — {skill-name} v{old} → v{new}

## 演进类型: FIX / DERIVED / CAPTURED
## 演进日期: {ISO timestamp}
## 触发来源: {health report / execution analysis / manual}
## 审批者: {user who approved}

## 变更摘要
{1-3 句描述变更内容}

## 关键变更
- Section §{N}: {what changed and why}
- Section §{N}: {what changed and why}

## 指标变化预期
- applied_rate: {before} → 预期 {after}
- effective_rate: {before} → 预期 {after}
```

---

## §4 回滚协议

### 4.1 触发条件

| 条件 | 触发方式 |
|---|---|
| 演进后 3 次使用内 effective_rate 下降 | `skill-effectiveness-tracker` 健康报告标记 |
| 用户手动请求 | Orchestrator `/rollback-skill {skill-name}` |
| 安全扫描失败 | `skill-safety-scanner` 标记 BLOCK |

### 4.2 回滚流程

```
1. 用户确认回滚目标版本
2. 从 .versions/v{target}.md 恢复内容到 SKILL.md
3. 更新 SKILL.md frontmatter（版本号回退、标记 rollback-from）
4. 更新 SKILL-REGISTRY.md（版本信息同步）
5. 将被回滚的版本标记到「废弃版本」
6. 重置该 Skill 在 skill-effectiveness-tracker 中的计数器
```

### 4.3 回滚约束

| 约束 | 说明 |
|---|---|
| 不可跨 major 版本回滚 | 结构性重构不可逆 |
| 回滚需用户确认 | 自动触发仅给出建议，不执行 |
| 回滚后记录 | 在差异文件中记录回滚原因和指标数据 |

---

## §5 族谱可视化

Orchestrator `/skill-lineage {skill-name}` 输出 Mermaid 族谱图：

```mermaid
graph TD
    A["constraint-first-protocol v1.0.0<br/>imported, gen=0"] --> B["constraint-first-protocol v1.0.1<br/>fixed, gen=1"]
    B --> C["constraint-first-protocol v1.1.0<br/>derived, gen=2"]
    A --> D["constraint-first-protocol-lite v1.0.0<br/>derived, gen=1"]
    
    style A fill:#4CAF50
    style B fill:#2196F3
    style C fill:#FF9800
    style D fill:#FF9800
```

节点颜色约定：
- 🟢 绿色：imported（手工创建）
- 🔵 蓝色：fixed（修复演进）
- 🟠 橙色：derived（派生增强）
- 🟣 紫色：captured（模式捕获）
- ⚫ 灰色：deprecated（已废弃）

---

## §6 一致性校验

### 6.1 Drift Check 集成

Drift Check Agent 可执行注册表一致性校验：

| 检查项 | 说明 |
|---|---|
| 文件 vs 注册表 | `.github/skills/*/SKILL.md` 的 frontmatter 与注册表条目一致 |
| 目录 vs 注册表 | 注册表中每个条目对应的 Skill 目录存在 |
| 快照完整性 | 非 v1.0.0 的 Skill 在 `.versions/` 中有对应快照 |
| 状态一致性 | deprecated Skill 不在活跃版本中 |

### 6.2 自动修复

| 不一致 | 修复方式 |
|---|---|
| Skill 存在但未注册 | 自动添加到注册表（status=stable, origin=imported） |
| 注册表有条目但 Skill 目录不存在 | 标记为 MISSING，报告给 Orchestrator |
| frontmatter 与注册表版本不一致 | 以 frontmatter 为权威，更新注册表 |

---

## §7 与其他 Skill 的集成关系

| 关联 Skill | 集成方式 |
|---|---|
| `skill-evolution-protocol` | 每次演进自动更新注册表 + 创建快照 |
| `skill-effectiveness-tracker` | 按版本维度聚合指标 |
| `skill-safety-scanner` | 演进后版本触发安全扫描 |
| `post-execution-analysis` | 分析结果引用 Skill 版本信息 |
| Drift Check | 校验注册表与文件系统一致性 |

---

## §8 变更记录

| 日期 | 版本 | 变更 |
|---|---|---|
| 2026-04-17 | 1.0.0 | 初始版本：元数据标准、注册表文件、快照协议、回滚协议、族谱可视化、一致性校验 |