⚡

复合文档技能Skill compound-docs

该技能用于自动捕获和分类已解决的软件问题，构建基于YAML frontmatter的可搜索知识库，实现问题解决方案的快速查找、团队知识共享和错误预防，适用于软件开发、DevOps和文档管理场景。关键词：自动文档化、问题解决、知识库、YAML、搜索、分类、DevOps、软件调试。

DevOps 0 次安装 0 次浏览 更新于 3/9/2026

name: compound-docs description: 捕获已解决的问题作为分类文档，使用YAML frontmatter进行快速查找 allowed-tools:

  • Read # 解析对话上下文
  • Write # 创建解决方案文档
  • Bash # 创建目录
  • Grep # 搜索现有文档 preconditions:
  • 问题已解决（非进行中）
  • 解决方案已验证有效

compound-docs 技能

目的： 自动文档化已解决的问题，构建基于类别的可搜索机构知识库（使用枚举验证的问题类型）。

概述

该技能在确认后立即捕获问题解决方案，创建结构化文档，作为未来会话的可搜索知识库。

组织方式： 单文件架构 - 每个问题作为一个markdown文件记录在其症状类别目录中（例如，docs/solutions/performance-issues/n-plus-one-briefs.md）。文件使用YAML frontmatter进行元数据管理和搜索。

<critical_sequence name=“documentation-capture” enforce_order=“strict”>

7步流程

<step number=“1” required=“true”>

步骤1：检测确认

自动触发短语：

  • “that worked”（问题解决了）
  • “it’s fixed”（已修复）
  • “working now”（现在正常了）
  • “problem solved”（问题已解决）
  • “that did it”（搞定了）

或手动： /doc-fix 命令

仅非琐碎问题：

  • 需要多次调查尝试
  • 耗时的复杂调试
  • 非显而易见的解决方案
  • 未来会话会受益

跳过文档化的情况：

  • 简单拼写错误
  • 明显的语法错误
  • 立即纠正的琐碎修复 </step>

<step number=“2” required=“true” depends_on=“1”>

步骤2：收集上下文

从对话历史中提取：

必需信息：

  • 模块名称： 哪个模块或组件出现问题
  • 症状： 可观察的错误/行为（确切的错误消息）
  • 调查尝试： 未奏效的方法及原因
  • 根因： 实际问题的技术解释
  • 解决方案： 修复方法（代码/配置更改）
  • 预防措施： 如何避免未来发生

环境细节：

  • Rails版本
  • 阶段（0-6或实施后）
  • 操作系统版本
  • 文件/行引用

阻塞要求： 如果缺少关键上下文（模块名称、确切错误、阶段或解决步骤），询问用户并在继续步骤3前等待响应：

我需要一些细节来正确文档化：

1. 哪个模块出现此问题？ [模块名称]
2. 确切的错误消息或症状是什么？
3. 您处于哪个阶段？（0-6或实施后）

[用户提供细节后继续]

</step>

<step number=“3” required=“false” depends_on=“2”>

步骤3：检查现有文档

搜索docs/solutions/以查找类似问题：

# 通过错误消息关键词搜索
grep -r "确切错误短语" docs/solutions/

# 通过症状类别搜索
ls docs/solutions/[类别]/

如果找到类似问题：

则呈现决策选项：

找到类似问题：docs/solutions/[路径]

下一步？
1. 创建新文档并添加交叉引用（推荐）
2. 更新现有文档（仅当根因相同时）
3. 其他

选择（1-3）：_

等待用户响应，然后执行所选操作。

否则（未找到类似问题）：

直接进行步骤4（无需用户交互）。 </step>

<step number=“4” required=“true” depends_on=“2”>

步骤4：生成文件名

格式：[净化后症状]-[模块]-[YYYYMMDD].md

净化规则：

  • 小写
  • 空格替换为连字符
  • 移除特殊字符，除连字符外
  • 截断到合理长度（<80字符）

示例：

  • missing-include-BriefSystem-20251110.md
  • parameter-not-saving-state-EmailProcessing-20251110.md
  • webview-crash-on-resize-Assistant-20251110.md </step>

<step number=“5” required=“true” depends_on=“4” blocking=“true”>

步骤5：验证YAML模式

关键： 所有文档都需要经过验证的YAML frontmatter，包含枚举验证。

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

根据模式验证： 加载schema.yaml并根据yaml-schema.md中定义的枚举值对问题进行分类。确保所有必需字段存在且与允许值完全匹配。

验证失败则阻塞：

❌ YAML验证失败

错误：
- problem_type: 必须是模式枚举之一，得到"compilation_error"
- severity: 必须是[critical, high, medium, low]之一，得到"invalid"
- symptoms: 必须是包含1-5项的数组，得到字符串

