从一句话到几十份文档：用Skill-insight的生成企业级Skill

一篇文档生成一个Skill只是入门。当你有几十份故障记录、上百页操作手册时，怎么把它们浓缩成一个精准的领域Skill？Skill-insight就是答案。

第1篇里，我们用一份Git Commit规范文档走通了从文档到Skill的全流程：安装平台、一句话生成、质量验证、执行评测。

但真实工作中，输入很少像"一份写好的规范文档"那样整齐。更多时候你面对的是这些情况：

"帮我做个Kafka排查的Skill，我们线上最近老出问题。"

"这三年攒了20份MySQL慢查询复盘，能不能提炼成一套通用的排查技能？"

"我手头有份故障模式表，但不够全，你能帮我扩展一下吗？"

第1篇解决的是"一份文档 → 一个Skill"。但如果输入是模糊的一句话、散乱的十几份记录、或者半成品的表格，怎么办？

本篇就回答这一个问题：手头资料形态各异，怎么稳定输出高质量的Skill？

答案在Skill-insight两种能力上：扩展（Expand） 和 归纳（Induce）。它们覆盖了从"一句话"到"几十份文档"之间的所有输入形态。

Skill-insight的生成路径，本质上就是这两种信息流动方向的组合：

2.1 扩展能力

适用场景：你心里大概知道想要什么，但缺少具体的经验文档或故障模式列表。

典型入口语句：

"帮我做一个Kafka排查的Skill。""做个Code Review checklist的skill。""帮我生成一个分析vmcore的skill，主要用来排查OOM、死锁、内核崩溃和硬件报错等常见故障。"

Skill-insight会先搜索这个领域的常见故障 / 操作，扩展出一张候选模式表（5-10项），呈现给你确认增删。确认后再走完整生成流程。

2.2 归纳能力

适用场景：你手头有多份相近的真实案例（问题单、排障记录、复盘文档），想从里面"抽出共性"做成可复用的Skill。

典型入口语句：

"请基于以下三个故障问题单生成一个统一的排查Skill。""从这些OOM领域经验文件里总结一个通用的内存故障排查Skill。"

Skill-insight会逐份提取案例（提炼现象 / 时间线 / 关键证据 / 排查步骤），然后交叉比对，将相同机制的合并成一个故障模式。这一步对应入门篇里讲的"去冗余、合相似、抽模式"。

2.3 两个能力，一个流程

不管输入走扩展还是归纳，后续流程是统一的：

扩展输入 ──┐           ├──→ 故障模式列表 ──→ 质量扫描 ──→ 搜索补全 ──→ 审核 ──→ 生成Skill归纳抽取 ──┘

生成路径由Skill-insight自己根据输入识别，不需要你选"模式"或切换开关。只管把手头有的东西丢过去就行。

下面两个案例将分别展示扩展和归纳的实际工作方式。

3.1 环境

环境安装与第1篇完全相同。如果还没有安装，打开终端执行：

npx @witty-ai/skill-insight install

安装完成后在OpenCode中注册Skill工具包：

npx skills add https://gitcode.com/openeuler/witty-skill-insight.git

按指引选择 skill-generator，并选择你的集成框架（如OpenCode）。

如果环境已就绪，可跳过此节直接进入案例。

3.2 输入类型速查

下面任意一种输入都可以。输入越具体，生成的Skill越精确——但最低门槛就是一句话。

vmcore分析涉及多种互不相同的故障类别：内核崩溃、OOM、死锁、网络挂死、文件系统异常、硬件错误。每类的排查命令和判据都不一样。让人从零写一份覆盖全部的Skill，光梳理结构就要好几天。

但在Skill-insight里，只需要一句话。

输入

在OpenCode终端中输入：

帮我生成一个分析vmcore的skill，主要用来排查OOM、死锁、内核崩溃和硬件报错等常见故障。

Skill-insight会自动识别这是一条"扩展"类需求——输入稀疏，没有现成文档。它会先搜索vmcore相关的常见故障模式，列出一张候选表请你确认。确认后进入完整生成流程。

如果你想跳过交互确认：

帮我生成一个分析vmcore的skill，主要用来排查OOM、死锁、内核崩溃和硬件报错等常见故障，使用自动模式，不要交互。

生成的Skill   

vmcore-fault-diagnosis/├── SKILL.md                       # 定义4步分析工作流和6种故障模式识别方法的主文档├── scripts/                       # 7个故障排查脚本│   ├── collect.sh                 # 收集vmcore元数据、系统信息和内核日志的总入口脚本│   ├── check_hardware_fault.sh    # 检测MCE/ECC内存错误等硬件故障│   ├── check_kernel_panic.sh      # 分析panic消息和调用栈定位内核bug│   ├── check_deadlock.sh          # 检测spinlock/mutex等同步机制死锁│   ├── check_oom_killer.sh        # 分析内存耗竭和OOM killer触发原因│   ├── check_soft_lockup.sh       # 检测长时间占用CPU的软锁定故障│   └── check_hard_lockup.sh       # 检测CPU完全无响应的硬锁定故障└── references/                    # 6个故障模式详解文档    ├── hardware_fault.md    ├── kernel_panic.md    ├── deadlock.md    ├── oom_killer.md    ├── soft_lockup.md    └── hard_lockup.md

