AI Skill 管理框架 — 通用版

# AI Skill 管理框架 — 使用指南

【其中也结合了一些其他大佬的功能，特此说明】

> 一套结构化的 AI 开发辅助技能管理系统。> 将项目中积累的经验、规范、工作流程编目为可复用的 Skill，让 AI 在合适的时机自动加载对应规则。>> 框架版本: v2.0.0

---

## 一、这是什么

当你和 AI 一起开发一个长期迭代的项目时，会不断积累各种经验：

- 踩过的坑（某个 API 的隐藏限制、某种写法会导致崩溃）- 规范化的流程（提交代码前的检查清单、文档更新规则）- 风格约定（美术风格统一、代码命名规范）

这些经验如果只是散落在文档里，AI 不会主动翻阅。但如果把它们结构化为 **Skill**——带触发条件、执行步骤、检查清单的标准化单元——AI 就能在你做相关操作时**自动加载**对应的防护规则。

**Skill 管理框架**就是这套系统的骨架：分类编号、版本化、触发机制、安装部署、CLI 管理工具，全都包含。

---

## 二、核心组成

| 组件 | 文件 | 作用 ||------|------|------|| **注册表** | registry.json | 所有 skill 的结构化元数据（编号、类型、触发词、依赖、启用状态） || **框架规范** | FRAMEWORK.md | Skill 类型、生命周期、编写标准、质量要求的完整定义 || **Schema** | skill.schema.json | 标准化字段约束（确保注册表格式一致） || **管理工具** | manage.sh | CLI 命令行工具，10 个子命令增删搜查 || **安装脚本** | install.sh | 一键把 skill 部署到 ~/.claude/skills/ || **验证脚本** | validate.sh | 检查 SKILL.md 格式是否合规 || **创建模板** | templates/ | 新建 skill 的标准脚手架 |

---

## 三、5 种 Skill 类型

| 类型 | 说明 | 适用场景 ||------|------|---------|| **guard**（防御型） | 防止已知问题复发 | 历史上某种写法导致了 BUG，编为规则自动防护 || **workflow**（流程型） | 规范多步骤工作流 | 开工前读记忆、收工后写记忆、提交前检查文档 || **tool**（工具型） | 提供可执行的检查/生成功能 | 行数检查、重复代码检测、差异对比 || **style**（风格型） | 统一视觉/代码输出标准 | 美术风格规范、代码命名规范 || **reference**（参考型） | 纯知识参考 | API 速查表、设计模式参考 |

### 各类型必需章节

| 章节 | guard | workflow | tool | style | reference ||------|-------|----------|------|-------|-----------|| 触发条件 | 必需 | 必需 | 必需 | 必需 | 必需 || 覆盖问题表 | **必需** | — | — | — | — || 防御规则 | **必需** | — | — | — | — || 执行步骤 | — | **必需** | **必需** | — | — || 风格规范 | — | — | — | **必需** | — || 正确/错误示例 | **必需** | 推荐 | 推荐 | **必需** | 推荐 || 检查清单 | **必需** | **必需** | 推荐 | 推荐 | 推荐 |

---

## 四、3 种触发模式

| 模式 | 说明 | 典型场景 ||------|------|---------|| **auto**（自动） | AI 检测到相关文件修改或上下文匹配时自动加载 | 修改了输入处理文件 → 自动加载输入防护 skill || **manual**（手动） | 用户说出触发词时激活 | 用户说"开工" → 加载记忆读取 skill || **hybrid**（混合） | 两者兼有 | 用户说"编码"或 AI 检测到编码意图 → 加载反思 skill |

### 触发优先级（同时触发多个时）

```1. guard   （防御优先，避免引入问题）2. workflow（流程规范）3. style   （风格约束）4. tool / reference（辅助信息）```

同级别内按编号排序。

### 触发词注册

每个 skill 的触发词在 registry.json 的 `trigger.keywords` 字段中声明：

