技能演进契约生成器

技能文档

---
name: majiayu000-skill-contract-generator
description: 技能演进契约生成器。为技能生成「技能契约」，界定哪些内容必须保持稳定、哪些可以随项目演进、以及如何沉淀项目知识。当用户创建新技能需要定义演进规则、为现有技能规范更新边界、或在项目结束后沉淀技能知识时触发。触发词：技能契约、技能更新规则、技能演进、技能边界、知识沉淀。
title: 技能演进契约生成器
category: 开发工具
---

# 技能演进契约生成器

## 概述

为任意技能的 SKILL.md 增加「技能契约」章节。契约声明技能中哪些部分是稳定的（通用知识）、哪些是可变的（可在项目中演进），并定义更新规则与知识提取要求，为后续的技能维护与升级提供依据。

## 适用场景

- 创建新技能时，需要预先定义其演进规则
- 为现有技能正式划定更新边界
- 项目实践中发现技能需要迭代，希望规范更新方式
- 澄清项目结束后应沉淀哪些知识

## 技能工作流

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

确认需要生成契约的技能：

- 新技能：创建后立即生成契约
- 现有技能：可事后补充契约

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

默认假设为技能工作区下的 `<skill-name>/SKILL.md`。

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

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

- **技能类型**：元技能（作用于其他技能）还是通用技能
- **内容结构**：现有章节
- **资源目录**：scripts/、references/、assets/ 等
- **复杂度**：简单参考型还是复杂流程型

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

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

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

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

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

**示例：**
- Git 工作流技能：所有 Git 命令均为稳定内容
- 项目上下文生成技能：四步工作流为稳定内容

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

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

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

**改进说明：**
- 根据使用困惑澄清的说明
- 更好的示例
- 优化的决策树

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

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

明确更新应如何进行：

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

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

**审查要求：**
- 哪些变更需要人工确认
- 哪些可以自动执行
- 何时应新建技能而非更新现有技能

### 步骤6：定义知识提取要求

明确项目结束后应沉淀什么：

**提取模式：**
- 反复出现的常见用例
- 高频问题
- 可复用的代码片段

**抽象触发条件：**
- 何时将项目特定模式泛化
- 什么阈值表明具备通用性
- 如何区分通用知识与项目特定知识

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

在 SKILL.md 写入简要契约摘要，并在 references/ 落盘详细契约文件。

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

```markdown
# 技能契约：[skill-name]

> 完整界定可演进与须稳定的内容。

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

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

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

## 可变部分（可演进）

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

**更新准则：**
- [如何添加新内容]
- [使用什么格式]
- [何时更新而非新建技能]

## 更新规则

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

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

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

## 知识提取

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

**提取时机：**
- [触发条件，如「使用该技能完成 3 个项目后」]

**提取方式：**
- 将可泛化的模式加入 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/ 添加记录项目模式的文件
不可修改四步工作流结构
```

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

### 考虑技能成熟度

- **新技能**：契约可宽松（仍在探索有效模式）
- **成熟技能**：契约应严格（已验证的模式需保留）

### 平衡灵活与稳定

- 过于僵化：技能无法改进
- 过于宽松：技能失去一致性
- 合适平衡：核心身份保留，细节持续演进

使用说明

# 技能演进契约生成器

为技能生成「技能契约」：界定稳定内容与可演进内容，定义更新规则与知识沉淀要求。

## 用法示例

```
用户：给我的 bid-writer 技能加一份技能契约
技能：分析 SKILL.md 结构 → 界定稳定/可变边界
     → 生成 references/contract.md 并在 SKILL.md 插入契约摘要
```

## 输出

- `references/contract.md`：详细契约规范（更新规则、知识提取要求）
- SKILL.md 中的「技能契约」简要摘要章节

如何安装此技能？

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