请提供更正后的值。

门禁执行： 在YAML frontmatter通过schema.yaml定义的所有验证规则之前，不得进行步骤6（创建文档）。

</validation_gate> </step>

<step number=“6” required=“true” depends_on=“5”>

步骤6：创建文档

从problem_type确定类别： 使用yaml-schema.md中定义的类别映射（第49-61行）。

创建文档文件：

PROBLEM_TYPE="[来自验证后的YAML]"
CATEGORY="[从problem_type映射]"
FILENAME="[生成的文件名].md"
DOC_PATH="docs/solutions/${CATEGORY}/${FILENAME}"

# 如有需要，创建目录
mkdir -p "docs/solutions/${CATEGORY}"

# 使用assets/resolution-template.md中的模板写入文档
# （内容填充步骤2收集的上下文和验证后的YAML frontmatter）

结果：

  • 类别目录中的单个文件
  • 枚举验证确保分类一致性

创建文档： 用步骤2收集的上下文和步骤5验证后的YAML frontmatter填充assets/resolution-template.md中的结构。 </step>

<step number=“7” required=“false” depends_on=“6”>

步骤7：交叉引用和关键模式检测

如果在步骤3找到类似问题：

更新现有文档：

# 向类似文档添加相关问题链接
echo "- 另见：[$FILENAME]($REAL_FILE)" >> [类似文档.md]

更新新文档： 已包含步骤6的交叉引用。

如果适用，更新模式：

如果这代表常见模式（3个以上类似问题）：

# 添加到docs/solutions/patterns/common-solutions.md
cat >> docs/solutions/patterns/common-solutions.md << 'EOF'

## [模式名称]

**常见症状：** [描述]
**根因：** [技术解释]
**解决方案模式：** [通用方法]

**示例：**
- [链接到文档1]
- [链接到文档2]
- [链接到文档3]
EOF

关键模式检测（可选主动建议）：

如果此问题有自动指示器暗示可能关键：

  • YAML中severity为critical
  • 影响多个模块或基础阶段（阶段2或3）
  • 非显而易见的解决方案

则在决策菜单（步骤8）中添加注释：

💡 这可能值得添加到必读内容（选项2）

但切勿自动提升。用户通过决策菜单决定（选项2）。

关键模式添加模板：

当用户选择选项2（添加到必读内容）时，使用assets/critical-pattern-template.md中的模板构建模式条目。根据docs/solutions/patterns/critical-patterns.md中现有模式进行顺序编号。 </step>

</critical_sequence>

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

文档化后决策菜单

成功文档化后，呈现选项并等待用户响应：

✓ 解决方案已文档化

创建文件：
- docs/solutions/[类别]/[文件名].md

下一步？
1. 继续工作流（推荐）
2. 添加到必读内容 - 提升为关键模式（critical-patterns.md）
3. 链接相关问题 - 连接到类似问题
4. 添加到现有技能 - 添加到学习技能（例如，hotwire-native）
5. 创建新技能 - 提取为新学习技能
6. 查看文档 - 查看捕获内容
7. 其他

处理响应：

选项1：继续工作流

  • 返回调用技能/工作流
  • 文档化完成

选项2：添加到必读内容 ⭐ 关键模式的主要路径

用户选择此选项当：

  • 系统在不同模块多次犯此错误
  • 解决方案非显而易见但必须每次遵循
  • 基础要求（Rails、Rails API、线程等）

操作：

  1. 从文档中提取模式
  2. 格式化为❌错误 vs ✅正确，带代码示例
  3. 添加到docs/solutions/patterns/critical-patterns.md
  4. 添加交叉引用回本文档
  5. 确认：“✓ 已添加到必读内容。所有子代理将在代码生成前看到此模式。”

选项3：链接相关问题

  • 提示：“链接到哪个文档？（提供文件名或描述）”
  • 搜索docs/solutions/以查找文档
  • 向两个文档添加交叉引用
  • 确认：“✓ 交叉引用已添加”

选项4：添加到现有技能

用户选择此选项当文档化的解决方案与现有学习技能相关：

操作：

  1. 提示：“哪个技能？（hotwire-native等）”
  2. 确定更新哪个参考文件（resources.md、patterns.md或examples.md）
  3. 向适当部分添加链接和简要描述
  4. 确认：“✓ 已添加到[技能名称]技能的[文件]”

示例：对于Hotwire Native Tailwind变体解决方案：

  • 添加到hotwire-native/references/resources.md下的"项目特定资源"
  • 添加到hotwire-native/references/examples.md，带解决方案文档链接

选项5：创建新技能

用户选择此选项当解决方案代表新学习领域的开始：

