name: knowledge-base-article-writing description: 基于支持数据、产品文档和常见客户问题，撰写清晰、可检索的帮助中心文章与 FAQ 条目。 license: MIT metadata: author: community version: 1.0.0

小葱技能站7w4.net发现了升级插件。

知识库文章撰写

产出打磨精良的帮助中心文章和 FAQ 条目，通过为客户提供清晰、自助式的答案来分流支持工单。本技能将支持工单模式、产品变更和常见问题转化为结构化的文章，针对可读性、可检索性和可扫描性进行优化，并遵循文档最佳实践——分步指南、故障排查流程与参考资料。

工作流

1. 从支持数据中识别主题 — 挖掘支持工单趋势、搜索分析（客户搜索却找不到的内容）和 CSM 反馈，找出影响最大的主题。按工单量优先（覆盖前 10 大疑问簇的文章分流的工单最多）、主题复杂度（复杂主题从书面指南中获益最多）和新近度（新功能或近期变更需要立即文档化）。

2. 研究解决方案 — 从工程文档、内部 wiki、产品规格和主题专家处收集权威答案。在产品中亲自端到端测试该工作流以验证准确性。记录当前产品版本中出现的确切 UI 文本、按钮标签和导航路径。注明任何前置条件、所需权限或套餐层级限制。

3. 构建文章结构 — 遵循一致的模板：标题（以行动为导向，匹配客户搜索方式）、摘要（1–2 句用于扫描的答案）、前置条件（读者开始前需要什么）、步骤（编号，每步一个动作，含预期结果）、故障排查（常见错误及其修复）、相关文章（相邻主题的链接）。保持层级扁平——主要章节用 H2，H3 谨慎使用。

4. 添加可视化辅助与代码示例 — 对 UI 密集工作流附截图（用与步骤对应的编号标注），对 API 或 CLI 工作流附代码片段（带语言标签、复制按钮和预期输出），对架构或流程说明附图表。每张图片都应有替代文本。每个代码块都应经过测试且可运行。

5. 针对搜索优化 — 使用客户实际使用的确切措辞撰写标题（检查搜索分析）。在首句中前置关键词。为类别、产品区域和套餐层级添加元标签。将常见的替代表述作为"又称"一行或文章元数据中。保持 URL 简洁、人类可读。

6. 审查准确性与清晰度 — 请主题专家核实技术准确性。运行针对八年级阅读水平的可读性检查。确保每步都能被无任何先验上下文的人测试。检查截图是否与当前 UI 匹配。验证所有链接。设定复核日期（通常为 90 天，或下次影响该主题的产品发布时）。

使用方式

描述文章主题、目标受众，以及要包含的任何具体细节。Agent 会写出一篇完整、可直接发布的文章。

为我们写一篇帮助中心文章："如何用 SAML 配置 SSO。" 目标受众是 IT 管理员。
我们的产品支持 Okta、Azure AD 和 OneLogin。包含常见 SAML 错误的故障排查。

示例

示例 1：操作指南文章 — SAML 的 SSO 配置

输入： 面向 IT 管理员的 SSO/SAML 配置指南。

输出：

如何用 SAML 配置单点登录（SSO）

启用基于 SAML 的 SSO，让你的团队可以使用公司的身份提供商登录。支持的提供商：Okta、Azure AD 和 OneLogin。

前置条件 - 你账户中的 Admin 角色（Settings → Team → Roles 中你的名字旁显示"Admin"） - 可访问你的身份提供商的管理控制台 - 你的账户必须在 Enterprise 套餐上

步骤

1. 前往 Settings → Security → Single Sign-On 并点击 Configure SSO。

[截图：Settings 页面，Security 标签页高亮，SSO 区域可见]

1. 从下拉菜单中选择你的身份提供商：Okta、Azure AD 或 OneLogin。

2. 复制屏幕上显示的值——你在身份提供商处将需要这些值：

3. ACS URL： https://app.example.com/auth/saml/callback
4. Entity ID： https://app.example.com/saml/metadata

5. RelayState： 留空，除非使用自定义落地页

6. 在身份提供商的管理控制台中，使用第 3 步的值创建一个新的 SAML 应用。

Okta： Applications → Create App Integration → SAML 2.0 → 粘贴 ACS URL 和 Entity ID。

Azure AD： Enterprise Applications → New Application → Create your own → SAML → Basic SAML Configuration → 粘贴值。

OneLogin： Applications → Add App → SAML Custom Connector → Configuration → 粘贴值。

1. 从身份提供商处下载 Federation Metadata XML 文件，并上传到 SSO 配置页面。

2. 设置所需的属性映射： email → user.email (Required) firstName → user.firstName (Required) lastName → user.lastName (Required) role → user.role (Optional — maps to app roles)

