---
name: skill-maintainer
version: "1.0.0"
category: meta
description: "当需要技能维护时使用：深度扫描所有 SKILL.md，对比模板检测缺失项、过时模式、格式不一致。不要用于单个技能编辑或一次性修复。"
triggers:
  zh: ["skill维护", "更新skills", "检查skills", "修复skills", "技能维护", "批量更新", "skill audit", "refactor skills"]
  en: ["skill maintenance", "update skills", "audit skills", "fix skills", "batch update", "skill audit"]
license: MIT
compatibility: Node.js >= 18
metadata:
  author: "sunhongda20204834@example.com"
  created: "2025-06-16"
  updated: "2026-06-17"
  status: "beta"
---

# 技能维护 / Skill Maintainer

## Changelog / 版本履历

| 日期 | 版本 | 变更摘要 |
|------|------|---------|
| 2026-06-17 | 1.0.1 | Task 8 规范化：修复 YAML 分隔符、描述格式、内容分隔符、双语标头 |
| 2025-06-16 | 1.0.0 | 初始版本：深度扫描、差距检测、用户选择、变更应用、版本追踪 |

## Core Concept / 核心概念

### 🇨🇳
扫描项目下所有 `*/SKILL.md`，与 `docs/_skill-template/SKILL.md` 对比，检测 Frontmatter 缺失、章节缺失、格式不一致、过时内容。生成分类改进建议，由用户选择执行。应用变更时自动更新各 Skill 的 Changelog 和版本号。

### 🇺🇸
Scan all `SKILL.md` under project root, compare against `docs/_skill-template/SKILL.md`, detect missing frontmatter, missing sections, format inconsistencies, stale content. Generate categorized improvement suggestions for user selection. Auto-update changelogs and versions on apply.

***

## Position / 定位

```
docs/_skill-template/SKILL.md（模板）
         +
全部 SKILL.md（目标）
         ↓
  本 Skill（skill-maintainer）
         ↓
   用户选择 → 应用变更 → 更新版本+Changelog → git commit
```

***

## Workflow / 工作流程

### Step 1: Deep Scan / 深度扫描

**中文：** 遍历全部 `*/SKILL.md`，对每个文件检查以下 8 个维度：

| 维度 | 检查项 | 严重度 |
|------|--------|--------|
| Frontmatter 格式 | 是否有 `name/version/category/description{zh,en}/triggers[]` | 🔴 高 |
| 章节完整性 | 是否有 `Core Concept/Workflow/Iron Law/Red Flags` | 🟡 中 |
| 双语覆盖率 | 中文和英文内容是否都有 | 🟡 中 |
| triggers 数量 | 每种语言是否 ≥3 个触发词 | 🟡 中 |
| Changelog | 是否有版本履历表 | 🔵 低 |
| dependencies | 是否声明了依赖的其他 Skill | 🔵 低 |
| config 引用 | 是否声明了所需的配置文件 | 🔵 低 |
| Auto-Review | 是否有自检清单 | 🔵 低 |

**EN:** Scan all `*/SKILL.md`, check 8 dimensions above.

### Step 2: Generate Suggestions / 生成建议

**中文：** 按类别输出改进建议表。每项标注：目标文件、问题描述、建议修改、严重度、预估影响范围。

**EN:** Output categorized improvement suggestion table with: target file, issue, suggestion, severity, estimated impact.

### Step 3: User Selection / 用户选择

**中文：** 列出所有建议，由用户选择「全部执行」「按严重度执行（仅🔴）」「逐个选择」。等待用户确认后再进入 Step 4。

**EN:** Present all suggestions, let user choose "Apply All", "Apply High Only", or "Select Individually". Wait for confirmation before Step 4.

### Step 4: Apply Changes / 应用变更

**中文：** 对用户选中的每条建议，执行对应修改：

- **Frontmatter 缺失** → 追加对应字段（从原名/描述中推导）
- **章节缺失** → 插入模板对应章节（保留已有内容）
- **triggers 不足** → 从描述中提取关键词补充
- **Changelog 缺失** → 创建空白 Changelog 表
- **版本更新** → 本次变更涉及的 Skill，自动递增 patch 版本号（如 1.0.0→1.0.1），在 Changelog 中新增一行

**EN:** For each user-selected suggestion, apply the edit. Auto-bump patch version for modified skills.

### Step 5: Commit Changes / 提交变更

**中文：** 生成变更摘要，列出每个被修改的文件、修改了什么、版本变化。由用户确认后 git commit，使用 `skill-maintainer` 的 git 配置自动 push。

**EN:** Generate change summary. After user confirm, git commit with descriptive message, auto-push.

***

## Iron Law / 核心铁律

