---
title: Agent skill
description: The {agent-skill} directive renders a standardized callout that points readers to an Elastic AI agent skill. It includes a "Get the skill" button linking...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2736/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). It includes a "Get the skill" button linking to the skill's URL.

## Usage

By default, the directive renders a standard description:
<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 on GitHub. |

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.