Add Agent Builder skills + dashboards/viz documentation by leemthompo · Pull Request #5868 · elastic/docs-content

leemthompo · 2026-04-11T08:31:49Z

Contributes to https://github.com/elastic/docs-content-internal/issues/1041

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

Note

Dashboards component was approved in #5915

👀 URL preview

Summary

Adds three new pages for the Agent Builder skills feature: skills.md (overview), skill-creation-guidelines.md (guidelines), and builtin-skills-reference.md (reference)
Adds Skills APIs section to kibana-api.md with examples for all five CRUD operations
Cross-links skills into prompt-engineering.md, tools.md, and builtin-tools-reference.md
Wires all new pages into toc.yml

New pages

skills.md — Overview: what skills are, how agents use them, built-in vs custom, create via UI and API, add to agent, Skills API list.

skill-creation-guidelines.md — Structured guidance for writing effective skill descriptions and instructions. Covers deciding where to put instructions (skill vs system prompt), writing clear and semantically distinct descriptions, structuring instructions with trigger conditions and edge cases, scoping each skill to one task, using referenced_content, assigning only relevant tools, and testing the skill. Includes annotated code examples throughout.

builtin-skills-reference.md — Full reference listing all located built-in skills with inline applies_to tags, section-level serverless scoping, $$$anchor-ids$$$ for deep linking, and an inline tools section.

Open items

6 search.* skills (ES project): source files not yet located in Kibana — descriptions are from UI only, tools unconfirmed
dashboard-management: confirm whether the Experimental flag applies in all projects or only Security
observability.rca: confirm GA vs preview — marked experimental: true in Kibana source
observability.investigation: commented out pending elastic/kibana#262293

Introduces three new pages for the Agent Builder skills feature: - `skills.md`: Overview of how skills work, when to use them, how to create custom skills via UI and API, and how to assign them to agents. - `skill-creation-guidelines.md`: Structured guidance for writing effective skill descriptions and instructions, with annotated examples for trigger conditions, core instructions, edge cases, and referenced content. Includes a decision guide for choosing between skills, the system prompt, and direct conversation. - `builtin-skills-reference.md`: Full reference listing all built-in skills with applies_to tags, anchor IDs, and an inline tools section. Also updates existing pages to integrate skills into the broader Agent Builder docs: Skills APIs added to `kibana-api.md`, cross-references added to `prompt-engineering.md`, `tools.md`, `builtin-tools-reference.md`, and `custom-agents.md`. All three new pages wired into `toc.yml`.

github-actions · 2026-04-11T08:38:30Z

🔍 Preview links for changed docs

Vale Linting Results

Summary: 2 warnings, 4 suggestions found

⚠️ Warnings (2)

File	Line	Rule	Message
explore-analyze/ai-features/agent-builder/builtin-skills-reference.md	88	Elastic.Spelling	'chatbot' is a possible misspelling.
explore-analyze/ai-features/agent-builder/tools.md	17	Elastic.EndPuntuaction	Don't end headings with punctuation.

💡 Suggestions (4)

File	Line	Rule	Message
explore-analyze/ai-features/agent-builder/builtin-skills-reference.md	51	Elastic.Semicolons	Use semicolons judiciously.
explore-analyze/ai-features/agent-builder/builtin-skills-reference.md	51	Elastic.Semicolons	Use semicolons judiciously.
explore-analyze/ai-features/agent-builder/builtin-skills-reference.md	65	Elastic.WordChoice	Consider using 'atypical, not typical' instead of 'abnormal', unless the term is in the UI.
explore-analyze/ai-features/agent-builder/skills.md	17	Elastic.WordChoice	Consider using 'efficient' instead of 'easy', unless the term is in the UI.

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

Co-authored-by: Kenneth Kreindler <42113355+KDKHD@users.noreply.github.com>

…lt-in skills Co-authored-by: Kenneth Kreindler <42113355+KDKHD@users.noreply.github.com>

Co-authored-by: Kenneth Kreindler <42113355+KDKHD@users.noreply.github.com>

- Rename headings to consistent imperative form throughout - Promote single-responsibility principle to its own H2 ("Scope each skill to one task") - Promote semantically-distinct descriptions to H3 with checklist entry - Expand checklist with sub-headings for all sections - Add "Test your skill" section; remove defensive disclaimer from intro - Fix misleading callout on "Too vague" description example - Surface buried guidance (vague openings, tool documentation) via tip admonitions and paragraph breaks

