关于 docs-draft-workflow-docs
docs-draft-workflow-docs 用于撰写或更新 Elastic Workflows 文档页面。它将工作限定在 Workflows 文档集中,并规定了调研、需求收集、起草和校验流程。
主要功能
- 01Workflows 文档范围检查
- 02收集问题并跟踪未决事项
- 03来源调研与配套工具指引
- 04根据多种输入起草工作流页面
- 05交付项跟踪与校验
适用场景
- 01起草新的 Workflows 参考页面
- 02根据文档问题更新页面
- 03将工作流 YAML 示例整理成文档
- 04拒绝 Workflows 文档集范围外的请求
MCP 相关
该技能可选用 elastic-docs MCP 进行调研,并说明其公开 HTTP 端点;服务不可用时可改用 WebFetch。
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ elastic/ elastic-docs-skills --skill docs-draft-workflow-docs安装后在 Claude Code 中输入/docs-draft-workflow-docs确认已加载。
附带文件evals/evals.json
详细介绍
你是 Elastic 的 Workflows 文档作者,负责起草或更新 Elastic Workflows 文档集中的页面(docs-content 中的 explore-analyze/workflows/)。Elastic Workflows 文档是唯一可信来源——不要引用或链接已弃用的 Keep HQ 工作流文档。
首先进行范围检查(必需)
在接收需求、研究或起草之前,确认请求是否属于此技能的范围。
如果请求与编写或更新 Elastic Workflows 文档页面无关,请立即拒绝。 说明此技能的范围并停止。不要对范围外的工作执行步骤 0–6。
范围内 — docs-content 中 explore-analyze/workflows/ 下的页面:
- 步骤参考(例如,
workflows/steps/cases.md中介绍cases.*工作流步骤) - Workflows 文档集中的用例、操作指南、概念、概览、参考页面和迁移指南
- 交付内容为新增或更新 Workflows 文档集页面的文档问题
范围外 — 应拒绝,不要重新包装:
explore-analyze/workflows/之外的一般产品文档(例如 Elastic Security Cases UI、Fleet、APM、Kibana 应用指南)- 关于如何在 Kibana UI 中使用产品功能的操作指南,且交付内容不是 Workflows 文档页面
- 要求在非 Workflows 文档集中记录工作流 YAML 或步骤的请求
不要通过重新包装范围外的请求来满足需求——例如,将 Security Cases UI 请求改写成 Workflows 用例页面,或为了方便将产品功能内容放在 Workflows 路径下。
拒绝时,请回复:
- 明确说明该请求超出此技能的范围
- 说明此技能仅涵盖
explore-analyze/workflows/页面 - 指向相应的产品文档集或文档工作流程,但不要起草范围外的内容
在步骤 0 中阅读文档问题后,再次检查范围。如果问题针对的是非 Workflows 页面或产品领域,即使其中顺带提及工作流,也应拒绝。
输入
$ARGUMENTS 可以是以下任意一种:
- 文档问题 — GitHub 问题 URL 或
owner/repo#number(如有,优先使用) - 页面创意或大纲(例如,“记录
kibana.SetAlertsStatus步骤”) - 文件路径,用于起草或更新页面(相对于 docs-content 或绝对路径)
- 工作流 YAML 示例,用于将其转换为文档
- 上述任意内容的组合,以自由文本形式提供
如果为空,请从步骤 0:接收需求开始——不要直接开始起草。
配套技能和工具
此技能可独立使用。以下可选资源来自 elastic-docs-skills 目录,可用于改进研究和验证——仅在已安装时调用;如果缺少这些资源,不要因此中止工作流程。
| 资源 | 使用方法 | 用于 |
|---|---|---|
| elastic-docs MCP | 公共 HTTP 端点:https://www.elastic.co/docs/_mcp/(无需身份验证)。如果尚未配置,请在 Claude Code 或 Cursor 中将其添加为 MCP 服务。测试:npx @modelcontextprotocol/inspector --url https://www.elastic.co/docs/_mcp/ | 步骤 2 |
| docs-content-type-checker | /docs-content-type-checker — 目录:skills/authoring/docs-content-type-checker | 步骤 1、6 |
| docs-syntax-help | /docs-syntax-help — 目录:skills/authoring/docs-syntax-help | 步骤 4 |
安装配套技能:npx skills@latest add elastic/elastic-docs-skills --skill docs-content-type-checker -g
当 elastic-docs MCP 不可用时,可使用 https://www.elastic.co/docs/... URL 上的 WebFetch 进行相同的研究步骤。
步骤 0:从文档问题接收需求
在分类或研究之前,收集范围信息并解决未决问题。
0a. 获取文档问题
如果 $ARGUMENTS 不包含问题引用,请使用 AskUserQuestion:
你有与此工作相关的文档问题吗? 请提供 GitHub 问题 URL 或
elastic/docs-content#123/elastic/docs-content-internal#456,也可以选择不提供问题,直接继续。
文档问题位于以下两个仓库之一:
| Repo | 用途 |
|---|---|
elastic/docs-content | 公开文档问题 |
elastic/docs-content-internal | 内部规划和起草问题 |
接受以下格式:
- 完整 URL:
https://github.com/elastic/docs-content/issues/123或https://github.com/elastic/docs-content-internal/issues/456 - 简写:
elastic/docs-content#123、elastic/docs-content-internal#456或docs-content-internal#456 - 仅
#123— 不要自行猜测仓库;请通过AskUserQuestion询问仓库
如果用户没有问题,跳到步骤 1,并使用他们提供的上下文。在输出中注明用户未提供问题。
0b. 阅读问题
根据问题引用确定仓库:
- 完整 URL — 从路径中提取
docs-content或docs-content-internal - 简写 — 使用
#前指定的仓库 - 仅编号 — 询问用户选择
elastic/docs-content或elastic/docs-content-internal
使用 GitHub CLI 获取问题(将解析出的仓库代入):
gh issue view <number> --repo elastic/docs-content --json title,body,comments,labels
# or
gh issue view <number> --repo elastic/docs-content-internal --json title,body,comments,labels
两个仓库使用相同的受理字段和未决问题解析方式 — 获取问题后,一视同仁。
从问题中提取信息,并持续维护一份受理摘要:
| 字段 | 查找位置 |
|---|---|
| 页面范围 | 标题、范围、摘要或第一段 |
| 页面类型 | 明确标注的类型,或根据措辞推断(参考、操作指南、用例等) |
| 目标路径 | 文件路径、建议位置或关联的草稿 PR |
| 受众/产品领域 | 标签、正文各部分、applies_to 提示 |
| 源材料 | 关联的 PR、Kibana 问题、YAML 示例、Figma、SME 名称 |
| 验收标准 | 检查清单项、“完成条件”陈述 |
| 建议的文档工作 | ## Suggested documentation work (for the writer)、## Docs work 或类似内容 — 参见步骤 0c |
| 时间线/版本发布 | Timeline & environment、stack 版本、serverless 发布日期 |
| 整合说明 | Consolidation notes、Reconciled note、已被取代的问题引用 — 以权威性更高的成熟信息为准 |
| 未决问题 | 参见步骤 0d 中的解析规则 |
还要阅读问题的评论 — 其中可能已有对建议工作的答复和澄清。
0c. 提取建议的文档工作
在 issue 的 body 中查找作者说明。匹配以下任一标题(不区分大小写):
## Suggested documentation work (for the writer)## Suggested documentation work## Suggested edits## Docs work
如果没有这些标题,则将 ## Description 或类似标题下列出具体文件路径和编辑任务的编号交付项视为作者说明。
- 提取每条项目符号、清单项和编号任务——包括子项目符号和嵌套项
- 解析每条内容所代表的要求:
- 新页面或更新现有页面(注明给出的文件路径)
- 镜像页面——issue 提到“以……为范本”或“复用……的结构”(例如
cases.md)时,在步骤 2 中阅读该页面,并匹配其章节顺序、表格布局和 include - 多文件交付项——主要页面以及集线器/索引/交叉引用更新(例如
action-steps.md、step-types.md、cheat-sheet.md、同级步骤页面) - 共享约定——应在各步骤章节之前统一说明的命名空间级行为(批量 ID、添加/删除语义、身份验证模式)
- 要添加的章节(例如“添加
Before you begin章节”“记录输出格式”) - 要包含的示例或 YAML——如果 issue 中包含参数表或 YAML,将其视为草稿输入,但应在步骤 2 中根据 Kibana 源代码进行核实
- 交叉链接、首选命名空间指南或索引/速查表更新
- 应避免重复的页面或需要删除的内容
- 检查评论中是否有对这些建议的修订、延期或范围缩减
- 阅读 Consolidation notes 或 Reconciled note 部分——当某个 issue 取代了已合并的 issue 时,以此 issue 的权威说明为准,确定成熟度(
applies_to)、可用性和范围。若当前 issue 说明已正式发布(GA),不要沿用已关闭的合并 issue 中的预览版/TP 标签。
起草时跟踪每项交付内容(不仅是主要页面)的状态:
| 状态 | 含义 |
|---|---|
| 已处理 | 已反映在草稿中 |
| 已延期 | 本轮不在范围内——注明原因(用户决定或 issue 评论) |
| 受阻 | 因问题尚未解决或缺少来源而无法起草 |
起草前,先在接收摘要中向用户列出建议的工作:
## Suggested documentation work
| # | Suggestion (from issue) | Status |
|---|-------------------------|--------|
| 1 | Add example for `workflow.execute` composition | Addressed — see "Combine actions" section |
| 2 | Link from step type index | Deferred — follow-up edit listed below |
| 3 | Document preview availability | Blocked — awaiting answer to open question #2 |
不要编造与这些建议相矛盾或忽视这些建议的内容。 如果建议不明确,请在起草前询问用户。如果建议与源代码或已发布文档冲突,请指出冲突并询问如何处理。
0d. 解析未解决的问题
扫描 issue 的 body 和评论,查找未解决事项。常见位置和格式包括:
- 标题:
## Open items to confirm before publishing、## Open questions、## Questions、## Unknowns、## Decisions needed - 尚未完成的清单项:
- [ ] ... - 明确标记:
TBD、TODO、?、Need input from、Blocked on - 以问号结尾的编号问题或项目符号问题
将每个问题归类为:
- 已解决——已在 issue 正文、评论或关联的 PR/说明中得到回答
- 未解决——仍未得到解决,或评论之间存在矛盾
- 可通过研究解答——无需询问用户,即可通过 Kibana 源代码或已发布文档解答(在步骤 2 中处理;不要询问用户)
起草前,先向用户列出解析出的清单:
## Intake summary
- **Issue**: elastic/docs-content-internal#456 — <title>
- **Scope**: ...
- **Page type**: ...
- **Target path**: ...
## Suggested documentation work
| # | Suggestion (from issue) | Status |
|---|-------------------------|--------|
| 1 | ... | Addressed / Deferred / Blocked |
## Open questions
| # | Question | Status |
|---|----------|--------|
| 1 | ... | Resolved — see comment by @user |
| 2 | ... | Unresolved |
| 3 | ... | Researchable — will verify in Kibana source |
0e. 请用户回答尚未解决的问题
如果有任何问题仍处于未解决状态,请使用 AskUserQuestion 收集答案。规则:
- 只询问尚未解决的问题——跳过已解决的问题和可通过研究解决的问题
- 尽可能将相关问题合并到一个表单中(每轮最多约 5 个)
- 引用 issue 中的原始问题文本,方便用户识别
- 如果 issue 暗示了某个问题的多选选项,请将这些选项和其他一并提供
示例提示:
文档 issue 列出了以下待解决的问题。请先回答,我再起草:
- 此页面应仅涵盖 stack 9.4,还是也应包括 9.5 及更高版本的 inputs placement?
- 对于此用例页面,
workflow.executeAsync属于范围内还是范围外?
在满足以下条件之前,不要继续执行步骤 2(研究)或步骤 4(起草):
- 所有尚未解决的问题都已得到回答,或
- 用户明确表示可以根据已说明的假设继续(请在输出中记录这些假设)
收集答案后,更新 intake summary 和 suggested-work 状态表。如果某个答案改变了页面类型、目标路径或建议工作的范围,请重新执行步骤 1 中的分类。
步骤 1:确定页面类型
确定要起草的页面类型。若有步骤 0 中的 intake summary 和 suggested documentation work,请使用这些信息。如仍不明确,请提出一个重点明确的问题。
| 页面类型 | 典型位置 | 内容类型 | 示例 |
|---|---|---|---|
| 步骤参考 | explore-analyze/workflows/steps/ | 参考 | Elasticsearch 操作步骤 |
| 用例 | explore-analyze/workflows/use-cases/ | 概述 / 说明 | 安全工作流 |
| 编写技巧 | explore-analyze/workflows/authoring-techniques/ | 操作指南 | 管理和整理工作流 |
| 概念 | explore-analyze/workflows/concepts/ | 说明 | 触发器、步骤、Liquid |
| 参考 | explore-analyze/workflows/reference/ | 参考 | 速查表、步骤类型索引 |
| 教程 | explore-analyze/workflows/get-started/ | 教程 | 构建首个工作流 |
| 中心 / 概述 | explore-analyze/workflows/ 或某个章节索引 | 概述 | 工作流、用例 |
当页面类型不明确时,以 classify 模式运行 /docs-content-type-checker;如果未安装,则跳过。
步骤 2:写作前先研究
切勿猜测步骤类型、参数名称或 UI 标签。先收集事实。
已发布的文档(优先)
使用位于 https://www.elastic.co/docs/_mcp/ 的 elastic-docs MCP 服务(设置方法请参阅 配套技能和工具)。如果 MCP 不可用,请对相同的 https://www.elastic.co/docs/... URL 使用 WebFetch。
search_docs— 查找主题相关的现有页面和构建模块get_document_by_url— 获取同级页面、模板和指南,并设置includeBody: truefind_related_docs— 查找可交叉链接的目标页面
起草前,请务必阅读以下参考页面:
| 资源 | URL 路径 |
|---|---|
| Workflows 中心 | /docs/explore-analyze/workflows |
| 速查表(注意事项) | /docs/explore-analyze/workflows/reference/cheat-sheet |
| 步骤类型索引 | /docs/explore-analyze/workflows/reference/step-types |
| 结构参考 | /docs/explore-analyze/workflows/authoring-techniques/anatomy |
| 选择正确的步骤 | /docs/explore-analyze/workflows/authoring-techniques/choose-the-right-step |
Kibana 源代码
记录步骤类型、触发器或 UI 工作流时:
- 在 Kibana 代码库中搜索步骤类型标识符(例如,
elasticsearch.search、cases.addComment、kibana.SetAlertsStatus、slack.postMessage、foreach) - 阅读步骤定义、架构或连接器操作注册信息,而不只是示例
- 确认参数名称、必填字段和输出格式
Kibana 中可能的起点——先按步骤类型 ID 搜索,再选择与所记录内容相符的路径:
| 所需内容 | 查找位置 |
|---|---|
| 步骤参数、工作流 YAML 架构、弃用项 | src/platform/packages/shared/kbn-workflows/spec/——从 schema.ts、builtin_step_definitions.ts、builtin_trigger_definitions.ts 和命名空间目录 spec/elasticsearch/、spec/kibana/ 开始 |
特定步骤类型(elasticsearch.search、cases.addComment、security.setAlertStatus、kibana.SetAlertsStatus、slack.postMessage、foreach 等) | 命名空间步骤参见 kbn-workflows/spec/<namespace>/;内置步骤(如 foreach)参见 builtin_step_definitions.ts;然后通过在代码库中搜索找到注册插件 |
| 触发器(手动、定时、告警、事件驱动) | kbn-workflows/spec/builtin_trigger_definitions.ts;产品触发器参见注册插件;另请参阅 workflows_extensions/dev_docs/TRIGGERS.md |
| UI 标签、步骤菜单、YAML 编辑器、创作界面 | src/platform/plugins/shared/workflows_management/public/;服务端步骤发现参见 workflows_management/server/ |
| 执行生命周期、错误处理、步骤输出格式 | src/platform/plugins/shared/workflows_execution_engine/ |
| 自定义或产品注册的步骤 | src/platform/plugins/shared/workflows_extensions/;内部指南参见 workflows_extensions/dev_docs/STEPS.md |
| Stack 连接器操作 | x-pack/platform/plugins/shared/stack_connectors/ 以及 x-pack/platform/plugins/ 下的连接器专属插件 |
官方工作流示例位于 kbn-workflows/spec/examples/。验证符合架构的 YAML 时,优先使用这些示例,而不是 elastic/workflows。
注意: x-pack/platform/plugins/shared/workflows/ 是旧路径——请使用上文的 src/platform/ 目录结构。
现有 docs-content 文件
如果工作区中存在 docs-content 检出副本:
- 阅读
explore-analyze/workflows/下的相邻页面,了解行文风格、结构和交叉链接 - 检查
explore-analyze/workflows/_snippets/,查看可复用的包含内容 - 检查
toc.yml,了解导航位置以及目标是否为带有children:的集成页面
工作流示例
elastic/workflows 库包含 YAML 示例。可用它编写贴近实际的示例,但记录前要根据源代码核实每种步骤类型及其参数。
第 3 步:遵循 Workflows 编写规则
这些约定必须严格遵守。速查表是容易出错之处的权威参考。
YAML 示例
- 以步骤为重点的示例使用
steps:块;只有在触发器、输入或设置很重要时,才包含完整的工作流 YAML - 使用两个空格缩进;确保示例可直接复制粘贴
- 为步骤起描述性名称(
search_for_alerts,不要使用step1) - 明确展示步骤之间的数据流(
steps.<name>.output)
语法规则
| 规则 | 正确 | 错误 |
|---|---|---|
| Liquid 中的数组/对象 | "${{ event.alerts }}" | "{{ event.alerts }}" |
| Liquid 中的字符串 | "{{ inputs.name }}" | — |
data.filter/if 条件 | KQL:item._source.severity : 'critical' | Liquid:== 比较 |
| Cases 步骤参数 | case_id、comment(snake_case) | caseId(camelCase) |
带命名空间的步骤 ID(cases.*、security.*、elasticsearch.*) | 小写点号表示法:security.setAlertStatus | PascalCase(kibana.SetAlertsStatus),除非是在说明旧步骤本身 |
| 告警状态步骤 | kibana.SetAlertsStatus(PascalCase) | kibana.set_alerts_status |
| AI 步骤标识符 | 顶层的 connector-id、agent-id(字面量 kebab-case) | 嵌套在 with 下,或使用 Liquid 模板 |
| JSON 序列化 | | json、| json_parse | to_json(不存在) |
switch.cases | { case:, steps: } 对象数组 | 以 case 值为键的映射/对象 |
workflow.execute 目标 | with 中的 workflow-id | 顶层字段 |
版本差异
示例涉及 inputs 时,请用 applies-switch 或选项卡展示这两种位置:
- Stack 9.4 及更早版本:顶层的
inputs: - Stack 9.5+ 和 Serverless:嵌套在
type: manual触发器下的inputs
获取 anatomy.md,了解规范的选项卡标记。
生命周期与可用性
如果某个步骤或功能受版本限制,请注明其预览版/GA 状态以及 applies_to 标签。对于已弃用或已重命名的步骤、触发器或参数:
- 新内容记录当前替代方案,而不是已弃用的形式
- 迁移背景——如果展示已弃用的形式,请在行内标明其已弃用,并链接到替代方案参考文档
- 迁移指南——在 Workflows 文档集中查找特定版本的迁移页面(例如 9.3 → 9.4),并链接到这些页面;可以用
cases.*替代kibana.createCase风格的步骤作为示例,但不要将其作为唯一案例 - 优先命名空间——当新的带命名空间步骤(
security.*、cases.*)与旧版kibana.*PascalCase 步骤重叠时,在新工作流文档中将带命名空间的步骤作为首选方案,并在旧页面添加交叉引用(参照kibana.md指向cases.*的方式)
第 4 步:起草页面
如果提供了文档问题,请起草内容,回应 ## Suggested documentation work (for the writer) 中的每一项,除非明确标记为暂缓处理。将每条建议对应到草稿中的某个章节、示例或后续编辑。
遵循以下章节中对应页面类型的结构。H1 标题格式、开篇段落和章节顺序均在其中定义。
Workflows 页面使用少量 MyST 指令——请直接使用:
- 版本差异——对于因 Stack/Serverless 版本不同而有差异的 YAML(尤其是
inputs的位置),使用applies-switch或选项卡。复制anatomy.md中的标记;不要自行编造选项卡语法。 - UI 操作指南——仅在编写技巧页面中使用
stepper。 - 代码片段——如果存在匹配的代码片段,请使用
:::{include}引入explore-analyze/workflows/_snippets/中的内容。
只有在无法通过 Workflows 同级页面解决某项指令时,才查阅 /docs-syntax-help;如果未安装,则跳过。
Frontmatter
---
navigation_title: <Short nav label> # omit on hub pages when title suffices
description: <One sentence describing this Workflows page's content>
products:
- id: kibana
- id: cloud-serverless # include when feature is available on serverless
applies_to:
stack: ga 9.4+ # adjust per feature availability
serverless: ga
---
如果内容类型指南要求,请添加 type: how-to 或 type: tutorial。
步骤参考页面
文件:explore-analyze/workflows/steps/<topic>.md(或 steps/ 下的子文件夹)
如果问题要求以现有步骤页面为范例(例如 Cases 操作步骤),请先阅读对应的同级页面,并沿用其布局,而不是另行设计结构。
命名空间/操作步骤系列页面(例如 cases.md、security.md、kibana.md)采用以下结构:
- H1 + 锚点 — 为步骤系列命名(例如 “Security Triage and Investigation action steps”);将
navigation_title设为更简短的名称(例如Security) - 简介 — 说明
namespace.*步骤的用途、适用场景,以及它们与其他页面上重叠步骤的关系 - 通用约定 — 在介绍各步骤细节前,说明整个命名空间通用的规则:
- 参数位于
with下 - 单个 ID 与批量 ID 字段
- 添加/移除语义(保留现有值,而非完整替换;适用时)
- 必填字段规则(例如“至少填写 add 或 remove 之一”)
- 相关步骤组之间的参数命名差异——必须与实际实现完全一致,不要统一命名(例如
alert_ids与ids、close_reason与reason)
- 参数位于
- 步骤目录 — 提供每个步骤的跳转链接;必要时按子域分组(例如 Alerts 与 Attacks)
- 各步骤章节 — 对每种步骤类型:
- 用一句话说明用途
- 参数表:
Parameter | Location | Type | Required | Description - YAML 示例
- 如果作为范例的页面中包含
:::{include} ../_snippets/schema-location-legend.md :::,也要包含该内容 - 相关内容 — 同级步骤页面、触发器、步骤类型索引、速查表
其他步骤参考页面还可以包含:
- 概览表 — 步骤类型 → API/操作映射
- 组合操作 — 展示数据流的多步骤示例(search → foreach → action)
- 关键概念 — 用于组合操作的输出路径、循环变量、字段读取(例如在 assign 步骤前读取警报字段)
为现有命名空间页面添加单一步骤类型时,请记录:
- 必填和可选的
with参数(采用上述表格格式) - 顶层字段(
connector-id、if、foreach、on-failure等) - 输出结构(
steps.<name>.output) - 一个最简示例;必要时再提供一个贴近实际的多步骤示例
- 该步骤特有的注意事项
起草新的命名空间页面或步骤后,请列出以下后续修改:
steps/action-steps.md— 引入新的步骤系列时,添加类别说明和链接reference/step-types.md— 为每种新的步骤类型添加一行reference/cheat-sheet.md— 添加条目或更新面向任务的分组(例如“管理警报”“管理攻击”)- 重叠的同级页面 — 交叉引用首选命名空间(例如
kibana.md→security.*)
用例页面
文件:explore-analyze/workflows/use-cases/<domain>.md
结构:
- H1 + 锚点 — 以领域为中心的标题(例如 “Security workflows”)
- 简介 — 说明团队如何通过该领域的工作流完成任务
- 模式章节 — 按意图分组,而不是按步骤类型分组:
- 可自动化的内容(项目符号列出结果)
- 典型触发器和步骤模式(简要说明,并链接到步骤/触发器参考)
- 指向示例工作流或模板的链接(如有)
- 相关内容 — 链接到相关步骤参考、编写技巧和教程
用例页面应比步骤参考页面更简短。应链接到相关内容,而不是重复参数表。
编写技巧页面(操作指南)
文件:explore-analyze/workflows/authoring-techniques/<action-verb-topic>.md
遵循操作指南内容类型指南:
- 以动作动词开头的 H1 — 例如“监控工作流执行”
- 简介 — 读者将实现的目标
- 开始之前 — 权限、先决条件、UI 访问路径
- 编号步骤 — 使用祈使动词,每个步骤执行一项操作;UI 演练使用
stepper - 成功检查点 — 如何确认每个关键步骤均已成功
- 后续步骤和相关内容
操作指南最多 10 个步骤。如果涉及范围更广,请拆分为教程。
概念和参考页面
概念页面介绍触发器、步骤、数据流、Liquid、错误处理,重点是帮助读者建立心智模型,并链接到详细参考资料。
参考页面(结构剖析、速查表、上下文变量)使用表格、逐字段说明和版本选项卡。参数目录优先使用表格,而不是正文。
教程页面
文件:explore-analyze/workflows/get-started/<topic>.md
遵循教程内容类型指南。通过说明性上下文串联多项任务。包括示例数据设置、检查点以及“你构建了什么”总结。
第 5 步:交叉链接和导航
起草完成后:
- 根据需要,从中心页面、步骤类型索引、速查表或选择合适步骤页面添加指向新页面的链接
- 在新页面底部添加相关内容部分(3–5 个链接)
- 添加新的步骤系列时,更新
steps/action-steps.md— 遵循现有类别简介的格式(简短描述、“使用……来:”项目符号、Refer to …链接) - 如果问题将
reference/step-types.md和reference/cheat-sheet.md列为交付项,请同时更新这些文件 — 不要只完成主要页面草稿 - 在有重叠内容的同级页面中添加首选命名空间交叉引用(例如,将新建的警报分类工作流从
kibana.SetAlertsStatus引导至security.setAlertStatus) - 添加新文件时更新
toc.yml(与用户确认其位置) - 从中心页面删除重复内容 — 中心页面应作摘要并提供链接,而不是重复参考资料中的详细内容
第 6 步:验证
提交草稿前:
- 如果已安装,请对草稿运行
/docs-content-type-checker— 否则请参照第 4 步中的页面类型模板抽查结构 - 验证外链 — 如果草稿中有可用的文件路径,请使用 elastic-docs MCP 的
get_document_by_url(或 WebFetch)解析每个交叉链接 - 根据速查表中的易错项清单抽查 YAML 示例
- 根据 Kibana 源码确认步骤类型和参数名称
- 对照建议的文档工作表检查草稿 — 必须处理或说明每个未延期的项目
报告任何无法通过源码验证的项目。注明不可用的配套技能或 MCP 工具。
输出格式
请提供:
- 接收摘要 — 问题链接、范围、建议的文档工作(逐项注明状态)、已解决和未解决的问题(未使用问题时省略)
- 页面分类 — 类型、目标文件路径、理由
- 研究摘要 — 已阅读的源页面、查阅的 Kibana 文件
- 草稿内容 — 完整的 Markdown,包含 frontmatter,可直接写入 docs-content
- 后续编辑 — 需要更新的其他文件(索引、toc.yml、中心页面链接);包括建议文档工作中的延期项目
- 待解决问题 — 起草后仍需 SME 审核的事项
如果用户提供了文件路径,请将草稿写入该路径。否则,请提出文件路径并先展示内容以供审核。