```json{  "trigger": {    "mode": "manual",    "keywords": ["开工", "开始工作", "继续开发"],    "conditions": ["新会话开始时"],    "files": []  }}```

匹配规则：完全匹配优先 → 包含匹配次之 → 不区分大小写。

---

## 五、三层渐进加载

AI 不会一次性加载所有 skill 的全部内容，而是按需渐进加载，节省上下文 token：

| 层级 | 加载内容 | Token 消耗 | 时机 ||------|---------|-----------|------|| **L1 发现层** | 仅读 YAML frontmatter 的 name + description | 约 50 tokens/skill | AI 启动时扫描全部 skill || **L2 激活层** | 触发条件 + 执行步骤摘要 | 约 500-5000 tokens | 触发词/条件匹配时 || **L3 执行层** | 加载完整 SKILL.md 内容 | 按需 | AI 决定执行此 skill 时 |

这意味着即使注册了 50 个 skill，L1 总消耗也只有约 2500 tokens，不会占满上下文。

---

## 六、生命周期

```创建 ──→ 注册 ──→ 安装 ──→ 运行时 │        │        │        │ ▼        ▼        ▼        ▼编写      写入      复制到    AI 自动SKILL.md  registry  本地     发现并+ 模板    .json     skills/  加载执行```

### 6.1 创建

1. 确定 skill 类型和所属分类2. 从 templates/ 复制对应模板3. 填写 YAML frontmatter（name + description 必填）4. 编写正文内容（按类型必需章节）5. 运行 validate.sh 检查格式

### 6.2 注册

1. 在 registry.json 的 skills 数组中添加条目2. 填写必需字段：code、name、category、type、trigger、enabled3. 声明依赖关系（dependencies）和冲突（conflicts）

### 6.3 安装

```bashbash install.sh```

自动将启用的 skill 复制到 ~/.claude/skills/，禁用的跳过，已安装但被禁用的自动移除。

### 6.4 运行时

AI 启动时 L1 扫描 → 触发条件匹配时 L2 激活 → 执行时 L3 加载完整内容。

---

## 七、SKILL.md 编写规范

### 7.1 YAML Frontmatter（必需）

```yaml---name: skill-name-here          # 英文标识名（kebab-case，与目录名一致）description: |                  # 功能描述（用于 L1 发现层，建议 2-5 行）  一句话功能描述。  触发条件：当 XXX 时自动触发。  Use when: (1) 场景1, (2) 场景2。  MUST trigger when: 强制触发场景。---```

description 编写要求：- 第一行：一句话概括功能- 后续行：触发条件和使用场景- 控制在 50-200 tokens 以内（L1 发现层的预算）

### 7.2 正文结构

```markdown# Skill 名称

> 编号: S?-0??> 版本: x.y.z> 类型: guard / workflow / tool / style / reference

## 触发条件          ← 所有类型必需## 覆盖的问题列表    ← guard 必需## 防御规则 / 执行步骤 / 风格规范  ← 按类型选择## 检查清单          ← guard/workflow 必需，其他推荐## 禁止事项          ← 推荐```

### 7.3 规则示例格式

每条规则必须提供正确和错误两种示例：

```markdown### 规则 N: 规则标题

**背景**: 为什么需要这条规则

**规则**: 用一句话描述

代码示例:  -- 正确写法  ...

  -- 错误写法  ...```

---

## 八、依赖关系管理

### 8.1 声明方式

```json{  "code": "S5-001",  "dependencies": ["S4-001"],  "conflicts": []}```

- **dependencies**：执行本 skill 前必须先加载的 skill- **conflicts**：与本 skill 互斥的 skill（不可同时启用）

### 8.2 依赖规则

1. **禁止循环依赖**：A→B→A 不允许2. **禁用传导警告**：禁用一个 skill 时，依赖它的 skill 显示警告3. **拓扑排序安装**：install.sh 按依赖顺序安装4. **跨分类依赖允许**：如 S5-001 可以依赖 S4-0015. **冲突是双向的**：A 与 B 冲突 = B 与 A 冲突