- Replace removed alert-analysis skill example in skills.md with entity-analytics - Drop #inline-tools fragment from tools.md and builtin-tools-reference.md (no standalone anchor exists)

…e example; add alert investigation mention Agent-Logs-Url: https://github.com/elastic/docs-content/sessions/228c17be-926d-4046-ae10-c7da3c0dae84 Co-authored-by: leemthompo <32779855+leemthompo@users.noreply.github.com>

## Summary - Add new `dashboards-and-visualizations.md` page documenting how agents create, edit, and save dashboards and Lens visualizations through chat - Uncomment dashboard tools (`dashboard.create_dashboard`, `dashboard.update_dashboard`) and `platform.core.create_visualization` in built-in tools reference - Add cross-reference from core dashboard docs (`create-dashboard.md`) - Add brief mention + link in `chat.md` pointing to the new page - Add new page to `toc.yml` as a child of `chat.md` Closes elastic/docs-content-internal#1008 **Note:** Screenshot placeholders are wired up in the new page. Image files still need to be added to `explore-analyze/ai-features/agent-builder/images/`: 1. `agent-builder-dashboard-canvas-preview.png` 2. `agent-builder-dashboard-save-dialog.png` 3. `agent-builder-dashboard-outdated-notification.png` ## TODO - [ ] Verify new page renders correctly in docs-builder - [ ] Verify toc.yml entry places the page under Chat > Dashboards and visualizations - [ ] Verify cross-links resolve (skills reference anchors, tools reference anchors, create-dashboard.md link) - [ ] Add screenshot image files and verify they render - [ ] Coordinate merge with #5850 (Charlotte's UI screenshot updates touch some of the same files) 🤖 Generated with [Claude Code](https://claude.com/claude-code) ## Preview (click on me) <img width="2896" height="10722" alt="Screenshot 2026-04-16 at 14-44-41 Dashboards and visualizations in Elastic Agent Builder chat Elastic Docs" src="https://github.com/user-attachments/assets/a51db003-fca8-431d-ac44-c856df8d79df" /> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

- skills.md: Lead opening with user value before the definition - custom-skills.md: Add "When to create" section, outcome sentence, test step in stepper, and tip for import vs. create inline - skill-creation-guidelines.md: Use action verb title, add Next steps, deduplicate Related pages Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

benironside

I reviewed the new pages only. They look great. Left one small suggestion and a couple minor edits. Everything LGTM. Approving. The Skill creation guidelines in particular look excellent. Good job!

mdbirnstiehl

Nice work, @leemthompo! 🥇

mdbirnstiehl · 2026-04-17T18:29:29Z

+
+# Dashboards and visualizations in {{agent-builder}} chat
+
+Agents can create and manage [dashboards](/explore-analyze/dashboards.md) and [visualizations](/explore-analyze/visualize.md) directly in the conversation. Ask a question like "create a dashboard to monitor host CPU and memory usage" and the agent builds a dashboard with {{esql}}-powered visualization panels.


A nit and not sure how we want to talk about dialog with the agent, but not really a question.

good point 👍

Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Co-authored-by: Liam Thompson <leemthompo@gmail.com>

Co-authored-by: Liam Thompson <leemthompo@gmail.com>

