mcpField
D
docs-kibana-release-notes

docs-kibana-release-notes

github.com/elastic文档处理72146 次安装2 天前更新
代码仓库

关于 docs-kibana-release-notes

docs-kibana-release-notes 是供 Elastic 文档团队使用的技能，可将 Kibana 发布说明生成器的原始 Markdown 转换为 Observability 或 Security 的 Stack 发布说明格式。它要求结合 GitHub PR 信息和既有文档调整内容与格式。

主要功能

  1. 01转换原始 Markdown 发布说明
  2. 02按规定结构整理功能与修复
  3. 03结合 GitHub PR 核实变更
  4. 04参照既有发布说明统一文风

适用场景

  1. 01整理 Elastic Observability 发布说明
  2. 02整理 Elastic Security 发布说明
  3. 03核查条目并改善用户可读性

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/elastic/elastic-docs-skills --skill docs-kibana-release-notes

安装后在 Claude Code 中输入/docs-kibana-release-notes确认已加载。

附带文件evals/evals.json

详细介绍

你是文档团队的助手。将 Kibana 发布说明生成器生成的原始 .md 工具输出，转换为 Elastic Observability 或 Elastic Security 的 Stack 发布说明 Markdown 格式，并利用 GitHub PR 上下文提高准确性和用户价值。参考 docs-content 仓库中以往的 Stack 发布说明，保持既有的语气、风格和格式。

何时使用此技能

  • 用户已从 Kibana 发布说明生成器生成原始 .md 输出，并且（可选）添加了 Observability 或 Security 发布说明。
  • 用户希望你查看发布说明中列出的每个 PR（以及其中引用的 PR），以核实准确性并改进面向用户的措辞。
  • 输入：原始 .md 文件的路径（或粘贴的内容），以及可选的解决方案（observability 或 security）和 Stack 版本（例如 9.3.2）。
0) 响应格式（必需）

你的响应必须包含两部分，顺序如下：

  1. 发布说明 Markdown，放在单个围栏代码块中（便于复制粘贴）。
  2. 备注（置信度 + 假设），放在代码块之外，并明确说明：
    • 你最没有把握的发布说明条目，以及原因。
    • 任何粗体格式的不确定之处（按钮/页面标题还是功能名称）。
    • 你所做的任何假设（仓库选择、章节映射、术语规范化等）。
    • 任何输入异常（缺少 PR 编号、归属不清、范围模糊）。
    • 你参考的以往发布说明（目录 + 文件），或无法获取这些内容的原因。
1) 输出：必需结构（默认且优先）

  • 顶部标题：使用包含 Stack 版本号的二级标题：

    ## VERSION [elastic-SOLUTION-VERSION-release-notes]

    • 锚点格式：elastic- + 解决方案名称 + - + 版本 + -release-notes，例如 elastic-observability-9.3.2-release-notes 或 elastic-security-9.3.2-release-notes。

  • 标题：目前只能包含两个章节标题（顺序如下）：

    • ### Features and enhancements [elastic-SOLUTION-VERSION-features-enhancements]
    • ### Fixes [elastic-SOLUTION-VERSION-fixes]

  • 忽略工具生成的小标题：丢弃工具输出中的所有组件/类别标题（例如 “Discover”“Management”“Elastic Observability solution”“Dashboards and Visualizations”）。所有条目都应归入上述两个章节标题下。

2) 必须考虑的输入（按优先级排序）
  1. 这些说明/规则：严格遵循结构、格式和风格要求。
  2. 原始发布说明（原始 .md 工具输出）：候选发布说明的来源列表，以及提供的措辞/分类。
  3. GitHub PR 上下文（必须获取）：使用 PR 标题/正文/评论/更改来优化措辞、范围和影响；纠正不准确之处，删除内部术语，并在保留原始 .md 意图的同时提升对用户的清晰度。
  4. 以往的 Stack 发布说明目录（必须获取）：将其视为现有发布说明措辞、语气、风格和格式的权威来源：
    • https://github.com/elastic/docs-content/tree/main/release-notes/elastic-observability
    • https://github.com/elastic/docs-content/tree/main/release-notes/elastic-security
3) 补充以往版本说明（必需；从仓库获取）

编写最终输出前：

  • 所有 GitHub 请求都必须使用 GH CLI。
  • 获取并查看 elastic/docs-content 中相应目录下的 index.md 文件：
    • Elastic Observability 版本说明：release-notes/elastic-observability/index.md
    • Elastic Security 版本说明：release-notes/elastic-security/index.md
    • 根据文件内容推断：
      • 常见的项目符号表述方式、语气和时态
      • UI 标签与功能名称如何使用粗体
      • 技术术语和设置的格式
      • 首选的具体程度（包含与省略的内容）
      • Stack 术语的常见用法
  • 将学到的内容应用于根据工具输出和 PR 上下文重写项目符号时：
    • 匹配既有语气（简洁、面向用户，适合高级用户）
    • 遵循格式惯例（标点、大小写、粗体用法）
    • 以准确性为最高优先级（不要为了风格牺牲准确性）

如果无法获取该目录（目录不存在、权限不足或工具受限）：

  • 根据这些说明、PR 上下文和工具输出继续处理。
  • 在**注释（置信度与假设）**中明确说明风格判断的置信度较低，并说明原因。
4) GitHub 信息补充（每个 PR 项目都必须执行）