---

## 九、分类体系

### 9.1 编号规则

- 格式：**S<分类号>-<三位序号>**（如 S1-001、S3-002）- 分类号固定，序号在分类内递增- 新增 skill 使用 `bash manage.sh add <分类> <名称>` 自动分配编号

### 9.2 推荐分类（可自定义）

以下是推荐的分类方式，你可以根据项目实际需要调整：

| ID | 分类名称 | 适合放什么 ||----|---------|-----------|| **S1** | Bug 防御守卫 | 从历史 BUG 中提炼的防御规则 || **S2** | 协同/部署 | 团队协作、CI/CD、部署相关流程 || **S3** | 代码质量 | 复用检测、行数限制、重复代码治理 || **S4** | 文档管理 | 项目记忆、文档去重、提交后检查 || **S5** | 任务流程 | 编码前反思、完成验证、审核流程 || **S6** | 风格规范 | 美术风格、代码风格、输出格式 |

### 9.3 扩展分类

当现有分类不能覆盖新 skill 的领域时：

1. 分配新的分类号（S7、S8...）2. 在 registry.json 的 categories 数组中添加条目3. 创建对应目录4. 更新相关文档

每个分类支持 999 个 skill（S?-001 ~ S?-999）。

---

## 十、管理工具 manage.sh

10 个子命令：

```bash# 进入仓库目录cd <你的 skill-registry 目录>

# === 查看类 ===bash manage.sh list           # 列出全部 skillbash manage.sh list S1        # 只看某个分类bash manage.sh search 关键词   # 按名称/描述/标签/触发词搜索bash manage.sh info S1-001    # 查看单个 skill 详情bash manage.sh stats          # 统计面板

# === 增删类 ===bash manage.sh add S1 my-new-guard    # 新增（自动分配编号、创建目录、更新注册表）bash manage.sh remove S1-009          # 删除（含依赖检查）

# === 开关类 ===bash manage.sh enable S1-009   # 启用bash manage.sh disable S1-009  # 禁用

# === 分析类 ===bash manage.sh deps            # 查看全局依赖图bash manage.sh deps S5-001     # 查看单个 skill 的依赖链bash manage.sh health          # 健康检查（5 项自动检测）```

### 健康检查 5 项

1. **文件存在性** — 注册表中的 skill 是否都有对应目录和 SKILL.md2. **必填字段** — type、trigger、enabled 等 schema 要求的字段是否齐全3. **循环依赖检测** — 依赖图是否存在环4. **状态一致性** — 启用的 skill 所依赖的 skill 是否也启用5. **格式验证** — SKILL.md 是否有 YAML frontmatter

---

## 十一、版本管理

| 层级 | 方式 | 说明 ||------|------|------|| 仓库级 | registry.json version + Git tag | 整体版本号 || Skill 级 | 每条 skill 的 version 字段 | 单个 skill 的语义化版本 || Schema 级 | skill.schema.json $id | 字段结构版本 |

### 版本号规范（SemVer）

| 阶段 | 版本号 | 说明 ||------|--------|------|| 草稿/预留 | 0.x.x | 结构已建但内容不完整 || 正式发布 | 1.x.x | 所有必需章节完成，经实际使用验证 || 成熟 | 2.x.x+ | 经多次迭代优化，覆盖了边缘场景 |

变更类型：- **MAJOR** — 不兼容变更（删除规则、结构重组）- **MINOR** — 新增功能（新增规则/步骤）- **PATCH** — Bug 修复（修正描述/typo）

---

## 十二、快速上手

### 第一步：初始化仓库结构

```skill-registry/├── README.md              ← 总索引├── FRAMEWORK.md           ← 框架规范├── skill.schema.json      ← Schema├── registry.json          ← 注册表├── manage.sh              ← 管理工具├── install.sh             ← 安装脚本├── validate.sh            ← 验证脚本├── CHANGELOG.md           ← 变更日志│├── S1-bug-guards/         ← 分类目录（按需创建）├── S2-xxx/├── S3-xxx/├── ...│└── templates/             ← 创建模板    ├── basic-skill.md     ← 通用模板    └── bug-guard-skill.md ← Bug 防御专用模板```

