# Support Kb Article Writer

> 当工单已解决/同类问题反复出现/需发布临时绕过方案或对外公告已知问题、要把它沉淀为可自助检索的知识库文章时使用；做按文章类型（How-to/排障/FAQ/已知问题/参考）模板产出含元数据、SEO 检索优化标题与发布注记的发布就绪 KB 草稿；不适用于面向单个客户的工单回复、内部 Runbook、事故复盘报告本身；触发词：知识库文章、KB article、帮助中心、自助文档、FAQ、排障文档、已知问题、workaround、客户文档

- Skill: `findscripter/support-kb-article-writer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add findscripter/support-kb-article-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/findscripter/support-kb-article-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- License: Apache-2.0
- Author: findscripter (https://skillmd.com/u/findscripter)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/findscripter/support-kb-article-writer

---

# 支持知识库文章撰写

## 何时使用

当一次工单解决、常见问题或临时绕过方案值得沉淀为**客户可自助检索**的知识库（KB）文章时使用。典型触发：

- 一个工单的解决方案值得文档化以减少重复工单。
- 同一个问题反复被问（内容缺口）。
- 某绕过方案需要对外发布。
- 某已知问题需要主动告知客户。

**不该用的边界**：

- 面向单个客户的工单/邮件回复（那是一次性沟通，不进 KB）。
- 内部 Runbook / 排障手册（面向工程师、含敏感内部细节）。
- 事故复盘 / Postmortem 报告本身（KB 文章只引用其链接，不写根因分析）。
- 营销博客、产品发布说明。

## 步骤

1. **解析源材料**，识别五要素：原始问题是什么 / 解决方案或答案是什么 / 影响谁（用户类型、套餐、配置） / 频率（一次性 vs 反复） / 适配哪种文章类型。
2. **拉取上下文（若给了工单号）**：从支持平台拉完整工单线程与内部备注；查 KB 是否已有相似文章（决定**更新 vs 新建**）；查关联 bug/需求。
3. **选文章类型并套模板**（见示例的 5 类模板）。
4. **按检索优化写作**：标题用客户语言、首句平实复述问题、嵌入精确报错原文、加同义词与别名。
5. **输出草稿 + 元数据 + 发布注记**（见指令的输出结构）。
6. **给后续动作**：是否检查重复文章 / 调整受众技术深度 / 写配套文章 / 出内部增强版。

## 指令

**判定「更新已有 vs 新建」**：产品变更需刷新步骤、文章大体正确仅缺细节、客户反馈某节困惑、发现更优方案 → **更新**；新功能/新领域、解决工单暴露空缺、旧文混入太多主题需拆分、不同受众需另一种讲法 → **新建**。

**检索优化（文章找不到 = 无用）**：

- 标题要具体含客户搜索词：用「如何用 Okta 配置 SSO」而非「SSO 设置」；用「修复：仪表盘显示空白页」而非「仪表盘问题」；含**精确报错原文**「报错：导入数据时 'Connection refused'」。
- 用客户语言而非内部术语：「登录不了」而非「认证失败」。
- 加同义词（删除/移除、导出/下载、仪表盘/首页）与多种问法。

**首句公式**（按类型）：How-to=「本指南教你如何〈完成 X〉」；排障=「如果你看到〈症状〉，本文说明如何修复」；FAQ=「〈客户原话问题〉？答案如下」；已知问题=「部分用户遇到〈症状〉，以下是已知情况与绕过方法」。

**格式规则**：用 H2/H3 分节；顺序步骤用有序列表、非顺序用无序列表；UI 元素名/关键词加粗；命令、API、报错、配置值用代码块；对比/选项用表格；警告与提示用 callout；段落 2-4 句封顶；一节只讲一件事，混了就拆。

**输出结构**：

```
## KB 文章草稿
**标题:** [客户语言、含搜索词]
**类型:** [How-to / 排障 / FAQ / 已知问题 / 参考]
**分类:** [产品域]   **标签:** [可检索标签]   **受众:** [全部/管理员/开发者/某套餐]
---
[正文 — 按下方对应类型模板]
---
### 发布注记
- 来源: [工单号/对话/内部讨论]
- 待更新的已有文章: [若有重叠]
- 需谁评审: [技术准确性需 SME 把关时]
- 建议复查日期: [何时回看]
```

## 示例

**How-to 模板**：`# 如何〈完成任务〉` → 概览 / 前置条件 / 步骤（每步动词开头、给精确路径如「进入 设置 > 集成 > API 密钥」、说明操作后应看到什么如「应出现绿色确认横幅」）/ 验证是否成功 / 常见问题 / 相关文章。

**排障模板**：`# 〈用户看到的问题〉` → 症状（先写症状，客户按看到的搜）/ 原因（简短非术语）/ 解决（方案 1 主修复、方案 2 备选）/ 预防 / 仍有问题？（指向支持）。多方案时最可能的修复放最前。

**FAQ 模板**：`# 〈客户原话问题〉` → 直接答案（1-3 句、首句即答）/ 细节 / 相关问题。需要走查的就该是 How-to 而非 FAQ。

**已知问题模板**：

```markdown
# 已知问题：〈简述〉
**状态:** [排查中 / 有绕过方案 / 修复中 / 已解决]
**影响:** [谁/什么受影响]   **最后更新:** [日期]
## 症状
[用户遇到的现象]
## 绕过方案
[绕过步骤，或「暂无绕过方案」]
## 修复时间线
[预期修复日期或当前状态]
## 更新记录
- [日期]: [更新]
```

状态务必保持最新（陈旧的已知问题最毁信任）；修复上线后标记「已解决」并保留 30 天供仍按旧症状搜索的客户。

## 注意事项

- **一文一题**：一篇文章只解决一个问题，过长就拆，用链接互串。
- **可检索压倒一切**：客户搜不到的文章等于不存在；把精确报错原文与客户口语词放进标题和概览。
- **互链方向**：排障→How-to（「配置步骤见〈如何配置 X〉」）、How-to→排障、FAQ→详细指南、已知问题→绕过方案；KB 内用相对链接（重构后更稳）；避免无意义循环链接。
- **激进维护**：错的文章比没有文章更糟。建议节奏——已知问题状态每周更新、月度排查 6 个月未更新的陈旧内容、季度审计高流量文章准确性与内容缺口。
- **技术准确性**：涉及命令/配置/API 的文章需 SME 评审；步骤要自己实测或用近期工单解决过程核对。
- 引用的事实（版本号、影响面、报错）应来自工单与系统，不确定要标注。
- 本条采编自 anthropics/knowledge-work-plugins（Apache-2.0），保留其 5 类文章模板、检索优化（客户语言标题/精确报错/同义词）、首句公式、格式规则、更新 vs 新建判据、维护节奏与文章生命周期等关键约束。

## 互见

- related：`internal-comms` —— 对内/对外的事故与状态公告写法可复用，已知问题文章可引用其 status update。
- related：`ai-customer-support` —— 一线工单解决方案是 KB 文章的主要素材源，KB 反过来降低重复工单。
- combines_with：`ai-customer-support` —— 工单解决 → 沉淀 KB → 自助分流，形成支持闭环。