技能演进契约生成

技能文档

---
name: skill-contract-generator
title: 技能演进契约生成
category: 开发工具
description: 为技能（Skill）生成演进契约：在 SKILL.md 中增加「技能契约」章节，声明哪些内容保持稳定（通用知识）、哪些可以随项目演化（可变部分），并定义更新规则与知识萃取机制。适用于新技能创建时定义演化规则、存量技能固化更新边界、项目结束后萃取可泛化知识。当用户需要规范技能的更新与维护、定义技能稳定边界时触发。触发词：技能契约、技能治理、技能更新规则、知识萃取、技能维护。
---

# 技能演进契约生成

## 概述

为任意技能的 SKILL.md 增加一个结构化的「技能契约」章节。契约声明技能中哪些部分是稳定的（通用知识）、哪些是可变的（可随项目演化），并定义更新规则与知识萃取机制，指导技能在后续项目使用中的持续演化。

## 适用场景

- 创建新技能时，定义其演化规则
- 为存量技能固化更新边界
- 让技能在团队内可持续维护
- 明确项目结束后应萃取哪些知识

## 技能工作流

### 步骤1：选定目标技能

确认要为哪个技能建立契约：

- 新技能：创建后立即生成契约
- 存量技能：补充式生成契约

向用户确认：「要为哪个技能创建契约？该技能的 SKILL.md 文件在哪里？」

默认假设：当前环境技能目录下的 `<技能名>/SKILL.md`。

### 步骤2：分析技能结构

通读目标技能的 SKILL.md，了解：

- **技能类型**：元技能 vs 通用技能
- **内容结构**：现有章节构成
- **资源目录**：scripts/、references/、assets/ 是否存在
- **复杂度**：简单参考型 vs 复杂工作流型

分析结论决定契约的生成方式。

### 步骤3：界定稳定元素

识别跨项目应保持不变的内容：

**核心工作流步骤：**
- 定义该技能的基础流程
- 关键决策逻辑
- 标准操作规程

**领域知识：**
- 普适的最佳实践
- 技术规范
- 少变的 API/库使用模式

**示例：**
- `git-workflow` 类技能：所有 Git 命令是稳定的
- 项目上下文生成器类技能：四步工作流是稳定的
- 技能分析器类技能：匹配启发式规则是稳定的

### 步骤4：界定可变元素

识别可在项目中演化的内容：

**新增参考资料：**
- 项目中发现的特定模式
- 真实使用案例
- 遇到的边界情况

**改进说明：**
- 根据困惑点澄清的指令
- 更好的示例
- 优化后的决策树

**新增脚本：**
- 实践中被证明有用的辅助工具
- 校验工具
- 自动化脚本

**示例：**
- `git-workflow` 类技能：可在 references/ 中增加项目特定工作流
- 项目日志类技能：可按项目需要增加新条目类型
- 技能分析器类技能：可细化匹配标准

### 步骤5：定义更新规则

规定更新如何进行：

**允许的操作：**
- 向 references/ 添加文件（始终允许）
- 修改 SKILL.md 的指定章节（列出白名单）
- 向 scripts/ 添加脚本（附约束条件）
- 措辞优化（不改变语义）

**禁止的操作：**
- 更改核心工作流结构
- 删除已确立的最佳实践
- 破坏向后兼容

**评审要求：**
- 哪些更改需要人工确认
- 哪些可以自动执行
- 何时应新建技能而非更新存量

### 步骤6：定义知识萃取需求

规定项目结束后萃取什么：

**萃取模式：**
- 反复出现的共性用例
- 高频问题与困惑点
- 可复用的代码片段

**抽象触发条件：**
- 何时把项目特定模式泛化
- 用什么阈值判断已具备通用性
- 如何区分通用内容与项目特定内容

**示例：**
- 前端设计类技能：萃取通用组件模式
- 项目日志类技能：萃取常见日志条目模式
- 领域技能：萃取可复用的业务逻辑

### 步骤7：生成契约章节与契约文件

同时产出两处：SKILL.md 中的精简契约摘要 + references/ 中的详细契约文件。

**A. 创建 references/contract.md（详细规格）：**