操作：

  1. 提示：“新技能应称为什么？（例如，stripe-billing、email-processing）”
  2. 运行python3 .claude/skills/skill-creator/scripts/init_skill.py [技能名称]
  3. 使用此解决方案作为第一个示例创建初始参考文件
  4. 确认：“✓ 创建了新的[技能名称]技能，以此解决方案作为第一个示例”

选项6：查看文档

  • 显示创建的文档
  • 再次呈现决策菜单

选项7：其他

  • 询问他们想做什么

</decision_gate>

<integration_protocol>

集成点

调用者：

  • /compound命令（主要接口）
  • 解决方案确认后对话中手动调用
  • 可通过检测确认短语触发，如"that worked"、"it’s fixed"等

调用：

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

交接期望： 文档化所需的所有上下文应在调用前存在于对话历史中。

</integration_protocol>

<success_criteria>

成功标准

文档化成功当所有以下条件为真：

  • ✅ YAML frontmatter已验证（所有必需字段，正确格式）
  • ✅ 文件创建于docs/solutions/[类别]/[文件名].md
  • ✅ 枚举值与schema.yaml完全匹配
  • ✅ 解决方案部分包含代码示例
  • ✅ 如果找到相关问题，添加了交叉引用
  • ✅ 用户呈现决策菜单并确认操作

</success_criteria>

错误处理

缺少上下文：

  • 询问用户缺失细节
  • 在提供关键信息前不继续

YAML验证失败：

  • 显示具体错误
  • 提供更正值重试
  • 阻塞直到有效

类似问题模糊：

  • 呈现多个匹配项
  • 让用户选择：新文档、更新现有或链接为重复

模块不在文档中：

  • 警告但不阻塞
  • 继续文档化
  • 建议：“如果[模块]不在模块文档中，请添加”

执行指南

必须做：

  • 验证YAML frontmatter（如果无效则阻塞，根据步骤5验证门）
  • 从对话中提取确切错误消息
  • 解决方案部分包含代码示例
  • 写入文件前创建目录（mkdir -p）
  • 如果缺少关键上下文，询问用户并等待

不得做：

  • 跳过YAML验证（验证门是阻塞的）
  • 使用模糊描述（不可搜索）
  • 省略代码示例或交叉引用

质量指南

良好文档有：

  • ✅ 确切错误消息（从输出复制粘贴）
  • ✅ 具体文件:行引用
  • ✅ 可观察症状（所见，非解释）
  • ✅ 失败的尝试文档化（帮助避免错误路径）
  • ✅ 技术解释（不仅"是什么"，还有"为什么"）
  • ✅ 代码示例（如适用，前后对比）
  • ✅ 预防指导（如何早期捕获）
  • ✅ 交叉引用（相关问题）

避免：

  • ❌ 模糊描述（“有些问题”）
  • ❌ 缺少技术细节（“修复了代码”）
  • ❌ 无上下文（哪个版本？哪个文件？）
  • ❌ 仅代码转储（解释为何有效）
  • ❌ 无预防指导
  • ❌ 无交叉引用

示例场景

用户： “问题解决了！N+1查询已修复。”

技能激活：

  1. 检测确认： "问题解决了！"触发自动调用
  2. 收集上下文：
    • 模块：Brief System
    • 症状：简报生成超过5秒，加载电子邮件线程时N+1查询
    • 失败尝试：添加分页（无效），检查后台作业性能
    • 解决方案：在Brief模型上添加急切加载includes(:emails)
    • 根因：缺少急切加载导致每个电子邮件线程单独数据库查询
  3. 检查现有： 未找到类似问题
  4. 生成文件名： n-plus-one-brief-generation-BriefSystem-20251110.md
  5. 验证YAML：
    module: Brief System
date: 2025-11-10
problem_type: performance_issue
component: rails_model
symptoms:
  - "加载电子邮件线程时N+1查询"
  - "简报生成超过5秒"
root_cause: missing_include
severity: high
tags: [n-plus-one, eager-loading, performance]
    ✅ 有效
  6. 创建文档：
    • docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md
  7. 交叉引用： 无需（无类似问题）

输出：

✓ 解决方案已文档化

创建文件：
- docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md

下一步？
1. 继续工作流（推荐）
2. 添加到必读内容 - 提升为关键模式（critical-patterns.md）
3. 链接相关问题 - 连接到类似问题
4. 添加到现有技能 - 添加到学习技能（例如，hotwire-native）
5. 创建新技能 - 提取为新学习技能
6. 查看文档 - 查看捕获内容
7. 其他

未来增强

不在第7阶段范围，但可能：

  • 按日期范围搜索
  • 按严重性筛选
  • 基于标签的搜索界面
  • 指标（最常见问题、解决时间）
  • 导出为可共享格式（社区知识共享）
  • 导入社区解决方案