一句"帮我生成一个分析vmcore的skill" → 14个文件、68 KB的专业故障诊断Skill。

SKILL.md主体是4步分析工作流（信息采集 → 故障模式识别 → 场景细化与排查 → 兜底）。每个故障模式包含典型现象、关键判据和排查脚本概述，完整的子场景区分和排查建议放在对应的 references/{fault_mode}.md 里。这符合Agent Skills的"渐进式加载"设计：主文档保持紧凑（< 500行），细节按需加载。

执行效果

在真实环境中，用户输入：

我的操作系统发生了crash，你帮我分析下原因，目录:/opt/vmcore_file

配备该Skill的OpenCode自动完成了排查：用脚本提取故障上下文，识别故障类型，分析vmcore文件，最终给出根因。下图是某次内核代码缺陷导致的系统崩溃的排查结果：

这就是"扩展"能力的实际效果：一句模糊的需求，展开成覆盖6类故障、7个脚本的完整Skill。不需要事先准备任何文档。

扩展 vs 直接写的区别

有人会问：扩展不就是让LLM自己编吗？和直接让ChatGPT写一份排查指南有啥区别？

两个区别。

第一，结构化约束。扩展出来的内容被限制在Skill的标准框架里（YAML Frontmatter + 步骤化工作流 + 脚本 + 参考文献），不是自由文本。这意味着它能直接被Agent执行、评测和优化。

第二，审核环节可追溯。扩展生成的候选模式表会先让你过目——哪些故障类别保留、哪些合并、哪些删除。你不是被动接收LLM的输出，而是在把控知识边界。

vmcore案例展示了"从无到有"的扩展能力。但如果手头不是一句话，而是多份真实记录呢？

假设你是运维团队的负责人。团队在不同时间、不同机器、不同硬件型号上积累了3份硬盘故障问题单。根因都是同一个——磁盘物理介质损坏——但症状严重程度、设备型号、扇区号、影响范围各不相同。

你希望从这3份记录中抽象出 1个通用的硬盘故障排查Skill，以后同类问题能快速诊断。

输入

根据 `tests/skill-generator/cases/fault-multi-doc-disk/inputs` 下的三个故障问题单，帮我生成一个故障排查skill。

inputs/ 目录下放着3份真实问题单。排障记录一般需要包含现象、关键证据、排查步骤、根因和处置这几类信息。

Skill-insight会自动识别这是"归纳"类需求——多份输入，先提取再合并。

工作方式：Skill-insight内部的归纳过程

与vmcore案例的"搜索→扩展→生成"不同，归纳走的是另一条路径：

1. 1. 逐份提取：对每份问题单，提炼出现象、时间线、关键证据、排查步骤、根因和处置措施，形成结构化的case记录
2. 2. 交叉比对：将三份记录的根因进行比对——发现都是"磁盘物理介质损坏"，属于同一机制
3. 3. 合并共性：将相同的故障机制合并为一个故障模式
4. 4. 记录差异：三份案例在症状严重程度（轻微坏道vs大面积损坏）、影响范围（单盘vs多盘+控制器）、设备型号上的差异，被记录为"变化维度"

最终输出的不是三份孤立的Skill，而是一份覆盖整类故障的通用Skill，外加差异维度说明。

生成的Skill

disk-medium-error/├── SKILL.md                            # 4步排查工作流├── scripts/                            # 2个自包含脚本│   ├── collect.sh                      # SMART/dmesg/RAID状态采集│   └── check_disk_medium_error.sh      # 介质损坏排查（5个check项）└── references/                         # 3个参考文档    ├── disk-medium-error.md            # 4个子场景：单盘轻微 / 单盘严重 / 多盘+控制器 / 批量预警    ├── pattern_detail.md               # 归纳细节 + variation_vectors    └── failure_cases.yaml              # 三份原始案例存档（含结构化字段）

有个值得注意的输出是 failure_cases.yaml——原始案例没有被丢掉，而是以结构化形式存档，保留了 case_id、environment、timeline、evidences 等字段。这意味着：

• • 日后回溯，你能看出这个通用Skill是从哪些具体案例提炼的
• • 来了新案例，追加到yaml里重新归纳一遍，Skill就能持续进化

扩展 vs 归纳：两个案例的对比

两个案例放在一起对比，差异更清楚：

一个从无到有建骨架，一个从多到一提精华。两种能力互补，日常工作中遇到的大部分输入形态都能覆盖。

