---
title: Agent skill
description: The {agent-skill} directive renders a standardized callout that points readers to an Elastic AI agent skill. When the URL includes a skill name (after...
url: https://www.elastic.co/elastic/docs-builder/docs/3431/reference/docs-builder/syntax/agent-skill
products:
  - Elastic Docs Builder
---

# Agent skill
The `{agent-skill}` directive renders a standardized callout that points readers to an [Elastic AI agent skill](https://github.com/elastic/agent-skills). When the URL includes a skill name (after `@`), it shows a "Copy install command" button that copies the `npx skills add owner/repo@skill-name` command to clipboard. Otherwise, it falls back to a "Get the skill" link.

## Usage

By default, the directive renders a standard description with a copy button:
<tab-set>
  <tab-item title="Output">
    <agent-skill url="https://github.com/elastic/agent-skills@elasticsearch-esql">
      A skill is available to help AI agents with this topic.
    </agent-skill>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{agent-skill}
    :url: https://github.com/elastic/agent-skills@elasticsearch-esql
    :::
    ```
  </tab-item>
</tab-set>

You can also provide custom body text to clarify the scope of the skill:
<tab-set>
  <tab-item title="Output">
    <agent-skill url="https://github.com/elastic/agent-skills@elasticsearch-esql">
      A skill is available to help AI agents with this topic.
      This skill helps agents write and optimize ES|QL queries.
    </agent-skill>
  </tab-item>

  <tab-item title="Markdown">
    ```markdown
    :::{agent-skill}
    :url: https://github.com/elastic/agent-skills@elasticsearch-esql

    This skill helps agents write and optimize ES|QL queries.
    :::
    ```
  </tab-item>
</tab-set>


## Properties


| Property | Required | Description                                                                                 |
|----------|----------|---------------------------------------------------------------------------------------------|
| `:url:`  | Yes      | Absolute URL to the skill. Include `@skill-name` to enable the copy install command button. |

The `:url:` property must be an absolute URL. Relative paths are not accepted, and the directive will emit a build error if the URL is missing or relative.
The skill name is extracted from the URL as the segment after the final `@`, and the repository prefix is extracted from the URL path. For example, `https://github.com/elastic/agent-skills@elasticsearch-esql` produces the install command `npx skills add elastic/agent-skills@elasticsearch-esql`.