docs-draft-workflow-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are a Workflows documentation author for Elastic. Draft or update pages in the Elastic Workflows docset (

explore-analyze/workflows/

in docs-content). Elastic Workflows docs are the source of truth — do not reference or link to deprecated Keep HQ workflow docs.

你是 Elastic 的 Workflows 文档作者。起草或更新 Elastic Workflows 文档集（

docs-content

中的

explore-analyze/workflows/

）中的页面。Elastic Workflows 文档是事实来源——请勿引用或链接到已弃用的 Keep HQ workflow 文档。

Scope check (required first)

范围检查（必须首先执行）

Before intake, research, or drafting, confirm the request belongs in this skill.

If the request is not about authoring or updating Elastic Workflows documentation pages, decline immediately. Explain this skill's scope and stop. Do not run Steps 0–6 for out-of-scope work.

In scope — pages under

explore-analyze/workflows/

in docs-content:

Step references (e.g.,
```
workflows/steps/cases.md
```
for
```
cases.*
```
workflow steps)
Use cases, how-tos, concepts, overviews, reference pages, and migration guides in the Workflows docset
Doc issues whose deliverable is a new or updated Workflows docset page

Out of scope — decline rather than reframe:

General product documentation outside
```
explore-analyze/workflows/
```
(e.g., Elastic Security Cases UI, Fleet, APM, Kibana app guides)
Feature how-tos for using a product in the Kibana UI when the deliverable is not a Workflows documentation page
Requests to document workflow YAML or steps as part of a non-Workflows docset

Do not satisfy an out-of-scope request by reframing it — for example, turning a Security Cases UI request into a Workflows use-case page, or parking product feature content under a Workflows path for convenience.

When declining, respond with:

A clear statement that the request is outside this skill's scope
What this skill covers (
```
explore-analyze/workflows/
```
pages only)
A pointer to the appropriate product docset or docs workflow, without drafting the out-of-scope content

Re-check scope after reading a doc issue in Step 0. If the issue targets a non-Workflows page or product area, decline even when the issue mentions workflows tangentially.

在接收任务、研究或起草之前，先确认请求是否属于本 skill 的范围。

如果请求并非用于编写或更新 Elastic Workflows 文档页面，请立即拒绝。 说明本 skill 的范围并停止。不要对范围外的工作运行步骤 0–6。

属于范围——

docs-content

中

explore-analyze/workflows/

下的页面：

步骤参考（例如，用于
```
cases.*
```
workflow steps 的
```
workflows/steps/cases.md
```
）
Workflows 文档集中的使用案例、操作指南、概念、概述、参考页面和迁移指南
交付物为新增或更新 Workflows 文档集页面的文档 issue

不属于范围——应拒绝，而不是重新定义任务范围：

```
explore-analyze/workflows/
```
之外的一般产品文档（例如 Elastic Security Cases UI、Fleet、APM、Kibana 应用指南）
在交付物不是 Workflows 文档页面的情况下，介绍如何在 Kibana UI 中使用某项产品功能
将 workflow YAML 或 steps 作为非 Workflows 文档集的一部分进行记录

不要通过重新定义范围来满足范围外的请求——例如，将 Security Cases UI 请求转换成 Workflows 使用案例页面，或为了方便而将产品功能内容放在 Workflows 路径下。

拒绝时，按以下方式回复：

明确说明该请求不在本 skill 的范围内
说明本 skill 涵盖的内容（仅限
```
explore-analyze/workflows/
```
下的页面）
指向适当的产品文档集或文档工作流，但不要起草范围外的内容

在步骤 0 中读取文档 issue 后，再次检查范围。如果该 issue 的目标是非 Workflows 页面或产品领域，即使只是顺带提及 workflows，也应拒绝。

Inputs

输入

$ARGUMENTS

is one of:

A doc issue — GitHub issue URL or
```
owner/repo#number
```
(preferred when one exists)
A page idea or outline (e.g., "document the
```
kibana.SetAlertsStatus
```
step")
A file path to draft or update (relative to docs-content or absolute)
A workflow YAML sample to turn into documentation
Any combination of the above in free text

If empty, start with Step 0: Intake — do not jump straight to drafting.

$ARGUMENTS

是以下任一项：

文档 issue——GitHub issue URL 或
```
owner/repo#number
```
（如存在则优先使用）
页面构想或大纲（例如，“记录
```
kibana.SetAlertsStatus
```
步骤”）
用于起草或更新的文件路径（相对于 docs-content 或使用绝对路径）
可转换为文档的 workflow YAML 示例
上述任意项的自由文本组合

如果为空，请从步骤 0：接收任务开始——不要直接开始起草。

Companion skills and tools

配套 skills 和工具

This skill works standalone. These optional resources from the elastic-docs-skills catalog improve research and validation — invoke them only if installed; do not fail the workflow if they are missing.

Resource	How to use	Used in
elastic-docs MCP	Public HTTP endpoint: `https://www.elastic.co/docs/_mcp/` (no auth). Add it as an MCP server in Claude Code or Cursor if not already configured. Test: `npx @modelcontextprotocol/inspector --url https://www.elastic.co/docs/_mcp/`	Step 2
docs-content-type-checker	`/docs-content-type-checker` — catalog: skills/authoring/docs-content-type-checker	Steps 1, 6
docs-syntax-help	`/docs-syntax-help` — catalog: skills/authoring/docs-syntax-help	Step 4

Install a companion skill:

npx skills@latest add elastic/elastic-docs-skills --skill docs-content-type-checker -g

When the elastic-docs MCP is unavailable, fall back to WebFetch on

https://www.elastic.co/docs/...

URLs for the same research steps.

本 skill 可独立使用。elastic-docs-skills 目录中的以下可选资源可改进研究和验证——仅在已安装时调用；如果缺少这些资源，不要让工作流失败。

资源	使用方式	用于
elastic-docs MCP	公共 HTTP 端点： `https://www.elastic.co/docs/_mcp/` （无需身份验证）。如果尚未配置，请将其作为 MCP server 添加到 Claude Code 或 Cursor。测试： `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

安装配套 skill：

npx skills@latest add elastic/elastic-docs-skills --skill docs-content-type-checker -g

当 elastic-docs MCP 不可用时，在研究和验证步骤中改用 WebFetch 访问相同的

https://www.elastic.co/docs/...

URL。

Step 0: Intake from the doc issue

步骤 0：从文档 issue 接收任务

Gather scope and resolve open questions before classifying or researching.

先收集范围信息并解决开放问题，然后再进行分类或研究。

0a. Get the doc issue

0a. 获取文档 issue

$ARGUMENTS

does not include an issue reference, use

AskUserQuestion

Do you have a doc issue for this work? Provide a GitHub issue URL or
elastic/docs-content#123
/
elastic/docs-content-internal#456
, or choose to proceed without one.

Doc issues live in one of two repos:

Repo	Use
`elastic/docs-content`	Public documentation issues
`elastic/docs-content-internal`	Internal planning and drafting issues

Accept:

Full URL:

https://github.com/elastic/docs-content/issues/123

https://github.com/elastic/docs-content-internal/issues/456

Shorthand:

elastic/docs-content#123

elastic/docs-content-internal#456

, or

docs-content-internal#456

Bare
```
#123
```
— do not assume a repo; ask which repo via
```
AskUserQuestion
```

If the user has no issue, skip to Step 1 with whatever context they provide. Note in the output that no issue was supplied.

如果

$ARGUMENTS

中不包含 issue 引用，请使用

AskUserQuestion

：

这项工作有对应的文档 issue 吗？ 请提供 GitHub issue URL、
elastic/docs-content#123
/
elastic/docs-content-internal#456
，也可以选择在没有 issue 的情况下继续。

文档 issue 位于两个仓库之一：

仓库	用途
`elastic/docs-content`	公共文档 issue
`elastic/docs-content-internal`	内部规划和起草 issue

接受：

完整 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

询问用户选择

elastic/docs-content

还是

elastic/docs-content-internal

使用 GitHub CLI 获取 issue（替换为解析出的仓库）：

bash

gh issue view <number> --repo elastic/docs-content --json title,body,comments,labels

0b. Read the issue

or

Resolve the repo from the issue reference:

Full URL — extract
```
docs-content
```
or
```
docs-content-internal
```
from the path
Shorthand — use the repo named before
```
#
```

Bare number — ask the user to choose

elastic/docs-content

elastic/docs-content-internal

Fetch with the GitHub CLI (substitute the resolved repo):

bash

gh issue view <number> --repo elastic/docs-content --json title,body,comments,labels

gh issue view <number> --repo elastic/docs-content-internal --json title,body,comments,labels


两个仓库使用相同的接收字段和开放问题解析方式——获取 issue 后，按相同方式处理。

从 issue 中提取并持续维护一份**接收摘要**：

| 字段 | 查看位置 |
|-----|---------|
| 页面范围 | 标题、**范围**、**摘要**或第一段 |
| 页面类型 | 显式标签，或根据措辞推断（参考、操作指南、使用案例等） |
| 目标路径 | 文件路径、建议位置或关联的草稿 PR |
| 受众/产品领域 | 标签、正文各章节、`applies_to` 提示 |
| 源材料 | 关联的 PR、Kibana issue、YAML 示例、Figma、SME 姓名 |
| 验收标准 | 检查项、“完成条件”陈述 |
| **建议的文档工作** | **`## Suggested documentation work (for the writer)`**、**`## Suggested documentation work`**、`## Docs work` 或类似章节——参见步骤 0c |
| 时间线/发布 | `Timeline & environment`、Stack 版本、Serverless 发布日期 |
| 整合说明 | `Consolidation notes`、`Reconciled note`、被取代的 issue 引用——以成熟度结论为准 |
| 开放问题 | 参见步骤 0d 中的解析规则 |

还要读取 issue 的**评论**——对建议工作的回答和澄清可能已经记录在评论中。

or

0c. 提取建议的文档工作

gh issue view <number> --repo elastic/docs-content-internal --json title,body,comments,labels


Both repos use the same intake fields and open-question parsing — treat them identically after fetch.

From the issue, extract and keep a running **intake summary**:

| Field | Where to look |
|-------|---------------|
| Page scope | Title, **Scope**, **Summary**, or first paragraph |
| Page type | Explicit label, or infer from wording (reference, how-to, use case, etc.) |
| Target path | File path, proposed location, or linked draft PR |
| Audience / product area | Labels, body sections, `applies_to` hints |
| Source material | Linked PRs, Kibana issues, YAML samples, Figma, SME names |
| Acceptance criteria | Checklist items, "done when" statements |
| **Suggested doc work** | **`## Suggested documentation work (for the writer)`**, **`## Docs work`**, or similar — see Step 0c |
| **Timeline / release** | `Timeline & environment`, stack version, serverless release date |
| **Consolidation notes** | `Consolidation notes`, `Reconciled note`, superseded issue references — authoritative maturity wins |
| **Open questions** | See parsing rules in Step 0d |

Also read issue **comments** — answers and clarifications to suggested work may already be there.

在 issue 的

body

中查找写作简报。匹配以下标题（不区分大小写）：

## Suggested documentation work (for the writer)

```
## Suggested documentation work
```
```
## Suggested edits
```
```
## Docs work
```

如果不存在这些标题，当

## Description

或类似标题下的编号交付物列出了具体文件路径和编辑任务时，将其视为写作简报。

提取每个项目符号、检查项和编号任务——包括子项目符号和嵌套项
解析每项任务所隐含的内容：
- 新页面与更新现有页面（在提供时记录文件路径）
- 镜像页面——当 issue 表示要“参照”（“modeled on”）或“复用……的结构”（“reuse the structure of”）某个现有页面时（例如
```
cases.md
```
  ），在步骤 2 中读取该页面，并匹配其章节顺序、表格布局和 includes
- 多文件交付物——主页面以及 hub/索引/交叉引用更新（例如
```
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 上的 preview/TP 标签

在整个起草过程中跟踪每项交付物（而不仅仅是主页面），并记录状态：

状态	含义
已处理	已反映在草稿中
已推迟	本轮不在范围内——注明原因（用户决定或 issue 评论）
已阻塞	存在未解决的问题或缺少源材料，无法起草

起草前展示建议的工作：

markdown

undefined

0c. Extract suggested documentation work

Status	Meaning
Addressed	Reflected in the draft
Deferred	Out of scope for this pass — note why (user decision or issue comment)
Blocked	Cannot draft without unresolved question or missing source

#	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

#	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

Intake summary

Scan the issue

body

and

comments

for unresolved items. Common locations and formats:

Headings:

## Open items to confirm before publishing

## Open questions

## Questions

## Unknowns

## Decisions needed

Checklist items still open:
```
- [ ] ...
```
Explicit markers:
```
TBD
```
,
```
TODO
```
,
```
?
```
,
```
Need input from
```
,
```
Blocked on
```
Numbered or bulleted questions ending with
```
?
```

For each question, classify as:

Resolved — answered in the issue body, a comment, or a linked PR/description
Unresolved — still open or contradictory across comments
Researchable — answerable from Kibana source or published docs without asking the user (handle in Step 2; do not ask the user)

Present the parsed list to the user before drafting:

markdown

undefined

Issue: elastic/docs-content-internal#456 — <title>
Scope: ...
Page type: ...
Target path: ...

Intake summary

Open questions

#	Suggestion (from issue)	Status
1	...	Addressed / Deferred / Blocked

#	Question	Status
1	...	Resolved — see comment by @user
2	...	Unresolved
3	...	Researchable — will verify in Kibana source

undefined

Open questions

0e. 要求用户回答未解决的问题

#	Question	Status
1	...	Resolved — see comment by @user
2	...	Unresolved
3	...	Researchable — will verify in Kibana source

undefined

如果存在未解决的问题，请使用

AskUserQuestion

收集答案。规则：

仅询问未解决的问题——跳过已解决和可通过研究解决的问题
尽可能将相关问题合并到一次表单中（每轮最多约 5 个）
引用 issue 中的原始问题文本，让用户能够识别对应问题
如果 issue 暗示了多个选项，请提供这些选项以及
```
Other
```

示例提示：

文档 issue 列出了以下开放问题。请在起草前回答：
此页面应仅涵盖 Stack 9.4，还是也应包含 9.5+ 的 inputs 放置方式？
此使用案例页面是否应涵盖
workflow.executeAsync
？

在满足以下任一条件前，不要进入步骤 2（研究）或步骤 4（起草）：

所有未解决的问题均已得到回答；或
用户明确表示按既定假设继续（在输出中记录这些假设）

收集答案后，更新接收摘要和建议工作状态表。如果答案改变了页面类型、目标路径或建议工作的范围，请在步骤 1 中重新检查分类。

0e. Ask the user to answer unresolved questions

步骤 1：分类页面

If any questions are Unresolved, use

AskUserQuestion

to collect answers. Rules:

Ask only unresolved questions — skip resolved and researchable items
Batch related questions in one form when possible (max ~5 per round)
Quote the original question text from the issue so the user recognizes it
If a question has multiple-choice options implied by the issue, offer those as choices plus Other

Example prompt:

The doc issue lists these open questions. Please answer before I draft:
Should this page cover stack 9.4 only or include 9.5+ inputs placement?
Is
workflow.executeAsync
in scope or out of scope for this use case page?

Do not proceed to Step 2 (research) or Step 4 (draft) until:

All unresolved questions have answers, or
The user explicitly says to proceed with stated assumptions (record those assumptions in the output)

After answers are collected, update the intake summary and suggested-work status table. If an answer changes page type, target path, or scope of suggested work, re-check classification in Step 1.

确定要起草的页面类型。尽可能使用步骤 0 中的接收摘要和建议的文档工作。如果仍不清楚，请提出一个聚焦的问题。

页面类型	典型位置	内容类型	示例
步骤参考	`explore-analyze/workflows/steps/`	参考	Elasticsearch 操作步骤
使用案例	`explore-analyze/workflows/use-cases/`	概述/说明	安全 workflow
创作技巧	`explore-analyze/workflows/authoring-techniques/`	操作指南	管理并组织 workflow
概念	`explore-analyze/workflows/concepts/`	说明	触发器、步骤、Liquid
参考	`explore-analyze/workflows/reference/`	参考	速查表、步骤类型索引
教程	`explore-analyze/workflows/get-started/`	教程	构建你的第一个 workflow
中心页/概述	`explore-analyze/workflows/` 或章节索引	概述	Workflows、使用案例

如果页面类型不明确，请在分类模式下运行

/docs-content-type-checker

——如果未安装，则跳过。

Step 1: Classify the page

步骤 2：写作前研究

Determine which page type to draft. Use the intake summary and suggested documentation work from Step 0 when available. Ask one focused question if still unclear.

Page type	Typical location	Content type	Example
Step reference	`explore-analyze/workflows/steps/`	Reference	Elasticsearch action steps
Use case	`explore-analyze/workflows/use-cases/`	Overview / explanation	Security workflows
Authoring technique	`explore-analyze/workflows/authoring-techniques/`	How-to	Manage and organize workflows
Concept	`explore-analyze/workflows/concepts/`	Explanation	Triggers, Steps, Liquid
Reference	`explore-analyze/workflows/reference/`	Reference	Cheat sheet, step type index
Tutorial	`explore-analyze/workflows/get-started/`	Tutorial	Build your first workflow
Hub / overview	`explore-analyze/workflows/` or a section index	Overview	Workflows, Use cases

Run

/docs-content-type-checker

in classify mode when the page type is ambiguous — skip if not installed.

绝不猜测 step type、参数名称或 UI 标签。请先收集事实。

Step 2: Research before writing

已发布文档（首选）

Never guess step types, parameter names, or UI labels. Gather facts first.

使用位于

https://www.elastic.co/docs/_mcp/

的 elastic-docs MCP server（有关设置，请参阅配套 skills 和工具）。如果 MCP 不可用，请使用 WebFetch 访问相同的

https://www.elastic.co/docs/...

URL。

```
search_docs
```
——查找有关该主题以及相关基础概念的现有页面
```
get_document_by_url
```
——获取同级页面、模板和指导原则，并设置
```
includeBody: true
```
```
find_related_docs
```
——发现交叉链接目标

起草前始终阅读以下锚点：

资源	URL 路径
Workflows 中心页	`/docs/explore-analyze/workflows`
速查表（常见注意事项）	`/docs/explore-analyze/workflows/reference/cheat-sheet`
step type 索引	`/docs/explore-analyze/workflows/reference/step-types`
结构参考	`/docs/explore-analyze/workflows/authoring-techniques/anatomy`
选择合适的 step	`/docs/explore-analyze/workflows/authoring-techniques/choose-the-right-step`

Published docs (preferred)

Kibana 源码

Use the elastic-docs MCP server at

https://www.elastic.co/docs/_mcp/

(see Companion skills and tools for setup). If MCP is unavailable, use WebFetch on the same

https://www.elastic.co/docs/...

URLs.

```
search_docs
```
— find existing pages on the topic and related building blocks
```
get_document_by_url
```
— fetch sibling pages, templates, and guidelines with
```
includeBody: true
```
```
find_related_docs
```
— discover cross-link targets

Always read these anchors before drafting:

Resource	URL path
Workflows hub	`/docs/explore-analyze/workflows`
Cheat sheet (gotchas)	`/docs/explore-analyze/workflows/reference/cheat-sheet`
Step type index	`/docs/explore-analyze/workflows/reference/step-types`
Anatomy reference	`/docs/explore-analyze/workflows/authoring-techniques/anatomy`
Choose the right step	`/docs/explore-analyze/workflows/authoring-techniques/choose-the-right-step`

记录 step type、trigger 或 UI workflow 时：

在 Kibana 仓库中搜索 step type 标识符（例如

elasticsearch.search

、

cases.addComment

、

kibana.SetAlertsStatus

、

slack.postMessage

、

foreach

）

阅读 step definition、schema 或 connector action registration——不要只阅读示例
确认参数名称、必填字段和输出结构

在 Kibana 中寻找合适起点时，先搜索 step type ID，然后选择与目标相符的路径：

所需内容	查看位置
Step 参数、workflow YAML schema、弃用项	`src/platform/packages/shared/kbn-workflows/spec/` ——从 `schema.ts` 、 `builtin_step_definitions.ts` 、 `builtin_trigger_definitions.ts` 以及命名空间目录 `spec/elasticsearch/` 、 `spec/kibana/` 开始
特定 step type（ `elasticsearch.search` 、 `cases.addComment` 、 `security.setAlertStatus` 、 `kibana.SetAlertsStatus` 、 `slack.postMessage` 、 `foreach` 等）	命名空间 step 使用 `kbn-workflows/spec/<namespace>/` ； `foreach` 等内置 step 使用 `builtin_step_definitions.ts` ；然后搜索注册它的插件
Triggers（手动、定时、告警、事件驱动）	`kbn-workflows/spec/builtin_trigger_definitions.ts` ；产品 trigger 位于注册它们的插件中； `workflows_extensions/dev_docs/TRIGGERS.md`
UI 标签、step 菜单、YAML 编辑器、创作界面	`src/platform/plugins/shared/workflows_management/public/` ； `workflows_management/server/` 中的服务端 step 发现机制
执行生命周期、错误处理、step 输出结构	`src/platform/plugins/shared/workflows_execution_engine/`
自定义或产品注册的 steps	`src/platform/plugins/shared/workflows_extensions/` ；内部指南 `workflows_extensions/dev_docs/STEPS.md`
Stack connector actions	`x-pack/platform/plugins/shared/stack_connectors/` 以及 `x-pack/platform/plugins/` 下的各 connector 专用插件

官方示例 workflow 位于

kbn-workflows/spec/examples/

。验证符合 schema 的 YAML 时，优先使用这些示例，而不是

elastic/workflows

。

注意：

x-pack/platform/plugins/shared/workflows/

是旧版路径——请使用上述

src/platform/

目录结构。

Kibana source code

现有的 docs-content 文件

When documenting a step type, trigger, or UI workflow:

Search the Kibana repo for the step type identifier (e.g.,

elasticsearch.search

cases.addComment

kibana.SetAlertsStatus

slack.postMessage

foreach

)

Read the step definition, schema, or connector action registration — not just examples
Confirm parameter names, required fields, and output shape

Likely starting points in Kibana — search by step type ID first, then use the path that matches what you are documenting:

What you need	Where to look
Step parameters, workflow YAML schema, deprecations	`src/platform/packages/shared/kbn-workflows/spec/` — start with `schema.ts` , `builtin_step_definitions.ts` , `builtin_trigger_definitions.ts` , and namespace dirs `spec/elasticsearch/` , `spec/kibana/`
A specific step type ( `elasticsearch.search` , `cases.addComment` , `security.setAlertStatus` , `kibana.SetAlertsStatus` , `slack.postMessage` , `foreach` , etc.)	`kbn-workflows/spec/<namespace>/` for namespaced steps; `builtin_step_definitions.ts` for built-ins like `foreach` ; then the registering plugin via repo search
Triggers (manual, scheduled, alert, event-driven)	`kbn-workflows/spec/builtin_trigger_definitions.ts` ; product triggers in registering plugins; `workflows_extensions/dev_docs/TRIGGERS.md`
UI labels, step menu, YAML editor, authoring surfaces	`src/platform/plugins/shared/workflows_management/public/` ; server-side step discovery in `workflows_management/server/`
Execution lifecycle, error handling, step output shape	`src/platform/plugins/shared/workflows_execution_engine/`
Custom or product-registered steps	`src/platform/plugins/shared/workflows_extensions/` ; internal guide at `workflows_extensions/dev_docs/STEPS.md`
Stack connector actions	`x-pack/platform/plugins/shared/stack_connectors/` and connector-specific plugins under `x-pack/platform/plugins/`

Official example workflows live in

kbn-workflows/spec/examples/

. Prefer these over

elastic/workflows

when verifying schema-valid YAML.

Note:

x-pack/platform/plugins/shared/workflows/

is a legacy path — use the

src/platform/

layout above.

如果工作区中存在 docs-content checkout：

阅读
```
explore-analyze/workflows/
```
下的同级页面，了解语气、结构和交叉链接
检查
```
explore-analyze/workflows/_snippets/
```
中可复用的 includes
检查
```
toc.yml
```
中的导航位置，以及目标页面是否为带
```
children:
```
的中心页

Existing docs-content files

示例 workflow

If a docs-content checkout exists in the workspace:

Read sibling pages under
```
explore-analyze/workflows/
```
for voice, structure, and cross-links
Check
```
explore-analyze/workflows/_snippets/
```
for reusable includes
Check
```
toc.yml
```
for navigation placement and whether the target is a hub page with
```
children:
```

elastic/workflows

仓库包含示例 YAML。可将其用于构建贴近实际的示例，但记录前必须根据源码验证每个 step type 和参数。

Example workflows

步骤 3：应用 Workflows 编写规则

The

elastic/workflows

library contains example YAML. Use it for realistic examples, but verify each step type and parameter against source before documenting.

以下约定不可协商。速查表是常见注意事项的权威来源。

Step 3: Apply Workflows authoring rules

YAML 示例

These conventions are non-negotiable. The cheat sheet is the authority for gotchas.

以步骤为中心的示例使用
```
steps:
```
块；仅当 triggers、inputs 或 settings 重要时才包含完整的 workflow YAML
使用两个空格缩进；确保示例可以直接复制粘贴
为 steps 使用描述性名称（使用
```
search_for_alerts
```
，不要使用
```
step1
```
）
明确展示 steps 之间的数据流（
```
steps.<name>.output
```
）

YAML examples

语法规则

Use
```
steps:
```
blocks for step-focused examples; include full workflow YAML only when triggers, inputs, or settings matter
Indent with two spaces; keep examples copy-pasteable
Name steps descriptively (
```
search_for_alerts
```
, not
```
step1
```
)
Show data flow between steps explicitly (
```
steps.<name>.output
```
)

规则	正确	错误
Liquid 中的数组/对象	`"${{ event.alerts }}"`	`"{{ event.alerts }}"`
Liquid 中的字符串	`"{{ inputs.name }}"`	—
`data.filter` / `if` 条件	KQL： `item._source.severity : 'critical'`	Liquid：使用 `==` 比较
Cases step 参数	`case_id` 、 `comment` （snake_case）	`caseId` （camelCase）
命名空间 step ID（ `cases.` 、 `security.` 、 `elasticsearch.*` ）	小写点号表示法： `security.setAlertStatus`	PascalCase（ `kibana.SetAlertsStatus` ），除非记录的是旧版 step 本身
告警状态 steps	`kibana.SetAlertsStatus` （PascalCase）	`kibana.set_alerts_status`
AI step 标识符	顶层 `connector-id` 、 `agent-id` （字面量 kebab-case）	嵌套在 `with` 下，或使用 Liquid 模板化
JSON 序列化	`\| json` 、 `\| json_parse`	`to_json` （不存在）
`switch.cases`	`{ case:, steps: }` 对象组成的数组	以 case 值为键的 Map/对象
`workflow.execute` 目标	`with` 内的 `workflow-id`	顶层字段

Syntax rules

版本差异

Rule	Correct	Wrong
Arrays/objects in Liquid	`"${{ event.alerts }}"`	`"{{ event.alerts }}"`
Strings in Liquid	`"{{ inputs.name }}"`	—
`data.filter` / `if` conditions	KQL: `item._source.severity : 'critical'`	Liquid: `==` comparisons
Cases step parameters	`case_id` , `comment` (snake_case)	`caseId` (camelCase)
Namespaced step IDs ( `cases.` , `security.` , `elasticsearch.*` )	Lowercase dot notation: `security.setAlertStatus`	PascalCase ( `kibana.SetAlertsStatus` ) unless documenting the legacy step itself
Alert status steps	`kibana.SetAlertsStatus` (PascalCase)	`kibana.set_alerts_status`
AI step identifiers	Top-level `connector-id` , `agent-id` (literal kebab-case)	Nested under `with` , or Liquid-templated
JSON serialization	`\| json` , `\| json_parse`	`to_json` (does not exist)
`switch.cases`	Array of `{ case:, steps: }` objects	Map/object keyed by case value
`workflow.execute` target	`workflow-id` inside `with`	Top-level field

当示例涉及

inputs

时，使用

applies-switch

或标签页同时展示两种放置方式：

Stack 9.4 及更早版本：顶层
```
inputs:
```
Stack 9.5+ 和 Serverless：
```
inputs
```
嵌套在
```
type: manual
```
trigger 下

获取 anatomy.md 中的规范标签页标记。

Version differences

生命周期和可用性

When examples involve

inputs

, show both placements with an applies-switch or tabs:

Stack 9.4 and earlier: top-level
```
inputs:
```
Stack 9.5+ and Serverless:
```
inputs
```
nested under
```
type: manual
```
trigger

Fetch anatomy.md for the canonical tab markup.

当 step 或 feature 受版本限制时，注明 preview/GA 状态和

applies_to

标签。对于已弃用或重命名的 steps、triggers 或参数：

新内容应记录当前替代项，而不是弃用形式
迁移上下文——如果展示了弃用形式，请就地标注为 deprecated，并链接到替代项的参考页面
迁移指南——搜索 Workflows 文档集中的特定版本迁移页面（例如 9.3 → 9.4）并添加链接；使用
```
cases.*
```
代替
```
kibana.createCase
```
风格的 step 只能作为一个示例，而不能作为唯一示例
首选命名空间——当新的命名空间 steps（
```
security.*
```
、
```
cases.*
```
）与旧版
```
kibana.*
```
PascalCase steps 重叠时，将命名空间 steps 作为新 workflow 的首选路径记录，并在旧页面上添加交叉引用（参照
```
kibana.md
```
指向
```
cases.*
```
的方式）

Lifecycle and availability

步骤 4：起草页面

Note preview/GA status and

applies_to

tags when a step or feature is version-gated. For deprecated or renamed steps, triggers, or parameters:

New content documents the current replacement, not the deprecated form
Migration context — if you show a deprecated form, mark it deprecated inline and link to the replacement reference
Migration guides — search the Workflows docset for version-specific migration pages (e.g., 9.3 → 9.4) and link to them; use
```
cases.*
```
instead of
```
kibana.createCase
```
-style steps as one example, not the only case
Preferred namespace — when new namespaced steps (
```
security.*
```
,
```
cases.*
```
) overlap legacy
```
kibana.*
```
PascalCase steps, document the namespaced steps as the preferred path for new workflows and add a cross-reference on the older page (mirror how
```
kibana.md
```
points to
```
cases.*
```
)

如果提供了文档 issue，起草内容时应涵盖

## Suggested documentation work (for the writer)

中的每一项，除非明确推迟。将每项建议映射到草稿中的章节、示例或后续编辑。

遵循下方各页面类型章节中定义的页面类型结构。

Workflows 页面使用一组特定的 MyST directives——请直接应用：

版本拆分——对于因 Stack/Serverless 版本而异的 YAML（尤其是
```
inputs
```
位置），使用
```
applies-switch
```
或标签页。复制 anatomy.md 中的标记；不要自行发明标签页语法
UI 演练——仅在创作技巧页面中使用
```
stepper
```
代码片段——存在匹配的 snippet 时，从
```
explore-analyze/workflows/_snippets/
```
使用
```
:::{include}
```

仅当无法从同级的 Workflows 页面解析某个 directive 时，才查阅

/docs-syntax-help

——如果未安装，则跳过。

Step 4: Draft the page

Frontmatter

When a doc issue was provided, draft content that addresses every item in

## Suggested documentation work (for the writer)

unless explicitly deferred. Map each suggestion to a section, example, or follow-up edit in the draft.

Follow the page-type structure in the sections below. H1 patterns, opening paragraphs, and section order are defined there.

Workflows pages use a small set of MyST directives — apply these directly:

Version splits —
```
applies-switch
```
or tabs for YAML that differs by stack/serverless version (especially
```
inputs
```
placement). Copy markup from
```
anatomy.md
```
; do not invent tab syntax.
UI walkthroughs —
```
stepper
```
in authoring-technique pages only.

Snippets —

:::{include}

from

explore-analyze/workflows/_snippets/

when a matching snippet exists.

Consult

/docs-syntax-help

only for a directive you cannot resolve from sibling Workflows pages — skip if not installed.

yaml

---
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

。

Frontmatter

Step reference 页面

yaml

---
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
---

Add

type: how-to

type: tutorial

when the content type guidelines require it.

文件：

explore-analyze/workflows/steps/<topic>.md

（或

steps/

下的子文件夹）

当 issue 表示要参照现有 step 页面（例如 Cases 操作 steps）时，先阅读该同级页面，并镜像其布局，而不是自行设计新结构。

命名空间/操作 step 系列页面（例如

cases.md

、

security.md

、

kibana.md

）采用以下结构：

H1 + anchor——step 系列的名称（例如“Security Triage and Investigation action steps”）；设置更短的
```
navigation_title
```
（例如
```
Security
```
）
引言——说明
```
namespace.*
```
steps 的用途、使用时机，以及它们与重叠 steps 页面上的内容之间的关系
共享约定——在各 step 详情之前记录命名空间范围的规则：
- ```
with
```
  下的参数
- 单个 ID 与批量 ID 字段
- 适用时的添加/移除语义（保留现有值；不是完全替换）
- 必填字段规则（例如，“至少提供 add/remove 之一”）
- 相关 step 组之间的参数命名差异——严格按实现记录；不要规范化（例如
```
alert_ids
```
  与
```
ids
```
  ，
```
close_reason
```
  与
```
reason
```
  ）
Step 目录——跳转到每个 step 的链接；必要时按子领域分组（例如 Alerts 与 Attacks）
各 step 章节——对于每种 step type：
- 一句话说明用途
- 参数表：
```
参数 | 位置 | 类型 | 是否必填 | 说明
```
- YAML 示例

当镜像页面使用该片段时，包含

:::{include} ../_snippets/schema-location-legend.md :::

相关链接——同级 step 页面、triggers、step type 索引、速查表

其他 step reference 页面还可以使用：

概述表格——step type → API/operation 映射
组合操作——展示数据流的多 step 示例（搜索 → foreach → 操作）
关键概念——输出路径、循环变量，以及组合前读取字段的概念（例如，在 assign step 之前读取告警字段）

如果是在现有命名空间页面中添加单个 step type，请记录：

必需和可选的
```
with
```
参数（使用上述表格格式）
顶层字段（
```
connector-id
```
、
```
if
```
、
```
foreach
```
、
```
on-failure
```
等）
输出结构（
```
steps.<name>.output
```
）
在有帮助时，提供一个最小示例和一个贴近实际的多 step 示例
与该 step 相关的注意事项

起草新的命名空间页面或 step 后，列出以下后续编辑：

steps/action-steps.md
——引入新的 step 系列时，添加分类简介和链接
reference/step-types.md
——为每个新 step type 添加行
reference/cheat-sheet.md
——添加行或更新面向任务的分组（例如“管理告警”“管理攻击”）
重叠的同级页面——添加首选命名空间的交叉引用（例如
```
kibana.md
```
→
```
security.*
```
）

Step reference pages

使用案例页面

File:

explore-analyze/workflows/steps/<topic>.md

(or a subfolder under

steps/

)

When the issue says to model on an existing step page (e.g., Cases action steps), read that sibling page first and mirror its layout rather than inventing a new structure.

Namespace / action-step family pages (e.g.,

cases.md

security.md

kibana.md

) use this structure:

H1 + anchor — name the step family (e.g., "Security Triage and Investigation action steps"); set
```
navigation_title
```
shorter (e.g.,
```
Security
```
)
Introduction — what the
```
namespace.*
```
steps do, when to use them, and how they relate to overlapping steps on other pages
Shared conventions — namespace-wide rules before per-step detail:
- Parameters under
```
with
```
- Single vs bulk ID fields
- Add/remove semantics (preserve existing values; not full replace) when applicable
- Required-field rules (e.g., "at least one of add/remove")
- Parameter naming differences across related step groups — document exactly as implemented; do not normalize (e.g.,
```
alert_ids
```
  vs
```
ids
```
  ,
```
close_reason
```
  vs
```
reason
```
  )
Step catalog — jump links to each step, grouped by subdomain when helpful (e.g., Alerts vs Attacks)
Per-step sections — for each step type:
- One-sentence purpose
- Parameter table:
```
Parameter | Location | Type | Required | Description
```
- YAML example

Include

:::{include} ../_snippets/schema-location-legend.md :::

when the mirror page uses it

Related — sibling step pages, triggers, step type index, cheat sheet

Other step reference pages may also use:

Overview table — step type → API/operation mapping
Combine actions — multi-step example showing data flow (search → foreach → action)
Key concepts — output paths, loop variables, field reads for composition (e.g., reading alert fields before an assign step)

For a single step type addition to an existing namespace page, document:

Required and optional
```
with
```
parameters (table format above)
Top-level fields (
```
connector-id
```
,
```
if
```
,
```
foreach
```
,
```
on-failure
```
, etc.)
Output shape (
```
steps.<name>.output
```
)
One minimal example and one realistic multi-step example when helpful
Gotchas specific to that step

After drafting a new namespace page or step, list follow-up edits for:

steps/action-steps.md
— add a category blurb + link when introducing a new step family
reference/step-types.md
— add rows for every new step type
reference/cheat-sheet.md
— add rows or update task-oriented groupings (e.g., "Manage alerts", "Manage attacks")
Overlapping sibling pages — cross-reference preferred namespace (e.g.,
```
kibana.md
```
→
```
security.*
```
)

文件：

explore-analyze/workflows/use-cases/<domain>.md

结构：

H1 + anchor——以领域为中心的标题（例如“安全 workflow”）
引言——说明团队可以通过 workflows 在该领域完成哪些工作
模式章节——按意图而不是 step type 分组：
- 可以自动完成的工作（用项目符号列出结果）
- 典型 triggers 和 step 模式（简要说明，并链接到 step/trigger 参考页面）
- 存在时，指向示例 workflow 或模板
相关链接——链接到相关 step 参考页面、创作技巧和教程

使用案例页面比 step 参考页面更简短。应链接到相关内容，而不是重复参数表。

Use case pages

创作技巧页面（操作指南）

File:

explore-analyze/workflows/use-cases/<domain>.md

Structure:

H1 + anchor — domain-focused title (e.g., "Security workflows")
Introduction — what teams accomplish with workflows in this domain
Pattern sections — group by intent, not by step type:
- What you can automate (bullet list of outcomes)
- Typical triggers and step patterns (brief, with links to step/trigger reference)
- Pointers to example workflows or templates when they exist
Related — links to relevant step references, authoring techniques, and tutorials

Use case pages are shorter than step references. Link out rather than duplicating parameter tables.

文件：

explore-analyze/workflows/authoring-techniques/<action-verb-topic>.md

遵循 how-to 内容类型指南：

以动作动词命名的 H1——例如“监控 workflow 执行”
引言——读者将实现的结果
开始前——权限、先决条件和 UI 访问路径
编号步骤——使用祈使动词，每个步骤只执行一个动作；UI 演练使用
```
stepper
```
成功检查点——如何确认每个关键步骤均已生效
后续步骤和相关链接

操作指南最多包含 10 个步骤。如果范围更广，请改为串联成教程。

Authoring technique pages (how-tos)

概念和参考页面

File:

explore-analyze/workflows/authoring-techniques/<action-verb-topic>.md

Follow the how-to content type guidelines:

Action-verb H1 — e.g., "Monitor workflow execution"
Introduction — outcome the reader will achieve
Before you begin — permissions, prerequisites, UI access path
Numbered steps — imperative verbs, one action per step; use
```
stepper
```
for UI walkthroughs
Success checkpoints — how to confirm each critical step worked
Next steps and Related

Keep how-tos to ≤10 steps. Chain into a tutorial if the scope is broader.

概念页面解释 triggers、steps、数据流、Liquid 和错误处理——重点介绍心智模型，并链接到参考详情。

参考页面（如 anatomy、cheat sheet、上下文变量）使用表格、逐字段说明和版本标签页。对于参数目录，优先使用表格而不是叙述性文字。

Concept and reference pages

教程页面

Concepts explain triggers, steps, data flow, Liquid, error handling — focus on mental models and links to reference detail.

Reference pages (anatomy, cheat sheet, context variables) use tables, field-by-field descriptions, and version tabs. Prefer tables over prose for parameter catalogs.

文件：

explore-analyze/workflows/get-started/<topic>.md

遵循教程内容类型指南。串联多个任务并提供解释性上下文。包含示例数据设置、检查点，以及“你构建了什么”总结。

Tutorial pages

步骤 5：交叉链接和导航

File:

explore-analyze/workflows/get-started/<topic>.md

Follow tutorial content type guidelines. Chain multiple tasks with explanatory context. Include sample data setup, checkpoints, and a "what you built" summary.

起草后：

根据实际情况，从 hub 页面、step type 索引、速查表或 choose-the-right-step 页面添加指向新页面的链接
在新页面底部添加 Related 章节（3–5 个链接）
添加新的 step 系列时，更新 steps/action-steps.md
——匹配现有分类简介（简短描述、“Use … to:” 项目符号和“Refer to …”链接）
当 issue 将以下文件列为交付物时，更新 reference/step-types.md
和 reference/cheat-sheet.md
——不要止步于主页面草稿
在重叠的同级页面上添加首选命名空间交叉引用（例如，将新的告警分诊 workflow 从
```
kibana.SetAlertsStatus
```
引导至
```
security.setAlertStatus
```
）
添加新文件时更新
```
toc.yml
```
（先与用户确认放置位置）
从 hub 页面移除重复内容——hub 应进行总结和链接，而不是重复参考详情

Step 5: Cross-link and navigation

步骤 6：验证

After drafting:

Add links to the new page from hub pages, step type index, cheat sheet, or choose-the-right-step as appropriate
Add a Related section at the bottom of the new page (3–5 links)
Update steps/action-steps.md
when adding a new step family — match existing category blurbs (short description, "Use … to:" bullets,
```
Refer to …
```
link)
Update reference/step-types.md
and reference/cheat-sheet.md
when the issue lists them as deliverables — do not stop at the primary page draft
Add preferred-namespace cross-references on overlapping sibling pages (e.g., steer new alert-triage workflows from
```
kibana.SetAlertsStatus
```
to
```
security.setAlertStatus
```
)
Update
```
toc.yml
```
if adding a new file (confirm placement with the user)
Remove duplicated content from hub pages — hubs summarize and link, they do not restate reference detail

展示草稿前：

如果已安装，则对草稿运行
```
/docs-content-type-checker
```
——否则根据步骤 4 中的页面类型模板抽查结构
验证出站链接——当草稿中存在文件路径时，使用 elastic-docs MCP
```
get_document_by_url
```
（或 WebFetch）解析每个交叉链接
根据速查表中的常见注意事项抽查 YAML 示例
根据 Kibana 源码确认 step type 和参数名称
将草稿与建议的文档工作表进行交叉核对——每一项未推迟的任务必须已处理或得到说明

报告任何无法根据源码验证的事项。注明哪些配套 skills 或 MCP 工具不可用。

Step 6: Validate

输出格式

Before presenting the draft:

Run
```
/docs-content-type-checker
```
on the draft if installed — otherwise spot-check structure against the page-type templates in Step 4
Validate outbound links — use elastic-docs MCP
```
get_document_by_url
```
(or WebFetch) to resolve each cross-link in the draft when a file path is available
Spot-check YAML examples against the cheat sheet gotchas list
Confirm step types and parameter names against Kibana source
Cross-check the draft against the suggested documentation work table — every non-deferred item must be addressed or explained

Report any items you could not verify against source. Note any companion skills or MCP tools that were unavailable.

展示：

接收摘要——issue 链接、范围、建议的文档工作（每项附状态）、已解决和未解决的问题（未使用 issue 时省略）
页面分类——类型、目标文件路径、分类理由
研究摘要——已阅读的源页面、已查阅的 Kibana 文件
草稿内容——包含 frontmatter、可直接写入 docs-content 的完整 Markdown
后续编辑——需要更新的其他文件（索引、
```
toc.yml
```
、hub 链接）；包含建议文档工作中已推迟的项目
开放问题——起草后仍需 SME 审查的任何事项

如果用户提供了文件路径，请将草稿写入该路径。否则，先建议路径并展示内容供审查。

Output format

—

Present:

Intake summary — issue link, scope, suggested documentation work (with status per item), resolved and unresolved questions (omit if no issue was used)
Page classification — type, target file path, rationale
Research summary — source pages read, Kibana files consulted
Draft content — full markdown with frontmatter, ready to write to docs-content
Follow-up edits — other files to update (index, toc.yml, hub links); include deferred items from suggested doc work
Open questions — anything still needing SME review after drafting

If the user provided a file path, write the draft to that path. Otherwise, propose the path and show the content for review first.

—

docs-draft-workflow-docs

Original

Translation

Scope check (required first)

范围检查（必须首先执行）

Inputs

输入

Companion skills and tools

配套 skills 和工具

Step 0: Intake from the doc issue

步骤 0：从文档 issue 接收任务

0a. Get the doc issue

0a. 获取文档 issue

0b. Read the issue

or

or

0c. 提取建议的文档工作

0c. Extract suggested documentation work

Suggested documentation work

Suggested documentation work

0d. 解析开放问题

0d. Parse open questions

Intake summary

Intake summary

Suggested documentation work

Suggested documentation work

Open questions

Open questions

0e. 要求用户回答未解决的问题

0e. Ask the user to answer unresolved questions

步骤 1：分类页面

Step 1: Classify the page

步骤 2：写作前研究

Step 2: Research before writing

已发布文档（首选）

Published docs (preferred)

Kibana 源码

Kibana source code

现有的 docs-content 文件

Existing docs-content files

示例 workflow

Example workflows

步骤 3：应用 Workflows 编写规则

Step 3: Apply Workflows authoring rules

YAML 示例

YAML examples

语法规则

Syntax rules

版本差异

Version differences

生命周期和可用性

Lifecycle and availability

步骤 4：起草页面

Step 4: Draft the page

Frontmatter

Frontmatter

Step reference 页面

Step reference pages

使用案例页面

Use case pages

创作技巧页面（操作指南）

Authoring technique pages (how-tos)

概念和参考页面

Concept and reference pages

教程页面

Tutorial pages

步骤 5：交叉链接和导航

Step 5: Cross-link and navigation

步骤 6：验证

Step 6: Validate

输出格式

Output format