> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# skills

> Defines a set of instructions for the Omni Agent that users can trigger with a button click.

Defines a set of instructions for the Omni Agent that users can trigger with a button click. Skills can be defined at the topic level (in topic files) or at the model level (in model files).

When triggered, the AI follows those instructions — querying data, summarizing results, interacting with the user, or walking through a multi-step process — all without the user needing to write a prompt. Each defined skill will display as a button in the [Omni Agent](/ai/chat).

See the [Agent Skills guide](/ai/skills) for more information about this feature, including use cases and best practices.

## Syntax

```yaml theme={null}
skills:
  <skill_id>:
    label: <string>
    input: |
      <string>
    description: |
      <string>
    required_access_grants: [ <access_grant_name> ]
```

## Properties

<ParamField path="skills" type="object" required>
  A map of skills, each defined with a unique `skill_id`.

  <Expandable title="skill properties" defaultOpen="true">
    <ParamField path="skill_id" type="string" required>
      A unique name for the skill. Use underscores for spaces.

      <Expandable title="skill_id properties" defaultOpen="true">
        <ParamField path="label" type="string" required>
          The display name shown on the skill button. Keep this short — aim for 2-4 words that clearly describe the task.
        </ParamField>

        <ParamField path="input" type="string">
          An opening message that sets the initial interaction. This is sent to the AI before the `description` and is useful for:

          * Greeting the user and explaining what the skill does
          * Asking the user for input before proceeding (e.g., an account name or date range)

          When `input` is set, the AI will typically respond to the `input` first, then use the `description` as its instructions for the rest of the conversation.
        </ParamField>

        <ParamField path="description" type="string" required>
          The instructions sent to the AI when the skill is triggered. This can range from a single sentence to a detailed, multi-step prompt with specific output formats, decision logic, and references to topics.

          Write this as if you're instructing an analyst: be specific about which data to query, how to structure the output, and what steps to follow.
        </ParamField>

        <ParamField path="required_access_grants" type="string[]">
          Controls skill visibility based on user access grants. Skills with this parameter will only appear to users who hold the required access grants.

          Values must match [`access_grants`](/modeling/models/access-grants) defined in the model file. Supports conditional grant expressions using `|` for OR and `&` for AND conditions.

          **Note**: This controls visibility only. Actual data access at execution time is still enforced by access grants on the underlying topics, fields, and views the skill touches.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

<Tip>
  See the [Agent Skills guide](/ai/skills) for additional examples.
</Tip>

```yaml title="Topic-level skill" theme={null}
skills:
  top_customers_in_region:
    label: Top Customers
    description: >
      Find the top 20 customers by total lifetime revenue in this region.
      Include customer name, total revenue, order count,
      and date of most recent order. Sort by revenue descending.
```

```yaml title="Skill with required access grants" theme={null}
skills:
  finance_summary:
    label: Finance Summary
    description: >
      Generate a financial summary including revenue, costs, and margins.
    required_access_grants: [ finance ]
```

```yaml title="Skill with conditional access grants" theme={null}
skills:
  regional_analysis:
    label: Regional Analysis
    description: >
      Analyze performance metrics for the user's assigned region.
    required_access_grants: [ northwest_region|southwest_region ]
```