docs: document the discover-data-analysis Agent Builder skill (#6684)

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

@@ -38,6 +38,13 @@ $$$agent-builder-dashboard-management-skill$$$ `dashboard-management` {applies_t
 $$$agent-builder-streams-exploration-skill$$$ `streams-exploration` {applies_to}`stack: ga 9.4+`
 :   Discovers, inspects, and queries {{es}} streams. Use when a user wants to list available streams, understand a stream's schema, check data quality or retention, or sample documents from a stream. This is a read-only skill: it cannot create, update, or delete streams or modify stream configuration.
 
+$$$agent-builder-discover-data-analysis-skill$$$ `discover-data-analysis` {applies_to}`stack: ga 9.5` {applies_to}`serverless: ga`
+:   Analyzes {{esql}} query results in {{kib}} **Discover**, identifying patterns, trends, and anomalies by running aggregation queries against the full dataset. The skill receives the current query, columns, sample rows, and time range as an attachment, then runs 2 to 3 focused aggregation queries, renders an inline visualization for the main finding, and proposes drill-down queries. When the active [context-aware profile](/explore-analyze/discover/discover-get-started.md#context-aware-discover) is logs, metrics, or traces, the skill receives shape-specific guidance. For example, it uses the {{esql}} `TS` source command for time series metrics.
+
+    **Assigned tools:** `platform.core.generate_esql`, `platform.core.execute_esql`, `platform.core.search`, `platform.core.list_indices`, `platform.core.product_documentation`, `platform.core.create_visualization`
+
+    **How to activate:** In addition to the [standard activation methods](skills.md#how-skills-are-invoked), this skill activates automatically when you open the **AI Agent** button from **Discover** in a new tab that is in {{esql}} mode and has no active conversation. Refer to [Analyze your data with AI](/explore-analyze/discover/discover-get-started.md#analyze-with-ai) for the full workflow.
+
 $$$agent-builder-workflow-authoring-skill$$$ `workflow-authoring` {applies_to}`stack: preview 9.4` {applies_to}`serverless: preview`
 :   Creates, modifies, and validates [Elastic Workflows](/explore-analyze/workflows.md) YAML definitions from natural language user input. Covers step types, triggers, Liquid templating, connector integrations, and validation. Use this skill when a user wants to draft a new workflow from a description, edit an existing workflow, change a workflow's trigger, or update top-level properties such as name, description, or tags. The agent validates the generated or modified YAML before proposing the change so the user can accept or decline it.
 

explore-analyze/discover/discover-get-started.md

@@ -29,9 +29,11 @@
 
 When you access **Discover** outside of a specific solution context, or when working with data types that don't have specialized experiences, you get the default **Discover** interface with all its core functionality for general-purpose data exploration.
 
+{applies_to}`stack: ga 9.5` {applies_to}`serverless: ga` The active profile also shapes [AI-powered deep analysis](#analyze-with-ai): when you query logs, metrics, or traces from the matching solution context, the agent receives domain-specific guidance on which fields to group by and which {{esql}} commands to use. For example, it uses the `TS` command for time series metrics.
+
 ### Context-awareness with multiple data types
 
 Your query may include multiple data types that each have tailored experiences; for example, if you query both `logs-*` and `traces-*` indices within an Observability context.
 
 In this case **Discover** provides the default experience until it detects that you're interacting with a single type of data. For example, when you [](#look-inside-a-document).
 
@@ -395,6 +397,40 @@
 To share your search and **Discover** view with a larger audience, click {icon}`share` **Share** in the application menu. For detailed information about the sharing options, refer to [Reporting](../report-and-share.md).
 
 
+## Analyze your data with AI [analyze-with-ai]
+
+```{applies_to}
+stack: ga 9.5
+serverless: ga
+```
+
+**Discover** integrates with [{{agent-builder}}](../ai-features/elastic-agent-builder.md) to provide AI-powered analysis of your {{esql}} query results. The [`discover-data-analysis` skill](../ai-features/agent-builder/builtin-skills-reference.md#agent-builder-discover-data-analysis-skill) runs aggregation queries against the full dataset behind your current view, renders a chart for the main finding, and proposes drill-down queries you can run in a new tab.
+
+This feature is available only when **Discover** is in {{esql}} mode.
+
+To start an analysis:
+
+1. Switch to {{esql}} mode and run a query so results are loaded in the table.
+2. Select the **AI Agent** button in the {{kib}} header, or press {kbd}`cmd+;` (Mac) / {kbd}`ctrl+;` (Windows and Linux), to open the agent chat.
+
+   When you open the agent on a new {{esql}} tab that has no active conversation, the analysis starts automatically. Otherwise, ask the agent to analyze your data.
+
+3. Review the agent's findings, the inline visualization, and the suggested drill-down queries.
+
+You can also ask the agent for follow-up analyses, including correlations between fields, time-over-time comparisons, and field statistics for specific columns.
+
+### Context-aware deep analysis
+
+When your data matches one of the [context-aware experiences](#context-aware-discover), the agent receives shape-specific guidance so the analysis is tailored to the data type:
+
+* **Logs**: groups by `log.level`, `service.name`, `host.name`, and `event.dataset`; surfaces error and warning frequency and shifts in level distribution.
+* **Metrics**: uses the {{esql}} `TS` source command for time series data streams, runs `TS_INFO` first to discover metric names, types, and dimension fields, then aggregates with the right function for each metric type (`RATE` or `SUM` for counters, `AVG`, `MAX`, `MIN`, or `PERCENTILE` for gauges, `PERCENTILE` for histograms).
+* **APM traces**: focuses on latency percentiles of transaction and span durations, throughput by transaction or span name, and error rate via `event.outcome`.
+* **OTel traces**: focuses on latency percentiles of `duration`, throughput by service and span kind, and error rate via `status.code`.
+
+If your query doesn't match any context-aware profile, the agent infers the analysis strategy from the column names and types in the results instead.
+
+
 ## Generate alerts [alert-from-Discover]
 
 From **Discover**, you can create a rule to periodically check when data goes above or below a certain threshold within a given time interval.