[Agent Builder] Split action-policy-authoring from rule-authoring

explore-analyze/ai-features/agent-builder/builtin-skills-reference.md

@@ -129,14 +129,60 @@ $$$agent-builder-cases-management-skill$$$ `cases-management` {applies_to}`stack
 
     :::
 
-$$$agent-builder-rule-management-skill$$$ `rule-management` {applies_to}`stack: preview 9.5` {applies_to}`serverless: preview`
-:   Composes, discovers, and modifies alerting rules and action policies from within a conversation.
+$$$agent-builder-rule-management-skill$$$ $$$agent-builder-rule-authoring-skill$$$ `rule-authoring` {applies_to}`stack: experimental 9.5+` {applies_to}`serverless: experimental`
+:   Composes, discovers, and modifies {{alerting-v2-system}} rules from within a conversation. Covers threshold, aggregation, and grouped conditions over any {{es}} index. Doesn't cover:
+
+    * [{{alerting-v1-system}}](/explore-analyze/alerting/alerts.md) rules
+    * {{observability}} rules created with {{alerting-v1-system}}
+    * {{elastic-sec}} detection rules
+
+    {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` This skill was previously named `rule-management`. If a custom agent lists `rule-management`, replace that id with `rule-authoring`.
+
+    {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` [`action-policy-authoring`](#agent-builder-action-policy-authoring-skill) sets up notifications. After this skill proposes a complete rule that opens alerts, it offers to set up notifications. If you accept, the agent loads `action-policy-authoring`.
+
+    {applies_to}`stack: experimental =9.5` In 9.5, this skill is named `rule-management` and also composes action policies.
 
     :::{dropdown} Assigned tools
-    `platform.alerting.manage_rule`, `platform.alerting.manage_action_policy`
+    `platform.alerting.manage_rule`
+
+    {applies_to}`stack: experimental =9.5` `platform.alerting.manage_action_policy`
 
     :::
 
+    **Prerequisites:**
+
+    * The `alerting:v2:enabled` advanced setting turned on. You can find it on the **Global Settings** tab. Refer to [Turn on the system](/explore-analyze/alerting/esql/setup.md#alerting-setup-turn-on). {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` This setting is on by default.
+    * {applies_to}`stack: experimental =9.5` The `agentBuilder:experimentalFeatures` advanced setting turned on. You can find it on the **Space Settings** tab. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional).
+    * {applies_to}`stack: experimental =9.5` To find or edit saved rules and action policies, the `contextEngine:enabled` advanced setting also turned on. You can find it on the **Space Settings** tab.
+    * {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` To search for saved rules from a conversation, turn on `agentBuilder:experimentalFeatures` on the **Space Settings** tab. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional). The agent can still create rules with this setting off. It can also edit a saved rule from that rule's details page.
+    * {applies_to}`stack: experimental 9.6+` A space that uses the Classic or {{observability}} solution view.
+    * {applies_to}`serverless: experimental` An {{obs-serverless}} project.
+
+    Saving a rule requires the **Rules: All** privilege. For all the privileges you need, refer to [Create rules and action policies with {{agent-builder}}](/explore-analyze/alerting/esql/manage/configure-access.md#alerting-agent-builder-privileges).
+
+$$$agent-builder-action-policy-authoring-skill$$$ `action-policy-authoring` {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental`
+:   Composes, discovers, and modifies action policies from within a conversation. Use it to set up, inspect, or edit alert notifications, such as email or paging an on-call responder.
+
+    An [action policy](/explore-analyze/alerting/esql/action-policies/about-action-policies.md) controls how alerts are matched, grouped, throttled, and sent to workflows. A policy belongs to a space, so one policy can match alerts from many rules.
+
+    {applies_to}`serverless: experimental` This skill was previously named `action-policy-management`. If a custom agent lists `action-policy-management`, replace that id with `action-policy-authoring`.
+
+    :::{dropdown} Assigned tools
+    `platform.alerting.manage_action_policy`
+
+    :::
+
+    **Prerequisites:**
+
+    * The `alerting:v2:enabled` advanced setting turned on. You can find it on the **Global Settings** tab. Refer to [Turn on the system](/explore-analyze/alerting/esql/setup.md#alerting-setup-turn-on). This setting is on by default.
+    * To search for saved action policies from a conversation, turn on `agentBuilder:experimentalFeatures` on the **Space Settings** tab. Refer to [Enable experimental features](get-started.md#enable-experimental-features-optional). The agent can still create action policies with this setting off. It can also edit a saved policy from that policy's edit page.
+    * {applies_to}`stack: experimental 9.6+` A space that uses the Classic or {{observability}} solution view.
+    * {applies_to}`serverless: experimental` An {{obs-serverless}} project.
+
+    Saving an action policy requires the **Action Policies: All** privilege and, on {{stack}} deployments, an Enterprise license. The policy sends alerts to a workflow. The workflow steps use a configured connector. For all the privileges you need, refer to [Create rules and action policies with {{agent-builder}}](/explore-analyze/alerting/esql/manage/configure-access.md#alerting-agent-builder-privileges).
+
+    **Related skills:** [`rule-authoring`](#agent-builder-rule-authoring-skill) composes the rules whose alerts a policy matches.
+
 ### Streams and significant events
 
 $$$agent-builder-streams-management-skill$$$ `streams-management` {applies_to}`stack: ga 9.5+` {applies_to}`serverless: ga`

explore-analyze/ai-features/agent-builder/tools/builtin-tools-reference.md

@@ -549,7 +549,8 @@ Identifier formats depend on the service:
 Some [built-in skills](../builtin-skills-reference.md) include inline tools that are only available while that skill is active. Because they are scoped to a skill rather than assignable on their own, they are not listed among the namespaced tools in this reference. For example:
 
 - The [`dashboards`](../builtin-skills-reference.md#agent-builder-dashboards-skill) skill (`dashboard-management` in 9.4 and 9.5) includes an inline tool for generating and updating dashboards.
-- The `rule-management` skill includes the `platform.alerting.manage_rule` and `platform.alerting.manage_action_policy` tools for composing and modifying alerting rules and their action policies.
+- The [`rule-authoring`](../builtin-skills-reference.md#agent-builder-rule-authoring-skill) skill (`rule-management` in 9.5) includes the `platform.alerting.manage_rule` tool for composing and modifying {{alerting-v2-system}} rules. In 9.5, it also includes `platform.alerting.manage_action_policy`.
+- {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` The [`action-policy-authoring`](../builtin-skills-reference.md#agent-builder-action-policy-authoring-skill) skill includes the `platform.alerting.manage_action_policy` tool for composing and modifying action policies.
 - The `alert-triage` skill includes the `security.alert-triage` tool for prioritizing the alert queue.
 
 :::{tip}

explore-analyze/alerting/esql/rules/create-rules-action-policies-agent-builder.md

@@ -5,20 +5,23 @@ applies_to:
   serverless: experimental
 products:
   - id: kibana
-description: "How Agent Builder creates rules and action policies using the rule management skill, what the agent produces, and the save-order dependency."
+description: "Create Universal Alerting rules and action policies with Agent Builder. Describe what to monitor in natural language, review the proposal, and save the rule, workflow, and action policy."
 ---
 
 # Create rules and action policies with {{agent-builder}} [create-rules-agent-builder]
 
-Use {{agent-builder}} to create and configure {{alerting-v2-system}} rules and action policies through natural language instead of the rule form. Describe what you want to monitor, and an agent equipped with the rule management skill resolves the data source and proposes a fully configured rule.
+Use an agent with the [`rule-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-rule-authoring-skill) skill (`rule-management` in 9.5) instead of the rule form. The agent resolves the data source and proposes a configured {{alerting-v2-system}} rule.
 
 ## Requirements [create-ai-agent-requirements]
 
 Before you start, make sure you have the following:
 
 - **The required subscription** - {{agent-builder}} requires the appropriate {{stack}} [subscription](https://www.elastic.co/pricing) or {{serverless-short}} [project feature tier](/deploy-manage/deploy/elastic-cloud/project-settings.md#project-features-add-ons).
-- **The `agentBuilder:experimentalFeatures` advanced setting turned on** - Go to the **Advanced Settings** menu using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), and turn on `agentBuilder:experimentalFeatures`.
-- {applies_to}`serverless: experimental` {applies_to}`stack: experimental 9.6+` **The `alerting:v2:experimentalFeatures` advanced setting turned on** - The setting is off by default and applies only to the space where you turn it on. To turn it on, refer to [Try experimental features in a space](../setup.md#alerting-setup-experimental-features).
+- {applies_to}`stack: experimental =9.5` **The `agentBuilder:experimentalFeatures` advanced setting turned on** - Go to the **Advanced Settings** page using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md), select the **Space Settings** tab, and turn on `agentBuilder:experimentalFeatures`.
+- {applies_to}`stack: experimental =9.5` **To search for and edit existing rules and action policies, the `contextEngine:enabled` advanced setting also turned on** - On the **Space Settings** tab, turn it on in each space where you use the agent.
+- {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` **To search for existing rules and action policies from a conversation, the `agentBuilder:experimentalFeatures` advanced setting turned on** - On the **Space Settings** tab, turn it on. Refer to [Enable experimental features](/explore-analyze/ai-features/agent-builder/get-started.md#enable-experimental-features-optional). The agent can still create rules and action policies with this setting off. It can also edit a saved rule from its details page, or a saved action policy from its edit page.
+- {applies_to}`stack: experimental 9.6+` **A space that uses the Classic or {{observability}} solution view** - The `rule-authoring` and `action-policy-authoring` skills aren't available in other spaces.
+- {applies_to}`serverless: experimental` **An {{obs-serverless}} project** - The `rule-authoring` and `action-policy-authoring` skills aren't available in other project types.
 - **The required privileges** - Your role needs the [privileges to use {{agent-builder}} and save rules and action policies](../manage/configure-access.md#alerting-agent-builder-privileges).
 
 ## Propose and save a rule [ai-agent-rule-proposal]
@@ -27,9 +30,13 @@ Before you start, make sure you have the following:
 
 To create a rule, go to **Alerting** → **Rules** in the {{observability}} navigation menu, or find **Rules** using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md).
 
-Then select the creation path that lets you create the rule with an agent. Alternatively, open any agent in [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) that has the rule management skill configured. 
+{applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` Select **Create rule** → **Create with agent**. When the Rules list is empty, select **With AI Agent**.
 
-The rule management skill gives the agent domain expertise in {{alerting-v2-system}} rule authoring, including knowledge of {{esql}} query patterns, threshold configuration, grouping, and the {{alerting-v2-system}} data model. When you describe a monitoring requirement, the agent uses its tools to resolve the relevant data source and builds a rule proposal.
+{applies_to}`stack: experimental =9.5` In the rule creation options, select **Create with agent**.
+
+Alternatively, open any agent in [{{agent-builder}}](/explore-analyze/ai-features/elastic-agent-builder.md) that has the [`rule-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-rule-authoring-skill) skill configured.
+
+The `rule-authoring` skill covers {{esql}} query patterns, thresholds, grouping, and the {{alerting-v2-system}} data model.
 
 ### Review the proposal [ai-agent-review-proposal]
 
@@ -58,26 +65,39 @@ Use these prompts as a starting point, then adjust them to your data and thresho
 
 ## Set up notifications [ai-agent-notification-setup]
 
-After a rule is saved, you can ask the agent to configure notifications. The rule management skill handles this by creating workflows and action policies.
+The agent proposes the workflows and action policies needed to deliver notifications.
+
+{applies_to}`stack: experimental =9.5` The `rule-management` skill creates the action policies itself.
+
+{applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` After the `rule-authoring` skill proposes a complete rule that opens alerts, it offers to set up notifications. If you accept, the agent loads the [`action-policy-authoring`](/explore-analyze/ai-features/agent-builder/builtin-skills-reference.md#agent-builder-action-policy-authoring-skill) skill. That skill creates the action policies.
 
 :::{note}
-Action policies invoke workflows for alerts only. If you ask the agent to set up notifications for a rule that doesn't open alerts, the skill explains the limitation. If the rule is still a draft in the conversation, the skill changes it so matches open alerts before you save it. If the rule is already saved, that setting can't change, so the skill offers to create a new rule with the same query and schedule that opens alerts, then set up notifications on that rule.
+Action policies invoke workflows for alerts only. If you ask the agent to set up notifications for a rule that doesn't open alerts, it explains the limitation and offers a way forward:
+
+- **Unsaved rule** - The agent changes the draft rule so that it opens alerts. Then you save the rule.
+- **Saved rule** - Whether a rule opens alerts can't change after you save it. The agent offers to create a new rule with the same query and schedule that opens alerts, then set up notifications on that rule.
 :::
 
 - **Workflows** - Workflows are the delivery mechanism. They define what happens when {{alerting-v2-system}} determines that a notification should be sent, such as posting to Slack, emailing a team, triggering PagerDuty, and so on.
 - **Action Policies** - Action policies are the gating mechanism. {{kib}} evaluates them against the rule's alerts and invokes the workflow for the alerts they apply to. When you create an action policy with a rule, the policy applies to that rule's alerts.
-    * {applies_to}`serverless: experimental` {applies_to}`stack: experimental 9.6+` The agent links the policy to the rule with a [routing tag](../action-policies/create-configure-action-policy.md#routing-tags). If the rule already has a routing tag that no other rule uses, the agent can reuse it. Otherwise, the agent adds a `notify-<rule-name>` routing tag to the rule and the policy, in lowercase with hyphens (for example, `notify-high-cpu-prod`). The policy also applies to alerts from any other rule with that routing tag. If the agent adds a routing tag to a rule you already saved, save the rule again so the tag takes effect.
+    * {applies_to}`serverless: experimental` {applies_to}`stack: experimental 9.6+` The agent links the policy to the rule with a [routing tag](../action-policies/create-configure-action-policy.md#routing-tags).
+        * If the rule already has a routing tag that no other rule uses, the agent reuses it.
+        * Otherwise, the agent adds a `notify-<rule-name>` routing tag to the rule and the policy. The tag is lowercase with hyphens, for example, `notify-high-cpu-prod`.
+        * The policy also applies to alerts from any other rule with that routing tag.
+        * If the agent adds a routing tag to a rule you already saved, save the rule again so the tag takes effect.
     * {applies_to}`stack: removed 9.6+, experimental =9.5` {applies_to}`serverless: unavailable` The action policy references the rule by ID.
 
 Both objects are proposed as inline attachments and must be explicitly saved before they take effect.
 
 ### Save order [save-order-ai-agent]
 
-The three objects have a dependency chain that determines the order in which they must be saved:
+The three objects depend on each other. Save them in this recommended order:
 
 1. **Rule** - Save the rule first. The link between the rule and the action policy takes effect only after the rule is saved.
 2. **Workflow** - The action policy references the workflow as a destination. The reference must resolve to a persisted workflow.
-3. **Action policy** - Can only be saved after both its rule and workflow dependencies exist.
+3. **Action policy** - Save the action policy last.
+    * {applies_to}`stack: experimental 9.6+` {applies_to}`serverless: experimental` You can't select **Create policy** while a workflow destination is still a draft. You can save the policy before the rule. The policy doesn't apply to the rule's alerts until the rule is saved.
+    * {applies_to}`stack: experimental =9.5` You can't save the action policy until both its rule and its workflow exist.
 
 :::{note}
 :applies_to: {"stack": "removed 9.6+, experimental =9.5", "serverless": "unavailable"}

explore-analyze/alerting/esql/setup.md

@@ -62,10 +62,7 @@ stack: experimental 9.6+
 
 To try features of {{alerting-v2-system}} that are still experimental, turn on the **Universal Alerting: Experimental Features** advanced setting (`alerting:v2:experimentalFeatures`). The setting is off by default and applies only to the space where you turn it on.
 
-When the setting is on, you can:
-
-- Detect multi-step alert patterns by chaining rules into a sequence. On the **Rules** page, select **Build a sequence (Experimental)**.
-- Create rules and action policies by describing them to {{agent-builder}} in natural language. Select **Create rule** → **Create with agent (Experimental)** on the **Rules** page, or **Create policy** → **Create with agent (Experimental)** on the **Action Policies** page. {{agent-builder}} has [its own requirements](rules/create-rules-action-policies-agent-builder.md#create-ai-agent-requirements).
+When the setting is on, you can chain rules into a sequence and detect multi-step alert patterns. On the **Rules** page, select **Build a sequence (Experimental)**.
 
 To turn on experimental features:
 
@@ -74,6 +71,13 @@ To turn on experimental features:
 3. Select the **Space Settings** tab, then turn on **Universal Alerting: Experimental Features**.
 4. Select **Save changes**, then reload {{kib}}.
 
+You can create rules and action policies with {{agent-builder}} while this setting is off.
+
+- On the **Rules** page, select **Create rule** → **Create with agent**. When the Rules list is empty, select **With AI Agent**.
+- On the **Action Policies** page, select **Create policy** → **Create with agent**. When the Action Policies list is empty, select **Create with AI Agent**.
+
+{{agent-builder}} has [its own requirements](rules/create-rules-action-policies-agent-builder.md#create-ai-agent-requirements).
+
 ## Keep the Observability alerts page for {{alerting-v1-system}} [alerting-setup-v1-alerts-page]
 
 ```yaml {applies_to}