…hods (#6059) ## [URL preview](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/6059/explore-analyze/ai-features/agent-builder/skills) ## Summary - Adds **Skills** as a fourth key concept on the Agent Builder overview page alongside Agent Chat, Agents, and Tools - Enriches the `skills.md` intro with a structured breakdown of what a skill bundles (instructions, tools, context) and how skills differ from tools and system prompts - Documents the three skill invocation methods: automatic discovery, slash commands (with screenshot), and attachment-driven activation - Updates `get-started.md` final step to lead with skills as the primary extension point - Links use case examples to the Security and Observability solution-specific Agent Builder pages ## Related - Tracks against #5719 (core AB collab items) - Builds on #5868 (skills docs: concept page, custom skills, built-in skills reference, skill creation guidelines) - Coordinates with #5850 (9.4 UI refresh, which adds skills mentions to the agents overview page) ## Test plan - [x] Verify cross-links resolve: `skills.md`, `builtin-skills-reference.md`, `custom-skills.md`, `skill-creation-guidelines.md`, solution-specific pages - [x] Verify `skill-slash-command.png` renders at correct size - [x] Confirm no merge conflicts with #5850 on `get-started.md` 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

@dhru42

## Summary Fixes #5718, #5719, and #5720. ### New pages - **`solutions/security/ai/agent-builder/skills-model.md`** — "Agents, skills, and tools" conceptual page for Security. Explains the one-agent-many-skills model in 9.4, with a comparison table (Agent / Skill / Tool), an Enable/manage section, the Threat Hunting Agent → skill relationship, and a short FAQ - **`solutions/security/ai/agent-builder/skills-use-cases.md`** — "Security use cases for Agent Builder." One section per SOC workflow, each naming the built-in skill(s) to enable and 3 example prompts grounded in what the skill actually does (pulled from the Kibana source) ### Updated pages - **`solutions/security/ai/agent-builder/agent-builder.md`** — added an `applies-switch` so 9.3 keeps the Threat Hunting agent content and 9.4 shows the skills-based content, with links to the two new pages. - **`explore-analyze/ai-features/agent-builder/builtin-agents-reference.md`** — Threat Hunting Agent section marked `deprecated 9.4`, with a prominent deprecation warning and a migration-path block pointing to the `threat-hunting` skill. - **`explore-analyze/ai-features/agent-builder/builtin-skills-reference.md`** — added two Security skills that were missing: - `alert-analysis` (GA 9.4+) - `automatic_troubleshooting` (preview 9.4, experimental feature flag) Also added "Supports ES|QL rule type only" to `detection-rule-edit` (real constraint from the source). - **`explore-analyze/ai-features/ai-chat-experiences/ai-agent-or-ai-assistant.md`** — applied your comparison-table updates for 9.4 (via `applies-switch` so 9.3 preserves the old tables): - **`solutions/toc.yml`** — adds the two new Security pages as children of `agent-builder.md`, concepts first then use cases. ## Attention @dhru42: Please double check the following: - [ ] **`alert-analysis` skill** — it's live in the Kibana source but wasn't in the #5868 built-in skills update. Confirm this should ship in 9.4 GA docs and that my description is right. - [ ] **`automatic_troubleshooting` skill** — source registers it behind the `automaticTroubleshootingSkill` experimental flag. Confirm preview + flag-gated framing is right, or whether it should be held out of docs entirely for 9.4. - [ ] **Example prompts** — grounded in Kibana source, but you may have better real-world prompts from demos/POCs. ## What's not here - **Release notes** — will be handled separately. - **Screenshots** — need a test env then I'll add some. ## Generative AI disclosure 1. Did you use a generative AI (GenAI) tool to assist in creating this contribution? - [ x] Yes Claude 4.6 & 4.7 / Cursor - [ ] No

leemthompo requested review from a team as code owners April 11, 2026 08:31

Fix unknown language identifier in skill-creation-guidelines code blocks

0580d28

leemthompo marked this pull request as draft April 11, 2026 08:43

leemthompo self-assigned this Apr 13, 2026

KDKHD reviewed Apr 13, 2026

View reviewed changes

leemthompo and others added 10 commits April 13, 2026 11:20

a skill is not always selected

e210e86

Co-authored-by: Kenneth Kreindler <42113355+KDKHD@users.noreply.github.com>

Inline tools is an implementation detail that is only relevant to bui…

e116b30

…lt-in skills Co-authored-by: Kenneth Kreindler <42113355+KDKHD@users.noreply.github.com>

skills associated tools are only built in, also custom tools

4ba23f2

Co-authored-by: Kenneth Kreindler <42113355+KDKHD@users.noreply.github.com>

delete unregistered sample skill from list

74b5011

Co-authored-by: Kenneth Kreindler <42113355+KDKHD@users.noreply.github.com>

delete sample skill

49cc761

Co-authored-by: Kenneth Kreindler <42113355+KDKHD@users.noreply.github.com>

Move inline tools under parent skill entry

f0cf4bf

Add character limits for name and description fields

8153db5

Add 1024-character limit for description field

d3f57ae

Fix broken anchor links in skills and tools pages

16ad0aa

- Replace removed alert-analysis skill example in skills.md with entity-analytics - Drop #inline-tools fragment from tools.md and builtin-tools-reference.md (no standalone anchor exists)

masci requested a review from arturoliduena April 13, 2026 13:10

neptunian reviewed Apr 13, 2026

View reviewed changes

Comment thread explore-analyze/ai-features/agent-builder/skills.md Outdated

neptunian reviewed Apr 13, 2026

View reviewed changes

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

Copilot started work on behalf of leemthompo April 13, 2026 15:33 View session

Copilot finished work on behalf of leemthompo April 13, 2026 15:36

neptunian approved these changes Apr 13, 2026

View reviewed changes

Copilot started work on behalf of KDKHD April 14, 2026 10:01 View session

Copilot finished work on behalf of KDKHD April 14, 2026 10:04

Copilot AI requested a review from KDKHD April 14, 2026 10:04

KDKHD approved these changes Apr 14, 2026

View reviewed changes

Merge branch 'main' into leemthompo/AB-skills

e245fe5

leemthompo marked this pull request as ready for review April 16, 2026 13:34

leemthompo changed the title ~~Add Agent Builder skills documentation~~ Add Agent Builder skills + dashboards documentation Apr 16, 2026

leemthompo changed the title ~~Add Agent Builder skills + dashboards documentation~~ Add Agent Builder skills + dashboards/viz documentation Apr 16, 2026

charlotte-hoblik reviewed Apr 17, 2026

View reviewed changes

leemthompo and others added 4 commits April 17, 2026 12:58

fixes per @charlotte-hoblik's review

6cbde67

Merge branch 'main' into leemthompo/AB-skills

0cbe4f7

deduplicate related pages and next steps link lists

63e99f0

benironside approved these changes Apr 17, 2026

View reviewed changes

Comment thread explore-analyze/ai-features/agent-builder/skills.md Outdated

Comment thread explore-analyze/ai-features/agent-builder/skills.md Outdated

Comment thread explore-analyze/ai-features/agent-builder/skills.md Outdated

mdbirnstiehl approved these changes Apr 17, 2026

View reviewed changes

leemthompo commented Apr 19, 2026

View reviewed changes

Comment thread explore-analyze/ai-features/agent-builder/skills.md Outdated

leemthompo and others added 2 commits April 19, 2026 15:07

Apply suggestions from review

8100851

Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> Co-authored-by: Liam Thompson <leemthompo@gmail.com>

Merge branch 'main' into leemthompo/AB-skills

57ac102

leemthompo commented Apr 19, 2026

View reviewed changes

Comment thread explore-analyze/ai-features/agent-builder/skills.md Outdated

leemthompo and others added 7 commits April 19, 2026 15:10

rework opening skills paragragh again

9e28593

Co-authored-by: Liam Thompson <leemthompo@gmail.com>

clarify skills assignment flows

05ac89c

clarify skills assignment flows even more

766e061

clarify skills creation/management UI story

f9ed16b

tighten up custom-skills.md

30c92e0

fix broken ref

30aefdf

fix per @mdbirnstiehl's review

ba95079

charlotte-hoblik self-requested a review April 20, 2026 07:28

charlotte-hoblik approved these changes Apr 20, 2026

View reviewed changes

leemthompo merged commit 2115419 into main Apr 20, 2026
8 checks passed

leemthompo deleted the leemthompo/AB-skills branch April 20, 2026 07:34

leemthompo mentioned this pull request Apr 22, 2026

[agent builder] Add Skills as key concept and document invocation methods #6059

Merged

3 tasks


		# Dashboards and visualizations in {{agent-builder}} chat

		Agents can create and manage [dashboards](/explore-analyze/dashboards.md) and [visualizations](/explore-analyze/visualize.md) directly in the conversation. Ask a question like "create a dashboard to monitor host CPU and memory usage" and the agent builds a dashboard with {{esql}}-powered visualization panels.

Conversation

leemthompo commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Contributes to https://github.com/elastic/docs-content-internal/issues/1041

👀 URL preview

Summary

New pages

Open items

Uh oh!

github-actions Bot commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions Bot commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vale Linting Results

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

benironside left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mdbirnstiehl left a comment

Choose a reason for hiding this comment

Uh oh!

mdbirnstiehl Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

leemthompo Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

leemthompo commented Apr 11, 2026 •

edited

Loading

github-actions Bot commented Apr 11, 2026 •

edited

Loading

github-actions Bot commented Apr 11, 2026 •

edited

Loading