```markdown
# 技能契约：[技能名]

> 完整声明哪些内容可演化、哪些必须保持稳定。

## 稳定部分（通用知识）

**核心元素：**
- [列出工作流步骤、领域知识或关键模式]
- [定义该技能身份的内容]

**禁止修改：**
- [必须保持不变的具体章节或内容]

## 可变部分（可演化）

**项目中可更新：**
- [SKILL.md 中可增改的内容]
- [references/ 中可新增的文件]
- [scripts/ 中可添加的脚本]

**更新指引：**
- [如何添加新内容]
- [使用什么格式]
- [何时更新 vs 新建技能]

## 更新规则

**无需评审即可执行：**
- 向现有章节添加新示例
- 添加记录项目模式的参考文件
- 修正错别字或澄清费解表述

**需要评审：**
- 修改核心工作流步骤
- 变更已确立的最佳实践
- 向 SKILL.md 增加新章节

**禁止：**
- 删除既有最佳实践
- 改变技能的根本目的
- 破坏既有用法的兼容性

## 知识萃取

**项目结束后萃取：**
- [多次出现的模式]
- [常见问题或困惑点]
- [可复用的代码或模板]

**萃取时机：**
- [触发条件，如「使用该技能完成 3 个项目后」]
- [判断指标，如「同一模式在 2 个以上项目出现时」]

**萃取方式：**
- 把可泛化的模式加入 references/
- 用真实案例更新 SKILL.md 中的示例
- 为项目特定领域创建新技能
```

**B. 在 SKILL.md 中加入精简摘要（渐进式披露）：**

```markdown
## 技能契约

**稳定部分：** [一句话概括不可变内容]
**可变部分：** [一句话概括可演化内容]
**更新规则：** [一句话概括，或「详见 references/contract.md」]

> 完整契约规格见 references/contract.md
```

### 步骤8：落盘契约与文件

执行两项操作：

**A. 创建 references/contract.md：**
1. 如无 references/ 目录则创建
2. 按步骤7A 的完整模板写入详细契约

**B. 在 SKILL.md 中插入契约摘要：**

**位置：**
- 主内容之后
- 「资源」章节之前（如有）
- 作为倒数第二节

**插入过程：**
1. 读取当前 SKILL.md
2. 找到插入点（资源章节之前或文末）
3. 插入精简的「## 技能契约」章节
4. 写回 SKILL.md

**结果**：技能同时拥有——SKILL.md 中的精简契约（节省上下文）+ references/contract.md 中的详细契约（供深读）。

### 步骤9：确认与归档

向用户展示契约：
- 呈现生成的契约内容
- 解释稳定/可变边界
- 确认更新规则是否合理

询问：
- 「这份契约是否准确反映了该技能的演化规则？」
- 「是否需要增加约束或放宽自由度？」

按反馈修订后确认完成。

## 按技能类型的契约模板

### 模板：参考/指引型技能

提供参考信息的技能（如 git 工作流）：

**稳定部分：**
- 核心参考内容（命令、API、模式）
- 组织结构

**可变部分：**
- 补充示例
- references/ 中的项目特定工作流
- 澄清与技巧

### 模板：工作流型技能

含分步流程的技能（如项目上下文生成器）：

**稳定部分：**
- 工作流步骤及其顺序
- 核心提问清单
- 模板结构

**可变部分：**
- 示例问题
- 模板章节（可增不可删）
- 边界情况的补充指引

### 模板：元技能

作用于其他技能的技能（如技能分析器）：

**稳定部分：**
- 核心算法或启发式规则
- 输入/输出格式
- 集成点

**可变部分：**
- 启发式权重或判定标准
- 边界情况处理
- 补充校验规则

## 最佳实践

### 边界要具体

**好的写法：**
```
可向「最佳实践」章节添加新示例
可在 references/ 中新增记录项目模式的文件
不可修改四步工作流结构
```

**避免模糊：**
```
可按需更新
不要改重要部分
```

### 考虑技能成熟度

- **新技能**：契约更宽松（仍在摸索有效做法）
- **成熟技能**：契约更严格（已验证的模式需要保护）

### 平衡灵活与稳定

- 过僵化：技能无法改进
- 过宽松：技能失去一致性
- 恰当平衡：核心身份保持不变，细节持续演化

使用说明

# 技能演进契约生成

为技能生成演进契约：声明稳定部分与可变部分，定义更新规则与知识萃取机制，让技能在项目中可持续、有边界地演化。

## 使用

```text
为新创建的这个技能生成技能契约
```

```text
这个技能最近被改得有点乱，帮我固化一下更新边界
```

## 工作原理

九步流程：选定目标技能 → 分析结构 → 界定稳定元素 → 界定可变元素 → 定义更新规则 → 定义知识萃取需求 → 生成契约 → 落盘（SKILL.md 精简摘要 + references/contract.md 详细规格）→ 与用户确认。内置参考型/工作流型/元技能三类契约模板。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。