### 🇨🇳
1. **先扫描后修改**: 绝不跳过 Step 1-2 直接修改。违规示例：❌ 用户说"更新所有skills"就直接批量改写。合规示例：✅ 先扫描→输出差距报告→用户选择→逐项修改。
2. **保留原有内容**: 补全缺失章节时，不删除已有内容。违规示例：❌ 覆盖用户手写的 Workflow。合规示例：✅ 在已有内容后追加缺失的 Iron Law 章节。
3. **不改变语义**: 自动补充的 trigger 词、描述必须从 Skill 正文中提取，不凭空编造。
4. **版本追踪**: 每次修改必须更新版本号+Changelog。不追踪的修改不可追溯。

### 🇺🇸
1. **Scan before modify**: NEVER skip Steps 1-2.
2. **Preserve existing content**: Append missing sections, don't overwrite.
3. **No semantic drift**: Auto-generated triggers/descriptions derive from content, not fabrication.
4. **Version tracking**: Every modification MUST update version+changelog.

***

## Red Flags / 三层防御

### Layer 1: Input / 输入
- **INPUT-01**: 工作区有未提交变更 → 🟡 WARN → 提示先 commit 或 stash
- **INPUT-02**: docs/_skill-template/SKILL.md 不存在 → 🔴 CRITICAL → 终止，模板是基准

### Layer 2: Execution / 执行
- **EXEC-01**: 用户选择"全部执行"但涉及 >10 个文件 → 🔴 CRITICAL → 分批执行，每批 ≤5 个
- **EXEC-02**: 自动推导的 trigger 词与已有内容冲突 → 🟡 WARN → 跳过，标注

### Layer 3: Output / 输出
- **OUTPUT-01**: 修改后 `git diff` 确认每个文件变更正确 → 输出 diff 摘要
- **OUTPUT-02**: 修改后版本号重复 → 🔴 CRITICAL → 回退，手动确认版本号

**级别标识**: 🔴 CRITICAL → 中断 | 🟡 WARN → 继续+标记 | 🔵 INFO → 记录

***

## Scanning Report Template / 扫描报告模板

```markdown
# Skill Audit Report / 技能审计报告

**Date**: YYYY-MM-DD
**Total Skills Scanned**: N
**Template Version**: X.X.X

## Summary / 总览

| 严重度 | 数量 |
|--------|------|
| 🔴 High | N |
| 🟡 Medium | N |
| 🔵 Low | N |

## Detailed Findings / 详细发现

### 🔴 High Priority

| # | Skill | Issue | Suggestion |
|---|-------|-------|------------|
| 1 | git-workflow | Missing triggers[] array | Add derived triggers from description |

### 🟡 Medium Priority

| # | Skill | Issue | Suggestion |
|---|-------|-------|------------|

### 🔵 Low Priority

| # | Skill | Issue | Suggestion |
|---|-------|-------|------------|

## Version Changes / 版本变更

| Skill | Before | After | Reason |
|-------|--------|-------|--------|
```

***

## Sync Capability / 同步能力

### 🇨🇳
当任何 SKILL.md 文件被创建、删除或修改时，skill-maintainer 能够自动同步元数据到中央注册表和域路由器配置文件，确保系统一致性。

**同步工作流**：
1. **扫描所有 SKILL.md**：遍历项目根目录下所有 SKILL.md 文件
2. **提取元数据**：从每个 SKILL.md 的 Frontmatter 中提取 `name`、`description`、`triggers`、`dependencies`、`category` 等关键信息
3. **对比差异**：将提取的元数据与 `auto/config/skill-map.yaml` 和各域 `dispatch.yaml` 文件进行差异分析
4. **生成更新计划**：基于差异生成具体的更新操作（新增、修改、删除条目）
5. **应用更新**：自动更新目标 YAML 文件，保持格式一致性和注释完整性

**同步验证清单**：
- ✅ 触发词同步：SKILL.md 中的 triggers 与 skill-map.yaml 中的 triggers 一致
- ✅ 能力同步：SKILL.md 描述的能力与 skill-map.yaml 中 capabilities 一致
- ✅ 依赖同步：SKILL.md 声明的 dependencies 与 skill-map.yaml 中 dependencies 一致
- ✅ 调度配置同步：skill-map.yaml 中的 dispatch 配置正确反映技能的执行方式
- ✅ 新技能注册：新创建的 SKILL.md 自动在 skill-map.yaml 中注册
- ✅ 删除技能清理：已删除的 SKILL.md 对应条目从 skill-map.yaml 中移除

### 🇺🇸
When any SKILL.md file is created, deleted, or modified, skill-maintainer can automatically sync metadata to the central registry and domain router config files, ensuring system consistency.

***

## Output / 输出规范

### 🇨🇳
输出格式为 Markdown 格式的审计报告，包含扫描总览、分类发现、版本变更。

### 🇺🇸
Output format is an audit report in Markdown, containing scan overview, categorized findings, version changes.

***

## Auto-Review / 自检清单

| # | 检查项 |
|---|--------|
| 1 | 所有 Skill 是否已扫描 |
| 2 | 用户选择是否已确认 |
| 3 | 修改后每个文件的 Changelog 是否更新 |
| 4 | 版本号是否正确递增 |
| 5 | git diff 是否仅包含预期变更 |
| 6 | git commit message 是否包含变更摘要 |