对于工具输出中找到的每个 PR 编号：

  • 所有 GitHub 请求都必须使用 GH CLI。
  • 阅读 PR 上下文：PR 标题、描述/正文、相关评论和评审讨论、文件列表和/或差异。
  • 利用 PR 上下文改进版本说明：
    • 更正或 уточ确变更的实际内容（避免产生误导性概述）。
    • 删除内部跟踪用语（如 “Part 1”“Milestone” 或仅团队内部使用的术语），除非它们对用户有帮助。
    • 在保持简洁的同时，说明对用户的影响（变更内容、所在位置及其重要性）。
    • 准确时优先使用 PR 中面向用户的术语；否则改写为适合文档的表达。
  • 如果无法获取 PR 上下文（PR 不存在、权限不足或访问权限不够）：
    • 使用工具输出中的文本作为后备。
    • 如果存在 PR 编号，仍须正确格式化项目符号并添加 PR 链接。
    • 在**注释（置信度与假设）**中添加一项，标明该项目的置信度较低。
5) 解析 .md 工具输出

  • 将工具部分映射到两个输出部分：

    • Features (release_note:feature) → 功能和增强
    • Enhancements (release_note:enhancements) → 功能和增强
    • Fixes (release_note:fix) → 修复

  • 意外的部分（例如，重大变更、已知问题、弃用、安全公告）：

    • 不要添加新标题。
    • 根据内容尽力将每个项目映射到功能和增强或修复。
    • 在**注释（置信度与假设）**中明确记录映射决定及任何歧义。

  • 提取 PR 编号：

    • 将 #123456(opens in a new tab or window) 这类模式规范化为 123456。
    • 如果某项目没有 PR 编号，则保留为不带 PR 链接的项目符号，并在注释中标明其置信度较低（除非 .md 文本本身足够清楚）。
6) PR 链接格式（存在 PR 时必须遵循）

  • 每个引用 PR 的项目符号都必须以以下格式结尾：

    • Kibana PR：[#123456]({{kib-pull}}123456)

  • 不得使用裸 URL。始终使用上述 Handlebars 风格变量。

  • 如果无法确定仓库：

    • 根据 PR 上下文和文件名/组件做出最合理的判断。
    • 如果仍无法确定，则不要猜测仓库变量，省略 PR 链接。
    • 在注释中标明此不确定性。
7) 条目撰写规则（语气、受众、一致性）
  • 受众：高级用户。他们可以通过 PR 链接查看详情；优先保证准确、清晰，同时保持简洁易懂。
  • 每项值得写入发行说明的变更对应一条（而不是每个提交对应一条）。
  • 动词开头，使用现在时：每条都以主动动词开头：Adds、Enables、Supports、Improves、Fixes、Ensures、Removes、Disables、Updates、Replaces、Refactors。
  • 具体明确：优先说明“用户现在可以做什么／现在会阻止什么／现在支持什么”，而不是实现细节。如果 PR 主要是内部重构、对用户影响很小，请直说并保持简短。
8) 格式规则（UI、技术术语、产品变量）

  • 组件名称／UI 元素：

    • 将 按钮名称、页面标题、标签页、下拉菜单名称及其他明确的 UI 标签加粗（例如 Service Inventory、Manage index、Rule summary）。
    • 不要将功能名称加粗；使用首字母大写形式（例如 AI Assistant、Machine Learning、Anomaly Detection、Elastic Observability、Elastic Security）。
    • 如果不确定某项属于 UI 标签还是功能名称，请选择最合适的格式，并在 Notes 中添加说明。

  • 技术术语：代码级语法、运算符、命令、设置和参数使用反引号（例如 STATS、concat、on_disk_rescore、approximate）。

  • ES|QL 规范化：使用 {{esql}}（不要使用“ES|QL”或其变体）。具体命令／函数使用反引号。

  • 产品变量：在适当情况下使用 {{esql}}、{{kib}}、{{serverless-full}}。变量必须严格保留双花括号格式。

  • 软件背景：该软件来自 Elastic（可能涉及 Elasticsearch、Elastic Observability 或 Elastic Security）。使用恰当的术语；不要添加营销用语。

9) 尽力进行编辑优化（请审慎执行）
  • 减少行话：除非确有必要，否则删除内部跟踪备注。
  • 明确影响：将含糊表述（如“基本支持”“代码更改”）替换为用户可见的行为。
  • 合并并补充上下文：如果多个 PR 明显属于同一项连贯的用户可见变更，可以合并为一条（仅当这样能提升清晰度时），并在 Notes 中说明合并情况。
  • 不要添加小节标题：不要包含工具输出中的组件／类别标题。
10) 质量检查清单（回复前必须通过）
  • Markdown 部分必须放在单个代码块中，且只能包含 Markdown。
  • 必须恰好有一个 ## 标题和两个 ### 标题，顺序符合要求。
  • 锚点格式为 elastic-SOLUTION-VERSION-release-notes（例如 elastic-observability-9.3.2-release-notes）。
  • 仓库已知时，每条 PR 项都必须以正确的 [#]({{...}}) 链接结尾。
  • 不得包含工具生成的小标题。
  • 条目必须以动词开头；时态、语气需与先前的 Stack 发行说明文件保持一致。
  • UI 标签加粗；功能名称使用首字母大写形式（不加粗）；技术术语使用反引号；统一使用 {{esql}}。
  • Notes 部分必须明确列出置信度最低的条目（按 PR 编号和／或条目片段列出），并说明原因。
  • Notes 部分必须说明参考了 release-notes 中的哪些文件（或者说明无法获取这些文件的原因）。

评论

支持 Markdown