### 第二步：创建第一个 Skill

```bashbash manage.sh add S1 my-first-guard```

这会自动：- 分配编号 S1-001- 创建目录 S1-bug-guards/S1-001-my-first-guard/- 复制模板到 SKILL.md- 在 registry.json 中添加条目

然后编辑 SKILL.md，填写规则内容。

### 第三步：验证和安装

```bashbash validate.sh       # 检查格式bash manage.sh health  # 健康检查bash install.sh        # 部署到本地```

### 第四步：日常使用

大部分 skill 是自动触发的，你正常提需求即可。AI 会在匹配条件时自动加载对应 skill。

需要手动触发的 skill，说出对应的触发词即可。

---

## 十三、Skill 质量评分

| 维度 | 权重 | 满分标准 ||------|------|---------|| 完整性 | 30% | 所有必需章节齐全 || 可执行性 | 25% | 步骤/规则明确可操作 || 示例质量 | 20% | 正确/错误示例清晰 || 触发精度 | 15% | 触发条件不遗漏不误触 || 文档质量 | 10% | 语言清晰、格式统一 |

### 新建 Skill 质量检查清单

```□ 1. YAML frontmatter 包含 name 和 description□ 2. description 包含触发条件说明□ 3. 正文包含所有类型必需章节□ 4. 每条规则有正确/错误示例□ 5. 检查清单覆盖所有关键操作□ 6. registry.json 已更新□ 7. validate.sh 通过□ 8. 依赖关系正确声明□ 9. 触发词不与其他 skill 严重重叠□ 10. 版本号和日期已更新```

---

## 十四、实践建议

### 什么时候应该创建 Skill

| 场景 | 建议 ||------|------|| 同一个 BUG 反复出现（2 次以上） | 创建 guard 型 skill || 某个流程经常遗漏步骤 | 创建 workflow 型 skill || 团队成员风格不统一 | 创建 style 型 skill || 某个工具/脚本频繁使用 | 创建 tool 型 skill || 某类知识反复查阅 | 创建 reference 型 skill |

### 什么时候不需要 Skill

- 一次性的操作指南 → 写普通文档即可- 通用编程知识 → AI 已经知道- 与项目无关的个人偏好 → 放 CLAUDE.md 即可

### guard 型 Skill 的最佳实践

1. **从实际 BUG 出发**：每条规则都应该对应一个真实发生过的问题2. **写明根因**：不只是"不要这样做"，而是解释"为什么这样做会出问题"3. **提供正反示例**：让 AI 一眼看出正确写法和错误写法的区别4. **保持精炼**：一个 guard skill 建议 5-20 条规则，太多会稀释重点

### 分类设计建议

- 不要一开始就创建太多分类，随项目成长自然增长- 一个分类下 skill 数量建议 2-15 个，太少则分类无意义，太多则难以管理- Bug 防御类（S1）通常是最大的分类，因为项目 BUG 积累最多

---

## 十五、与其他系统的配合

### 与 Bug 经验库配合

```发现 BUG → 修复 → 记录到 Bug 经验库 → 提炼为 guard skill 规则```

Bug 经验库是原始素材，guard skill 是提炼后的防御武器。

### 与项目规则（CLAUDE.md）配合

CLAUDE.md 定义**全局强制规则**（每次都加载），skill 定义**按需加载的规则**（触发时才加载）。

区分标准：- 每次编码都必须遵守的 → 放 CLAUDE.md- 只在特定场景需要的 → 做成 Skill

### 与 Git 提交流程配合

```代码修改完成  → 构建验证  → 行数检查（S3-002 自动触发）  → 文档同步检查（S4-005 自动触发）  → Git 提交```

---

*框架版本: v2.0.0*