⚡

复合文档技能Skill compound-docs

该技能用于自动捕获和文档化已解决的问题，通过YAML前端元数据构建分类组织的可搜索知识库，提高团队效率、促进知识共享和问题解决。关键词：文档化、知识管理、YAML、搜索优化、问题解决、分类组织、机构知识。

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

name: 复合文档 description: 以YAML前端元数据捕获已解决的问题作为分类文档，用于快速查找 allowed-tools:

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

复合文档技能

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

概述

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

组织： 单文件架构 - 每个问题记录为一个Markdown文件，放在其症状类别目录中（例如，docs/solutions/performance-issues/n-plus-one-briefs.md）。文件使用YAML前端元数据用于元数据和可搜索性。

<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或后实现）
  • OS版本
  • 文件/行引用

阻塞要求： 如果关键上下文缺失（模块名称、确切错误、阶段或解决步骤），询问用户并等待响应后再进行步骤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前端元数据，带枚举验证。

<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前端元数据通过 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前端元数据填充）

结果：

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

创建文档： 用步骤2收集的上下文和步骤5验证的YAML前端元数据填充 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中的 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前端元数据已验证（所有必需字段，正确格式）
  • ✅ 文件创建于docs/solutions/[类别]/[文件名].md
  • ✅ 枚举值完全匹配schema.yaml
  • ✅ 解决方案部分包含代码示例
  • ✅ 如找到相关问题，添加交叉引用
  • ✅ 向用户呈现决策菜单并确认操作

</success_criteria>

错误处理

缺失上下文：

  • 询问用户缺失细节
  • 直到提供关键信息才继续

YAML验证失败：

  • 显示具体错误
  • 呈现重试带更正值
  • 阻塞直到有效

类似问题模糊：

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

模块不在模块文档中：

  • 警告但不阻塞
  • 继续文档化
  • 建议：“如未添加，将[模块]添加到模块文档”

执行指南

必须做：

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

必须不做：

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

质量指南

良好文档有：

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

避免：

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

示例场景

用户： “That worked! The N+1 query is fixed.”（那有效了！N+1查询已修复。）

技能激活：

  1. 检测确认： “That worked!” 触发自动触发
  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阶段范围，但可能：

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