信息安全提醒： Skill-insight使用了LLM的生成能力，输入的问题单一定要做脱敏处理。建议做法：

1. 1. 输入侧：给 Skill-insight之前，把问题单里的真实IP、主机名、客户标识替换成占位符（<host-a>、<node-1>、<customer-x>）
2. 2. 产出侧：生成后用grep -rE "([0-9]+\.){3}[0-9]+|<内网主机名前缀>" <skill_dir>检查一遍

Skill生成出来了，怎么确认它真的能用？Skill-insight内置了一套递进式的验证体系，从"能不能跑"到"好不好用"。

结构合规在生成阶段自动完成，不需要手动跑。冒烟测试是你生成完立刻就能自查的：编一个合理的故障描述，看Skill能不能被激活并走完工作流。功能验证则需要真实数据来检验——这也是Skill-insight平台评测能力的用武之地，后续篇章会展开。

虽然Skill-insight会自动识别走扩展还是归纳，但输入有歧义时，一两句话的提示能省掉不少来回。

技巧1：明确数量与意图

模糊：

帮我处理一下这几份OOM文档。

精确（归并）：

请把这5份OOM问题单归纳合并成一个统一的内存故障Skill。

精确（分立）：

请基于这5份OOM问题单分别生成5个独立Skill，每个对应一类OOM触发路径。

数量和"归并还是分立"说清楚，Skill-insight不需要猜你的意图。

技巧2：明确粒度

模糊：

帮我做一个网络故障的skill。

精确：

帮我做一个网络层（L3）连通性故障的skill，重点覆盖路由、防火墙、MTU、DNS这几类，不需要包含应用层。

粒度划清，Skill-insight不会把范围扩展得太宽。

技巧3：跳过交互确认

... 使用自动模式，不要交互。

加这句话后，Skill-insight会全部采纳推荐选项，跳过审核环节。如果你希望在生成前看到并调整候选模式列表，则不要加这句。

技巧4：指明场景路径

如果你已经知道自己要做的是哪类Skill，直接告诉Skill-insight，省掉它的场景识别成本：

这是一个故障诊断类需求，请使用fault-diagnosis场景生成。

这是一个操作手册类需求（不是故障排查），请使用general场景生成。

skill-generator 对故障诊断和通用主题有两套不同的工作流，明确告知能让Skill-insight直接进入对应分支。

回顾本篇的完整路径：

第1篇：一份文档 → 一个Skill第2篇：一句话 → 扩展 → 完整Skill（vmcore）       多份问题单 → 归纳 → 通用Skill（硬盘故障）

要点回顾：

• • Skill-insight的两大能力是扩展（从稀疏到丰富）和归纳（从繁杂到简洁）。
• • 路径选择是自动的——你只管丢资料，不需要手动切模式。
• • 一句话能扩展出14个文件的专业Skill；多份案例能归纳成1个通用Pattern + 差异维度。
• • 生成后用三层验证（结构合规 → 冒烟 → 功能）把关质量。
• • 输入有歧义时，用四个技巧提升精度。

下一篇进入 Skill评测与全生命周期管理——Skill上线之后怎么观测表现、怎么用数据集驱动优化、怎么在团队内共建共享Skill库。这些都是可以展开聊的话题。

想第一时间获取后续内容？欢迎关注项目仓库并Star：

🔗 项目地址：https://gitcode.com/openeuler/witty-skill-insight

📦 npm包：@witty-ai/skill-insight^[1]

有问题？提Issue，社区一起搞定：Issue 入口^[2]

Q1：生成的Skill不满意怎么办？

skill-generator 没有单独的"生成后修改"命令，但有三条路可以走：

SKILL.md和scripts都是普通文件，OpenCode或Claude Code本身就能读写。90% 的微调用第二条路径就行，不需要什么特殊指令。

Q2：Skill-insight反复追问怎么办？

Skill-insight追问通常有两种情况：

• • 审核环节的选择题（"这几种故障模式要保留哪些？"）→ 每道题都有推荐答案（标注 ← 推荐），快速过一遍即可；或者在输入里加"使用自动模式，不要交互"，Skill-insight会全部采纳推荐选项
• • 非审核环节的追问（"请告诉我故障的更多细节..."）→ 通常意味着输入太稀疏——参考下一个问题

Q3：输入太少，生成内容空洞怎么办？

一句话是底线，但越具体越好。可以从三个层次递进：

1. 1. 领域 + 重点子场景："vmcore排查" → "vmcore排查，重点覆盖OOM、死锁、内核崩溃、硬件错误"
2. 2. 领域 + 环境约束："Kafka排查" → "Kafka 3.x单机集群排查，重点关注Consumer Lag和ISR收缩"
3. 3. 领域 + 已知故障表：直接给一张markdown表，包含名称、现象、检测方法，Skill-insight跳过扩展直接进入生成

如果生成出来的Skill主要章节都是空话或太通用，回头看输入——大概率是信息密度不够。