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

explore-analyze/ai-features/agent-builder/get-started.md

@@ -145,11 +145,13 @@ On {{ech}} and {{serverless-full}}, {{agent-builder}} comes with preconfigured m
 
 ::::
 
-::::{step} Begin building agents and tools
+::::{step} Build custom skills and tools
 
-Once you've tested [built-in agents](builtin-agents-reference.md) with [built-in Elastic tools](tools.md), you can begin [building your own agents](custom-agents.md#create-a-new-agent) with custom instructions and [creating your own tools](tools/custom-tools.md#create-custom-tools-in-the-ui) to assign them. You can also clone the default `Elastic AI Agent` as a starting point for a custom agent.
+The default [Elastic AI Agent](builtin-agents-reference.md) comes with [built-in skills](builtin-skills-reference.md) and [built-in tools](tools.md) ready to use. To add your own domain expertise, [create custom skills](custom-skills.md) that package knowledge and tools into reusable instruction sets. For tips on writing effective skill instructions, refer to the [skill creation guidelines](skill-creation-guidelines.md). To learn how skills are invoked during a conversation, refer to [how skills are invoked](skills.md#how-skills-are-invoked).
 
-To build agents and tools programmatically, try the [{{agent-builder}} API tutorial](agent-builder-api-tutorial.md) or explore the [Kibana APIs](programmatic-access.md).
+You can also [create custom tools](tools/custom-tools.md#create-custom-tools-in-the-ui) to give your skills and agents access to additional data sources. If you need a fully separate agent with its own system prompt, you can [create a custom agent](custom-agents.md#create-a-new-agent).
+
+To work programmatically, try the [{{agent-builder}} API tutorial](agent-builder-api-tutorial.md) or explore the [Kibana APIs](programmatic-access.md).
 
 ::::
 

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

@@ -14,25 +14,41 @@
 
 # Skills in {{agent-builder}}
 
-A skill is a reusable instruction set that gives [agents](agent-builder-agents.md) specialized expertise for a particular type of task. Instead of embedding the same detailed instructions in every agent that needs them, you author a skill once and assign it wherever it's needed. This keeps agent configurations clean and makes expertise easy to maintain and share across your team.
+A skill is a reusable capability pack that gives an [agent](agent-builder-agents.md) specialized expertise for a particular type of task. Each skill bundles three things:
 
-Tools are discrete operations the agent can invoke. Skills are higher-level capability packs that bundle tools, instructions, and context for a specific task domain. To learn more about tools, refer to [Tools](tools.md).
+- **Instructions**: domain-specific guidance written in Markdown that shapes how the agent approaches the task.
+- **Tools**: [built-in](tools/builtin-tools-reference.md) or [custom](tools/custom-tools.md) tools the agent can call while the skill is active.
+- **Context**: additional knowledge the skill can draw on, such as reference documents or runbooks.
 
-Skills differ from the agent's base system prompt: the system prompt is always in context, while skills are loaded selectively. An agent can have access to many skills without loading them all into the context window at once.
+This makes skills different from [tools](tools.md), which are discrete operations like running a query or retrieving a document. Skills sit one level higher, combining tools with the instructions and context needed to complete a workflow end to end.
 
-## How agents use skills
+Skills also differ from the agent's system prompt. The system prompt is always in context, while skills load selectively. An agent can have access to many skills without loading them all into the context window at once. You author a skill once and assign it to any agent that needs it, keeping agent configurations clean and making expertise easy to share across your team.
 
-When an agent receives a message, it selects a skill if it determines that one of the available skills is relevant to the query based on the skill's name and description. If a skill activates, it provides:
+## How skills are invoked
 
-- **Knowledge content**: domain-specific instructions written in Markdown that tell the agent how to approach the task.
-- **Tools**: [Built-in tools](tools/builtin-tools-reference.md) or [custom tools](tools/custom-tools.md)  that the agent can call while the skill is active.
+Skills can be invoked in three ways:
+
+**Automatic discovery (default)**
+:   The agent receives a list of available skills with their names and descriptions. Based on the user's natural language input, it automatically selects and invokes the most relevant skill. No special syntax is needed.
+
+**Slash commands**
+:   Users can explicitly invoke a skill by typing `/` followed by the skill name and a prompt. This is useful when you know exactly which skill you need.
+
+:::{image} images/skill-slash-command.png
+:alt: Chat input showing a slash command that invokes the visualization-creation skill
+:width: 550px
+:screenshot:
+:::
+
+**Attachment-driven**
+:   When a user attaches contextual data to a message (for example, an alert from the alert flyout), the agent can automatically invoke the relevant skill based on the attachment type.
 
 ## Use cases
 
 Use skills when you have domain-specific knowledge or procedures that multiple agents should follow consistently. Some examples:
 
-- An {{product.security}} user asks about a suspicious host. The [`entity-analytics`](builtin-skills-reference.md#agent-builder-entity-analytics-skill) skill activates and guides the agent through finding the entity, analyzing its risk score, asset criticality, and behavioral history.
-- An {{product.observability}} user asks why a service is slow or why an alert fired. The [`observability.investigation`](builtin-skills-reference.md#agent-builder-observability-investigation-skill) skill activates and diagnoses the issue across APM services and infrastructure.
+- An [{{product.security}}](/solutions/security/ai/agent-builder/agent-builder.md) user asks about a suspicious host. The [`entity-analytics`](builtin-skills-reference.md#agent-builder-entity-analytics-skill) skill activates and guides the agent through finding the entity, analyzing its risk score, asset criticality, and behavioral history.
+- An [{{product.observability}}](/solutions/observability/ai/agent-builder-observability.md) user asks why a service is slow or why an alert fired. The [`observability.investigation`](builtin-skills-reference.md#agent-builder-observability-investigation-skill) skill activates and diagnoses the issue across APM services and infrastructure.
 - An {{product.elasticsearch}} user asks how to combine keyword and vector search for a product catalog. The [`search.hybrid-search`](builtin-skills-reference.md#agent-builder-search-hybrid-search-skill) skill activates and guides the agent through building a hybrid search solution.
 
 ## Built-in skills

explore-analyze/ai-features/elastic-agent-builder.md

@@ -38,14 +38,15 @@ This feature requires the appropriate {{stack}} [subscription](https://www.elast
 - **Built-in agents and tools**: Get started immediately with pre-configured [agents](agent-builder/builtin-agents-reference.md) and [tools](agent-builder/tools/builtin-tools-reference.md) available out of the box.
 - **Chat UI**: [Chat with agents](agent-builder/chat.md) in real time using natural language.
 - **Custom and external tools**: Build targeted [custom tools](agent-builder/tools/custom-tools.md) to deliver precise context, or import external tools through the [Model Context Protocol](agent-builder/tools/mcp-tools.md).
+- **Skills**: Extend agents with domain-specific expertise using [built-in skills](agent-builder/builtin-skills-reference.md) or [custom skills](agent-builder/custom-skills.md) that bundle knowledge and tools for specific task domains.
 - **Custom agents**: Create [agents with tailored instructions](agent-builder/custom-agents.md) and toolsets for specific use cases.
 - **MCP and A2A servers**: Expose tools and agents to external clients through the [MCP server](agent-builder/mcp-server.md) and [A2A server](agent-builder/a2a-server.md).
 - **Kibana REST APIs**: Work with Agent Builder functionalities [programmatically](agent-builder/kibana-api.md), including agents, tools, and conversations.
 - **[Elastic Workflows](/explore-analyze/workflows.md) integration**: Automate complex processes within your deployment using the Elastic-native automation engine. Your agents can [trigger workflows](agent-builder/agents-and-workflows.md) and [workflows can invoke agents](agent-builder/agents-and-workflows.md) in their steps.
 
 ## Key concepts
 
-The {{agent-builder}} framework consists of three key components: Agent Chat, Agents, and Tools.
+The {{agent-builder}} framework consists of four key components: Agent Chat, Agents, Skills, and Tools.
 
 ### Agent Chat
 
@@ -59,6 +60,12 @@ Agents are powered by custom LLM instructions and the ability to use tools to an
 
 [**Learn more about agents**](agent-builder/agent-builder-agents.md)
 
+### Skills
+
+Skills are reusable instruction sets that give agents specialized expertise for particular task domains. A skill bundles knowledge content and tools so the agent knows how to approach a specific type of task. Skills load selectively based on the user's query, keeping agent configurations clean while enabling deep domain expertise. Choose from a set of built-in skills, or create your own.
+
+[**Learn more about skills**](agent-builder/skills.md)
+
 ### Tools [tools-concept]
 
 Tools are modular, reusable functions that agents use to search, retrieve, and manipulate {{es}} data. Tools are the primary mechanism for connecting agent capabilities to your data. Choose from a set of built-in tools, or create your own and assign them to your custom agents.