# Skill Refiner

> 通过复盘反思或专家输出对比，发现并提炼思维/写作/设计型 skill 的改进方向。 适用于分析问题、写高质量笔记等产出质量无客观指标，需要靠推演和专家判断来评估的 skill。 当用户要求审查、改进、更新或复盘某个 skill，或提供了专家输出用于与 AI 输出对比，或对某次 skill 执行的质量给出了具体反馈时，使用本 skill。

- Skill: `functoreality/skill-refiner` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add functoreality/skill-refiner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/functoreality/skill-refiner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: functoreality (https://skillmd.com/u/functoreality)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/functoreality/skill-refiner

---


# Skill Refiner

## 概述

本 skill 用于改进**思维/写作/设计型 skill**——那些产出质量无法用客观指标衡量、需要靠推演和专家判断来评估的 skill。
不适用于可用指标或成功/失败信号自动评估的执行型 skill（部署、代码生成等）。

核心命题：当"什么是好"本身也需要逐步发现时，如何系统化地改进一个 skill？

### 目标 skill 的特征

- 产出是文本文档或分析结果，质量是主观的、审美的
- 没有标准答案或客观评估指标
- 判断产出好坏需要推演使用场景（"用户读到这份产出后会怎么想？能否受益？"）
- 很多时候，改进方向不是修正"错误"，而是发现"还可以有更好的分析方式"

### 辅助文件

- `references/quality-lenses.md`：质量维度透镜的详细说明。在归因阶段需要从不同角度审视差异时查阅。
- 目标 skill 目录下的 `learnings.md`：该 skill 的工作记忆，记录尚未处理的原始观察。仅在阶段四出现可升级类弱观测时按 §4.4 交叉验证读取，不在复盘开始时读取。见下文"learnings.md 机制"。

---

## 三种工作模式

### 模式 A：专家对比分析

用户同时提供了 AI 输出和专家输出（或用户自己修改后的版本）。

不只比较输出形式的差异，而是追问：专家在写出这些内容时，脑中经过了什么样的思维过程，而 AI 没有？

差异可能体现在多个方面，但不限于以下角度——你看到的任何差异都值得探究：
- **预判差异**：专家做了 AI 没做的预判（如预判读者会在什么场景下查阅这份产出）
- **取舍差异**：专家在某个节点做了 AI 没做的取舍（如选择深入 A 而放弃 B，背后的考量是什么）
- **框架差异**：专家用了 AI 没用到的组织框架（如换了一个概念维度来归类信息）
- **你发现的任何其他差异**，只要追溯到思维层面的区别，都可能指向 skill 的改进方向

**差异分析的粒度要求**：在进行专家对比时，不能仅按行比较。
一行的修改中可能包含多个独立改动（换词、调序、增删限定语、拆句、调整层级结构，等等），
按行分析会将其笼统归为一个差异点，遗漏大量信息。
必须将差异拆解为**原子改动**——每个原子改动对应文本的一个独立变化维度，无法再分解为更小的独立操作。
在此基础上对每个原子改动分别归因。

### 模式 B：执行复盘反思

AI 刚用某个 skill 完成了一次任务，用户要求复盘。

回顾执行过程，寻找任何值得改进的信号。
以下是一些常见的入手角度，但不要局限于此——任何你觉得可能意味着 skill 应该调整的地方都值得提出：
- **困惑点**：执行过程中哪些地方感到不确定、拿不准？（如果 skill 指令更明确，是否可以消除这种不确定？）
- **经验点**：哪些做法 skill 没写、是你这次自己想出来的，它效果好、值得固化为 skill 规则？
- **约束问题**：skill 中哪些要求在执行中感觉不适用、过度限制，或需要重新考虑？
- **你自己发现的任何其他改进信号**。

### 模式 C：用户反馈分析

用户直接指出 skill 产出的某个具体问题（如"这里跳步了""这部分组织不够好"）。

用户的反馈通常是结果导向的（"这里不对"），需要将其翻译为思维导向的（"skill 缺少了什么思维步骤导致 AI 会犯这个错"）。

---

## 分析流程

### 阶段零：模式识别

根据用户提供的内容自动判断模式（有专家文件且有 AI 输出 → A，只说"复盘一下"且无专家文件 → B，用户指出具体问题 → C）。如无法确定，向用户确认。

### 阶段一：收集证据

根据模式收集以下内容中的相关部分：
- AI 使用目标 skill 后的产出
- 专家产出（模式 A）
- 用户反馈（模式 A/C）
- AI 自身对执行过程的回顾（模式 B）

### 阶段二：发现模式——思路归因

这是本 skill 最核心的方法论。对每个"做得好"或"有问题"的点，**不满足于表面形式，追溯到底层思维模式**。

#### 差异标注粒度

在进入归因之前，必须先确保差异标注的粒度足够细。
常见失败模式：逐行比较两个版本，将一整行的差异笼统标记为"这一行改了"。
但一行中可能包含多个独立改动，每个改动背后可能对应完全不同的思维模式。

**要求**：
- 将差异拆解为**原子改动**——每个原子改动对应文本的一个独立变化维度，无法再分解为更小的独立操作
  - 例如：替换一个词、增删一个短语、调整语序、改变层级关系等
  - "替换"类改动需复核：若新旧内容语义差异大（非局部措辞调整），判断是否为"删除旧内容 + 新增新内容"两个独立改动，而非单次替换（见示例二）
- 每个原子改动标注三要素：编号、改动描述、归因
  - 编号用分层式（如 1b = 第一行第二个改动）
  - 改动描述标注操作类型（如 [新增] [删除] [替换] [调整] 等）再附具体改动
  - 归因复杂时可另起行或缩进展开，不必压缩进一行
- 拆解完成后做完整性核对：对照 old/new 全文逐处检查，确认每个可见差异都被某个原子改动覆盖，无遗漏
- 聚类（如需）只能在逐原子改动归因全部完成后进行，作为对已归因项的整理
  - 大类下若存在明显不同的子目的，应分小类，每小类列出包含的改动编号，避免漏记异质点

**示例一：基本粒度**

> 原文：* 与 AOT-POT（Adaptive Operator Transformation，AISClit9）形成对照
> 专家改：* （AI 评）与 AOT-POT 均冻结现有网络、补充新模块以应对未见算子，但方法略有区别

❌ 按行标注——信息丢失，无法归因：
- 整句改为"（AI 评）与 AOT-POT 均冻结现有网络..."

✅ 原子改动标注——每个点可独立归因：
- ① 新增 "（AI 评）"（标注来源，区分笔记作者判断与原文内容）
- ② 删除 "Adaptive Operator Transformation"（删除冗余信息，全称展开用户可自行查阅）
- ③ 删除 "AISClit9"（删除冗余信息，信源位置用户可自行查阅）
- ④ "形成对照" → "均冻结现有网络、补充新模块以应对未见算子，但方法略有区别"
  （"形成对照"空泛，应直接陈述对照的具体结论、概括异同，让读者直接获得信息）

各改动背后的思维模式各自独立：
① 关乎读者意识（谁在说话），②③ 关乎压缩质量（哪些展开说明/引用可省），
④ 关乎推理深度（不止标注关系，而是提炼关系的实质内容）。

**示例二：常见陷阱——同一处的删与增是两个独立改动**

> 原文：* 关键设计：闭式算子，零可训参数
> 专家改：* $F$ 形式：预设变换，零可训参数

❌ 错误标注——将删和增并为一个"改成"：
- ① "关键设计：闭式算子" → "$F$ 形式：预设变换"

✅ 正确标注——拆为两个独立原子改动：
- ① 删除 "关键设计"（该词本身无含义，仅起占位作用）
- ② 新增 "$F$ 形式"（为后续讨论提供明确指代对象）
- ③ "闭式" → "预设"（术语解耦，确保脱离原论文语境仍可理解）
- ④ "算子" → "变换"（术语修正，判断原论文用词"算子"脱离语境有歧义，换更精确表述）

改动 ① 和 ② 虽然在同一位置，但对应两个完全不同的思维考量（"什么该删" vs "什么该加"），不能简并为一个"改成"的改动。

#### 归因的层次

| 层次 | 示例 | 判断标准 |
|---|---|---|
| 输出层 | "AI 没写这一段内容" | 不够——这是症状，不是原因 |
| 规则层 | "skill 没说要写这段" | 勉强——但止于此会让改动变成打补丁 |
| 思维层 | "AI 缺少一个预判步骤：写完一段后停下来问'读者读到这里会有什么疑问'——这正是专家自然在做的事" | 到位——这个发现可以直接指导 skill 设计 |

**追问方法**：对每个差异点反复问"为什么专家会写出这个而 AI 没有？专家脑中经过了什么 AI 没有的思维步骤？"

**警惕套用现成理由**：归因基于证据追问，不套用现成理由（如"压缩""更清晰""避免冗余"）为改动辩护。
检验：能否用一句话把归因教给另一个 AI，让它复现专家的改动，且不误伤其他正常的内容？若不能，说明归因流于表面或编造了理由。
例：删除一段流程，真实原因可能是"两处训练 loss 相同只写一遍"（同一性去重），而非笼统的"不记流程"；后者会引导其他 AI 同步删除另一处正常内容。
尤其警惕目标 skill 自身价值观关键词（如 note-writing 的"压缩"）——在目标 skill 语境下"天然正确"，最易被当作归因而不追问依据。专家改动常有独立于 skill 价值观的具体考量（如"加→&"是消歧而非压缩）。

**注意**：在原子改动标注的基础上，还需要注意一个原子改动可能包含多个独立考量。
例如，"改了表述"这个标注项背后可能同时考虑了"措辞正式化"和"避免绝对化"。
逐考量分别归因，不要笼统归为一条。
若多个可能归因无法判定是否都成立/哪个成立，分别列出供用户选择，与「归因不确定时须确认」配合使用。

**验证**：假设把归因出的思维模式用一句话教给另一个 AI，它能否在类似场景下达到接近专家的表现？如果不够，说明归因还不够深。

#### 既有规则诊断：不要默认专家修正应追加为新规则

当 AI 的错误可追溯到目标 skill 中已有的具体要求时，先检查该要求本身，
而非直接把专家修正写成补丁式的新规则。

对每个相关的既有要求，回答：

1. AI 是否确实因该要求而做出了当前行为？引用对应原文说明因果链。
2. 专家修正否定的是该要求的目标，还是只否定它在当前情境中的适用？
3. 该要求属于以下哪一种情况？
  - **缺少适用范围**：原则仍成立，但缺少触发条件、排除条件或判断依据。
  - **过度具体**：一个场景化动作被写成普遍要求，应上提为更一般的判断原则，
    并把旧要求说明为该原则的典型特例。
  - **可能不合理**：其目标、推理或取舍本身值得推翻或替换。

不要用“再加一条相反规则”掩盖既有规则的问题。这样会留下互相冲突的指令，
使下一次执行仍依赖模型自行猜测何时该遵循哪一条。

若无法判断属于哪一种，或存在多个合理的上提原则，明确告知用户：
相关既有规则、AI 受其影响的方式、各诊断方案及其影响，并由用户决定。

#### 开放的思考空间

以上列出的分析角度只是起手式。**如果你发现了其他值得分析的角度、不合理之处、或值得总结的模式，主动提出。** 即使不在上述框架内，任何你觉得可能意味着 skill 应该改进的地方，都可以纳入分析。

#### 旋转视角：使用质量维度透镜

同一个差异点，换不同视角看，可能发现不同层面的改进机会。查阅 `references/quality-lenses.md`，在归因时轮换使用推理深度、框架自觉、读者意识、完备性、直接性、压缩质量等透镜。

#### 归因完成后的检查点

归因完成进入阶段三之前，按识别出的改进点数量分流：

- **1-2 个点**：直接进入阶段三，在改动方案中一并呈现归因，用户可在审阅改动时一并修正归因
- **3+ 个点**：先暂停，把每个点的归因独立列出供用户确认。用户确认后再进入阶段三设计改动
  理由：多点归因若有误，直接设计 3+ 个改动会产生大量返工；先确认归因可避免

阈值 3 为建议值。若多点明显同源（如同一根本原因在多处显现）可视为少数独立点；若少数点但复杂纠缠、归因彼此依赖，也可先列出确认。给出判断理由即可，不必拘泥于数字。

### 阶段三：泛化提炼

把特定案例中发现的思维模式重新表述为可跨场景适用的原则。

**泛化检验**：
1. 变换场景：把当前案例的具体条件全部去掉，这个思维模式在另一个案例或领域还成立吗？
2. 寻找反例：设想一个场景，遵循这个思维模式反而会导致错误——存在吗？如果存在，需要加什么限定条件？
3. 凝练表述：能否用一句话说清楚这个思维模式？如果说不清楚，判断是否因为提炼得还不够。
4. 覆盖范围：原则覆盖的操作范围是否需要更宽？找出失败案例中受影响的操作范围，问该原则在其他操作范围（同案例或跨案例）是否也成立。若是，重新表述为更通用形式。
5. 修复既有规则：
   - 若问题是缺少适用范围，保留原则，补足“何时适用、何时不适用、
     用什么信号判断”的边界。边界应尽量是可执行的判断问题，不只罗列当前案例。
   - 若问题是规则过度具体，先提炼其服务的更一般目标或判断原则，
     再将旧规则改写为该原则的典型适用情形，而不是继续把该情形表述为硬性要求。

**如果通不过泛化检验**：这个发现可能只是当前案例的特异性现象，先标记为弱观测，到阶段四 §4.4 做 learnings.md 交叉验证后，再决定是记录等待更多案例验证，还是升级为改动候选。不要直接写入 skill。

**枚举类内容建议标注为开放列表**：当改动涉及枚举（如"常用检索入口类型"），可注明开放性（"通常取以下几类"而非"只有以下几类"），除非确定是封闭枚举。实际使用所需内容常落在预设列表之外。

### 阶段四：设计改动

#### 4.1 判断改动位置与形态

在判断问题可控性、设计具体改动之前，先通读目标 skill 顶层结构，检索与本次发现相关的现有表述：

- 理解每节的组织目的（这一节讲什么主题、服务什么功能）
- 判断改动形态：
  - 改写合并：已有规则部分覆盖或高度相关时，融入该规则使其更完善。如文献笔记行首场景，新发现的"第 N 贡献"与已有"空洞前缀"同属"非回查线索"。改写位置即原规则所在，无需再判断归节
  - 新增：确认无相关内容才新增，此时判断归入哪一节（依据规则主题，而非"出错的那一节"）
  - 既有规则是问题成因时，直接改写、限定、降级或删除该规则，
    不得只在其他位置新增一条例外规则来抵消它。
- 避免直接在归因指向的那一节打补丁——出错位置告诉你"这里缺东西"，但不告诉你"缺的东西应该写在这里"
  - 例：AI 在 A 节执行出错，归因发现 A 节缺某规则。但深入看 skill 结构会发现该规则本应属 B 节（B 节讲相关概念定义），A 节只是漏引用——补在 A 节会让 A、B 两节主题混淆

#### 4.2 判断问题可控性

在动手设计改动之前，先判断问题属于哪类：

| 类型 | 判定 | 示例 |
|---|---|---|
| **skill 可控** | 问题源于 skill 指令缺失、模糊、矛盾或组织框架不当 | → 可以更新 skill |
| **模型能力限制** | 问题源于 AI 模型本身的能力边界 | → 不写入 skill，可在 learnings.md 记录为已知限制 |
| **任务固有难度** | 问题源于任务本身的模糊性，任何 skill 都无法完全消除 | → 可在 skill 中增加"遇到这种情况时的处理策略" |
| **一次性因素** | 问题仅由当前案例的特殊条件导致，经认真评估确认无法泛化为一般原则 | → 不更新 skill |

#### 4.3 三层输出

每个改动按其规模/风险/自信度归入三个层级之一；无论哪一层都展示 skill 改动 diff 代码块供用户决策：

| 层级 | 条件 | 做法 |
|---|---|---|
| **可信** | 改动很小、副作用风险极低 | 展示简洁改动 diff 供用户确认 |
| **需审** | 改动较显著或有争议 | 展示改动 diff + 推演验证供用户审阅 |
| **存疑** | 不确定是否应固化为 skill 规则 | 同时输出「若固化的简洁改动 diff」和「记 learnings.md 的摘要」二选项，由用户选择；若选 learnings，将改动方案一并记录在该条目中，便于未来直接采用 |

- 建议层级在每处 diff 后直接标注（如"—— 可信"），不集中到结尾统一说明
- 改动表述从简：本 skill 反复使用，累积膨胀快；新增文字尽量精简，追求言简意赅

**每一层改动方案都应包含**：
- skill 改动计划
  - 优先用 Markdown diff 格式代码块（`-` 旧行 / `+` 新行 / ` ` 共享上下文）
  - 变更密集或 diff 难以阅读时，改用 before/after 对照
- 改动理由（从归因到泛化的完整链条）
- 推演验证结果（有效性 + 副作用）
- 负面警示类考虑执行 AI 的默认倾向（常默认不做多余动作，如写笔记默认不标行首）。先判断改动类型：
  - 破除默认（AI 默认不做）：表述应"先正面指令（要做什么），再负面警示（别做成什么）"——否则禁止对象不存在，AI 不会因"禁止"而开始做
  - 防错（AI 会做但做错）：可只给负面警示

> 上述改动方案仅为**提议**。
> diff 格式指展示给用户的 Markdown 代码块，禁止在此阶段编辑任何 skill 文件。
> 编辑操作在进入阶段六、且用户明确批准改动方案后才执行。

#### 4.4 弱观测的 learnings.md 交叉验证

当某个观测被判定为"证据不足以直接写入 skill"、且属于可能升级为 skill 规则的类别（泛化失败、"存疑"）时，在决定其去向前，先查阅目标 skill 的 learnings.md，检索是否有同模式先例：

- **有先例**：升级本次观测，它不再是孤例。按"需审"层级呈现改动方案（引用先例作为佐证），并在方案中标注 learnings.md 中对应旧条目将在执行阶段删除（见阶段六）。
- **无先例**：维持弱观测处理，按 §4.3 "存疑"层级呈现两选项，其中"记入 learnings.md"即作为新观测追加。

仅记录类弱观测（如模型能力限制、已知限制）不触发本步骤，直接追加。

触发条件：仅当本次复盘存在可升级类弱观测时才需要读取 learnings.md。若本次复盘没有任何弱观测，则全程无需读取、也无需写入 learnings.md。

### 阶段五：推演验证

**此阶段需要用户参与**。AI 先做初步推演，然后将关键推演结果呈现给用户。用户可能指出 AI 没意识到的使用场景或边界条件，这些信息应纳入最终的改动决策。

#### 5.1 有效性验证

> 设想另一个 AI 使用更新后的 skill 执行本次相同的分析任务，它能否复现本次的成功经验、或不再出现本次的问题？

选取本次执行中 1-2 个关键决策点，设想更新后的 skill 在这些决策点会给出什么指导，判断这个指导是否足以让 AI 做出正确的选择。

#### 5.2 副作用验证

> 设想另一个 AI 使用更新后的 skill 执行一个不同领域的问题，它是否会被新增规则误导？

选取 1-2 个与当前案例截然不同的场景（如当前是物理问题，则选一个组织管理问题），设想新规则在这些场景下会如何被解读，判断解读结果是否合理。
如果会导致不合理行为，改动需要重新设计——增加限定条件或从硬性规则改为软性建议。

#### 5.3 既有规则修复验证

当本次改动涉及既有规则的范围、抽象层级或存废时，分别推演：

1. **当前案例**：更新后能否避免原错误？
2. **边界案例**：旧规则不应触发时，AI 能否识别并停止执行它？
3. **原规则的典型场景**：若旧规则加了适用边界，或被上提为原则的特例，更新后能否仍导出原来正确的具体做法？

若三者不能同时成立，说明范围或一般原则仍不够准确，应重新设计或保留多个方案供用户选择。

#### 5.4 多版本比较

如果针对同一个问题有多种改进方案，对它们分别做有效性和副作用验证，选出最优方案。难以抉择时，保留多个方案并标注各自的适用条件，由用户决定。

#### 5.5 子 Agent 辅助

当需要并行检查多个不同领域的案例时，可启动子 agent 分别评估，每个 agent 负责一个领域场景的推演。

> ⛔ **停止**：阶段五到此为止。等待用户对改动方案的反馈。
> 在用户明确批准之前，禁止编辑任何 skill 文件。

### 阶段六：执行与记录

用户确认改动方案后：
1. 编辑目标 skill 的 SKILL.md，应用改动
2. 删除 learnings.md 中在 §4.4 交叉验证中被升级的旧条目
3. 如果此次分析产生了新的、尚未达到"需审"级别的观察（如 §4.4 交叉验证无先例、泛化失败、模型能力限制），追加到 learnings.md

---

## learnings.md 机制

### 角色

`learnings.md` 是目标 skill 的工作记忆——存放尚未归因、未泛化、低置信度的原始观察。它位于目标 skill 的目录下（与 SKILL.md 同级）。
它同时充当弱观测的证据累积账本：本次复盘出现的弱观测先与其中先例交叉验证（§4.4），有先例则升级、无先例则追加。

### 格式

自由文本。每次追加一个条目，标注日期、场景类型、发现类别（困惑点/经验点/约束问题）和描述。格式从简，目的是让下次执行时 AI 能快速理解上下文。

```markdown
## 2026-07-18
- 场景：分析纯理论 PDE 论文。困惑点：skill 说"优先用公式拆分"，但论文没有显式公式时拆分策略不明。
- 场景：用户指出因果链跳步。经验：拆分完应增加一步反向验证。
```

### 生命周期

```
skill 启动 → 读取 learnings.md → 执行任务
  ↓
执行中发现可能的改进信号 → 追加到 learnings.md
  ↓
用户触发 skill-refiner 复盘 → 归因 → 设计改动
  ↓
是否存在可升级类弱观测？
  ├─ 否 → 全程不读不写 learnings.md
  └─ 是 → 读取 learnings.md 交叉验证
       ├─ 有同模式先例 → 升级为改动候选（旧条目标记已处理）
       └─ 无先例 → 新弱观测追加到 learnings.md
  ↓
改动经归因→泛化→验证→用户确认 → 写入 SKILL.md
  ↓
被升级的旧条目 → 从 learnings.md 中删除
```

---

## 与用户互动

### 必须确认的情况

- 归因不确定时（如无法判断专家是因为 X 还是 Y 才这么写的）
  - 可列选项：并列列出各候选归因供用户选择
- 专家修正可能表明既有规则缺少适用范围、过度具体或本身不合理时
  - 说明证据、候选诊断和各自的改动方向，由用户决定
- 改动可能导致 skill 行为重大变化时（如调整顶层组织框架）
- 泛化检验中发现了需要用户领域知识才能判断的边界条件
- 多种改动方案难以抉择时
- 任何改动在执行之前都必须经用户确认

### 可能对用户有启发的互动

- 帮用户在"说不好哪里不对"时，通过结构化提问把模糊的感觉翻译为具体的质量缺陷
- 鼓励并辅助用户设想"如果 skill 改成这样，在什么情况下反而会变差"
- 多个改进方向时，让用户排列优先级
- 推演验证阶段，请用户补充 AI 可能没意识到的使用场景

### 不需要打扰用户的情况

- 纯技术性归因（AI 可独立完成的因果推理）
- 初步推演（用户会在阶段五统一参与）
- 措辞润色（凝练表述、调整文字）

以上指分析过程中的判断步骤，不包含执行文件改动。
编辑 skill 文件始终需要用户确认（见上方"必须确认的情况"最后一条）。

---

## 证据强度

当评估某个观察是否足够成熟、可以提议为改动时，参考以下分级：

| 强度 | 条件 | 处理 |
|---|---|---|
| **弱** | 单次观察、未被验证，learnings.md 中亦无同模式先例 | 按 §4.3 "存疑"层级呈现两选项，由用户决定直接改 skill 还是先放 learnings |
| **中** | 同模式在 ≥2 次独立执行中出现（含 learnings.md 中的先例），或已通过初步跨领域泛化检验 | 提议为"需审" |
| **强** | 用户明确认可，或多次出现且推演验证全部通过 | 高置信度改动 |

证据强度的作用是为 AI 提供判断依据——强度越低，越应按"存疑"层级呈现两选项让用户决断；强度越高，越可主动推进为"可信"或"需审"。
learnings.md 先例是弱观测升级的关键证据：同一模式首次出现时经用户决定记入 learnings.md，第二次独立出现（本次观测加先例）即达中强度，具备改动候选资格。
注意这不替代用户确认：即使是"强"证据的改动，仍需经用户确认后执行。