compound 技能

目的： 在工作过程中即时记录经过验证的洞察，构建可搜索的知识库。

概述

该技能在洞察被确认的瞬间立即捕获，并将其存储为基于 YAML frontmatter 的结构化文档。它使用按类别划分的单一文件架构，每个洞察都保存在 knowledge/[category]/[filename].md 中。

<critical_sequence name=”insight-capture” enforce_order=”strict”>

7 步流程

自动检测短语（从对话中识别）：

• “这个效果很好”
• “这个方法不错”
• “下次也这么做吧”
• “这个记录一下吧”
• “这个格式很管用”
• “这个有效果”
• “这样做就成了”
• “需要记住”

或手动触发： /compound 命令

仅记录非琐碎信息（有价值的可复用洞察）：

• 可以重复使用的模式
• 适用于其他情境的经验教训
• 经过反复尝试发现的方法
• 经过实践检验的有效方法
• 带来结构性改进的发现

跳过标准：

• 仅适用于当前情境的一次性方法
• 单纯的事实记录（数字、日期等）
• 已记录内容的重复
• 尚未验证的假设

从对话历史中提取：

必填信息：

• domain：work / learning / project / tool / personal
• insight_type：洞察类型（参见 schema.yaml 枚举）
• component：领域内的子组件（参见 schema.yaml 枚举）
• context：洞察产生的情境描述（1-3 句）
• key_learning：核心经验教训的一句话总结（应可泛化到其他情境）
• impact：critical / high / medium / low
• tags：搜索关键词（小写，连字符分隔）

额外收集项：

• 背景：当时正在进行的项目/活动
• 尝试过的方法：无效的方法
• 有效的方法：实际起作用的方法
• 有效的原因：为何该方法有效
• 复现条件：何时可以使用该方法

阻塞性要求： 如果 domain、insight_type 或核心洞察不明确，需向用户提问并等待回答：

为记录此洞察，需要确认几点信息：

1. 属于哪个领域？(work/learning/project/tool/personal)
2. 洞察类型是？(例如：workflow_pattern, problem_solving, tool_discovery...)
3. 用一句话总结核心经验教训？

[等待用户回复后继续]

在 knowledge/ 中搜索相似洞察：

# 按 domain、tags、insight_type 进行并行搜索
Grep: pattern="domain: [domain]" path=knowledge/ output_mode=files_with_matches
Grep: pattern="tags:.*[keyword]" path=knowledge/ output_mode=files_with_matches -i=true
Grep: pattern="insight_type: [type]" path=knowledge/ output_mode=files_with_matches

发现相似文档时，向用户提供选项并等待：

发现相似文档：knowledge/[path]

接下来怎么做？
1. 创建新文档 + 添加交叉引用（推荐）
2. 更新现有文档（如果是同一洞察的补充）
3. 其他

请选择 (1-3)：_

等待用户回复后执行所选操作。

若无相似文档，直接进入步骤 4。

格式：YYYYMMDD-[经处理的洞察标识].md

处理规则：

• 转为小写
• 空格 → 连字符
• 移除特殊字符（连字符除外）
• 截断至 80 字符以内

示例：

• 20260304-claude-code-skill-structure.md
• 20260304-mcp-server-debugging-pattern.md
• 20260304-prompt-iteration-framework.md

基于 schema.yaml 验证所有必填字段。

<validation_gate name=”yaml-schema” blocking=”true”>

验证项：

• domain：必须是 schema.yaml 中的枚举值之一
• date：格式为 YYYY-MM-DD
• insight_type：必须是 schema.yaml 中的枚举值之一
• component：必须是该 domain 映射的枚举值之一（参见 domain_component_mapping）
• context：20-300 字，需描述具体情境
• key_learning：10-200 字，应为可泛化的经验教训
• impact：critical / high / medium / low
• tags：1-8 个，小写，连字符分隔

验证失败时，阻塞步骤 6：

YAML 验证失败

错误：
- domain：不是允许的值 → 必须为 work、learning、project、tool、personal 之一
- component：该 domain 不允许的组件 → 请参考 schema.yaml
- tags：包含大写字母 → 需要转为小写

请提供修正后的值。

关卡强制： 在所有验证通过前，不得进行步骤 6。

</validation_gate>

确定类别目录： 根据 schema.yaml 中的 category_mapping 将 insight_type 映射到存储路径。

创建文档：

INSIGHT_TYPE="[从已验证的 YAML 中获取]"
CATEGORY_DIR="[从 category_mapping 获取]"
FILENAME="[步骤 4 生成的名称]"
DOC_PATH="${CATEGORY_DIR}${FILENAME}"

# 如果目录不存在，则创建
mkdir -p "${CATEGORY_DIR}"

# 基于 assets/resolution-template.md 编写文档
# （使用步骤 2 收集的上下文 + 步骤 5 验证过的 YAML frontmatter）

结果：

• 在类别目录下创建单个文件
• 通过枚举验证确保分类一致

如果在步骤 3 中发现了相似文档：

# 在现有文档中添加相关章节
# 在新文档中也添加指向现有文档的链接

模式候选项检测：

如果同一类别中存在 3 个或以上相似洞察：

检测到模式文档候选：[类别] 中存在 X 个相似洞察
→ 是否要综合到 patterns/ 文档中？