3. 点击 Test Connection。新浏览器标签页打开。用你的身份提供商凭据登录。若成功，将看到"SSO connection verified."

4. 切换 Enforce SSO 以要求所有团队成员通过你的身份提供商登录。非 SSO 登录将在 24 小时宽限期后禁用。

故障排查

相关文章 - 管理团队角色与权限 - 配置 SCIM 用户预配 - 配置多因素身份验证

示例 2：FAQ 条目 — 账单问题

输入： 涵盖套餐变更、发票和退款的常见账单 FAQ。

输出：

账单 FAQ

关于套餐、发票、付款和退款最常见问题的答案。

如何升级或降级我的套餐？

前往 Settings → Billing → Plan 并点击 Change Plan。选择新套餐并确认。升级立即生效，你将按当前计费周期剩余天数按比例计费。降级在下个计费周期开始时生效——在此之前你仍可使用当前套餐的功能。

在哪里可以找到我的发票？

所有发票都在 Settings → Billing → Invoice History。点击任意发票查看或下载 PDF。每笔扣费后 24 小时内，发票也会通过邮件发送给在档的账单联系人。

如何更新付款方式？

前往 Settings → Billing → Payment Method 并点击 Update。我们接受 Visa、Mastercard、American Express 和 ACH 银行转账（仅年度套餐）。你的新付款方式将用于所有未来扣费。

我可以获得退款吗？

如果你不满意，我们在任何扣费后 14 天内提供全额退款。超过 14 天后，我们发放用于未来计费的比例抵扣。要申请退款，请发送邮件至 billing@example.com，附上你的账户邮箱和发票号。退款在 5–7 个工作日内处理。

如果付款失败会怎样？

我们在第 1、3、7 天重试失败的付款。每次失败后你都会收到邮件通知。如果 14 天内未解决，你的账户将降级到免费层级。你的数据保留 90 天——随时升级以恢复完整访问。

你们提供年度账单折扣吗？

是的。在 all paid plans 上，年度账单相比月度账单节省 20%。随时可从 Settings → Billing → Plan 切换到年度账单——选择"Annual"，你的节省会立即生效，并对任何剩余的月度余额按比例抵扣。

相关文章 - 理解你的发票行项目 - 设置 ACH 银行转账付款 - 管理多个计费账户

最佳实践

• 标题使用匹配客户搜索方式的问题或行动短语——"如何配置 SSO"胜过"SSO 配置指南"，因为客户用自然语言搜索。
• 一篇文章，一个主题。如果一篇文章涵盖两个不同的工作流，就拆分它。搜索"导出数据"的客户不应落到同时涵盖"导入数据"的页面——即便它们对你来说似乎相关。
• 每篇文章都以一句直接回答问题的摘要开头。客户是扫描而非阅读——如果答案在第一行，即使他们不再往下读也能获得价值。
• 使用与 UI 标签完全一致的术语。如果按钮显示"Configure"，不要在文章中写"Set Up"。文档与 UI 的不一致会造成困惑并损害信任。
• 在每篇文章上包含"最后验证"日期，并在其覆盖的产品区域在变更日志中收到更新时建立自动提醒。
• 用两个指标跟踪文章效果：搜索到查看率（客户能找到它吗？）和分流率（查看后 30 分钟内客户是否开了工单？）。

边缘情况

• 撰写与发布之间产品 UI 发生变化 — 始终最后再截图，在文章文本定稿之后。在图片替代文本中包含产品版本号，以便在审计时更容易识别过时的截图。
• 仅在特定套餐可用的功能 — 在顶部添加醒目横幅："此功能在 Pro 和 Enterprise 套餐上可用。"不要把套餐限制埋在第 4 步之后，在读者已投入时间之后才出现。
• 多语言知识库 — 先以英文撰写规范文章，再进行本地化。不要未经人工审查就机器翻译并发布——技术术语和 UI 标签必须与本地化的产品界面匹配。
• 已弃用的功能 — 不要删除已弃用功能的文章。添加带 sunset 日期的弃用横幅，并链接到替代文章。使用旧套餐的客户可能仍需要旧文档。
• 来自多个来源的冲突信息 — 当内部文档与产品的实际行为不一致时，产品行为才是事实来源。在产品里测试，记录实际发生的情况，如果行为有误则提交 bug。

这个Skill质量不错，提供了清晰的写作流程和丰富的示例参考，能够帮助你写出结构完整、格式规范的知识库文章。优点是示例详细、最佳实践实用；不足之处是引导方式较为单一，缺少互动迭代机制，写作质量保障方法也不够具体。对于需要撰写帮助文档的用户来说，是一个有参考价值的参考模板，但使用体验还有优化空间。