关键模式升级条件（不自动升级，由用户决定）：

• impact 为 critical 时
• 可跨多个领域应用时
• 必须牢记时

在这种情况下，在决策菜单的“2. 添加到关键模式”选项旁添加注释：

此洞察值得考虑升级为关键模式

</critical_sequence>

<decision_gate name=”post-documentation” wait_for_user=”true”>

记录后决策菜单

文档记录成功后，提供选项并等待用户回复：

洞察已记录。

文件已创建：
- knowledge/[category]/[filename].md

下一步操作：
1. 继续当前工作（推荐）
2. 添加到关键模式 - 升级到 critical-patterns.md
3. 关联相关文档 - 与相似洞察建立交叉引用
4. 添加到现有技能 - 链接到 .claude/skills/
5. 查看文档 - 显示生成的内容

请选择：_

各选项处理方式：

选项 1：继续当前工作

• 返回当前任务/工作流
• 文档记录完成

选项 2：添加到关键模式

当用户选择此项时：

• 可重复应用的模式
• 绝不能忘记的经验教训
• 非直观但必须遵守的规则

操作：

1. 从文档中提取模式
2. 按 assets/critical-pattern-template.md 格式进行结构化
3. 添加到 knowledge/patterns/critical-patterns.md（保持原有顺序）
4. 在原文档中添加交叉引用
5. 确认信息：“已添加到关键模式。”

选项 3：关联相关文档

• 提示：“要与哪个文档关联？（输入文件名或描述主题）”
• 在 knowledge/ 中搜索目标文档
• 添加双向交叉引用
• 确认信息：“已添加交叉引用”

选项 4：添加到现有技能

• 提示：“要添加到哪个技能？”
• 在 .claude/skills/[技能名称]/ 的适当文件中添加链接和说明
• 确认信息：“已添加到 [技能名称] 技能”

选项 5：查看文档

• 显示生成的文档内容
• 重新显示决策菜单

</decision_gate>

<integration_protocol>

集成点

调用触发：

• /compound 命令（主要接口）
• 对话中自动检测到特定短语
• 工作流完成后手动调用

被调用的技能/代理：

• 无（终端技能 – 不委托给其他技能）

交接条件：
调用前，对话历史中应有足够的上下文信息。

</integration_protocol>

<success_criteria>

成功标准

当满足以下所有条件时，文档记录视为成功：

• YAML frontmatter 验证通过（所有必填字段、格式正确、枚举值有效）
• 已在 knowledge/[category]/[filename].md 创建文件
• domain-component 映射与 schema.yaml 一致
• Context、What Worked、Why This Works 等章节内容具体
• 若发现相似文档，已添加交叉引用
• 已向用户展示决策菜单并根据其操作进行确认

</success_criteria>

错误处理

上下文不足：

• 向用户询问缺失信息
• 在获取到必填信息前，不得继续

YAML 验证失败：

• 显示具体的错误项
• 使用修正后的值重试
• 通过验证前阻塞进程

相似洞察不明确：

• 列出所有候选项
• 由用户选择：新建文档 / 更新现有 / 单独链接

类别映射不确定：

• 建议最接近的类别
• 经用户确认后继续

执行指南

必须执行的事项：

• 必须进行 YAML frontmatter 验证（步骤 5 的 validation gate 是阻塞性的）
• 必须验证 domain-component 映射的有效性
• 写入文件前必须使用 mkdir -p 创建目录
• 缺少上下文时必须询问用户并等待回复
• key_learning 应泛化到其他情境

绝对禁止的事项：

• 跳过 YAML 验证（validation gate 是阻塞性的）
• 用模糊的描述记录文档（导致无法搜索）
• 记录假设或未经验证的内容
• 自动升级为关键模式（必须由用户决定）

示例场景

用户： “在 Claude Code 里创建技能时，在 references/ 文件夹里放了示例，它执行得就准确多了。下次也这么做吧。”

技能激活：

1. 触发检测： “下次也这么做吧” → 自动激活
2. 收集上下文：
   • domain: tool
   • insight_type: tool_discovery
   • component: claude-code
   • context: “编写 Claude Code 技能时，如果除了 SKILL.md 之外，还在 references/ 文件夹里放入具体示例文件，技能执行的准确率会显著提高”
   • key_learning: “编写 AI 技能/提示词时，提供具体示例文件比仅靠抽象指令能显著提高执行准确率”
   • impact: high
   • tags: [claude-code, skill, references, accuracy, prompt-engineering]
3. 搜索现有文档： 搜索 knowledge/tool-discoveries/
4. 生成文件名： 20260304-skill-references-improve-accuracy.md
5. YAML 验证： 通过
6. 创建文档： knowledge/tool-discoveries/20260304-skill-references-improve-accuracy.md
7. 交叉引用： 无（未发现相似文档）

输出：

洞察已记录。

文件已创建：
- knowledge/tool-discoveries/20260304-skill-references-improve-accuracy.md

下一步操作：
1. 继续当前工作（推荐）
2. 添加到关键模式 - 升级到 critical-patterns.md
3. 关联相关文档 - 与相似洞察建立交叉引用
4. 添加到现有技能 - 链接到 .claude/skills/
5. 查看文档 - 显示生成的内容