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

# Configuring skills for agents

> Write and structure Atlas AI agent skills to give agents domain-specific knowledge for accurate, consistent responses.

Skills give Atlas AI agents domain-specific knowledge for a particular task or dataset.

## Before you start

You must have an agent configured in the [Agent builder](/cdf/atlas_ai/guides/atlas_ai_agent_building) before you can attach skills to it.

## Creating a skill

The Agent builder includes a skill builder that generates a structured skill from a description or source document. You can also write skills manually in markdown.

<Steps>
  <Step title="Open the skill builder">
    In CDF, navigate to **Atlas AI** > **Agent builder** and open your agent.

    Select **Skills**, then select **+ Add skill**.
  </Step>

  <Step title="Provide source material">
    To generate a skill automatically, paste in or upload source material relevant to the skill's domain. Suitable sources include SOPs, engineering specification documents, naming convention guides, and equipment manuals.

    The skill builder extracts the structure, vocabulary, and rules from the source material and produces a draft skill. This can be faster than writing a skill manually and works well for skills that cover naming conventions, tag formats, and asset hierarchies.

    <Tip>
      If you provide an existing document, review the generated skill for accuracy before saving. The skill builder produces a structured draft, but domain-specific rules may require adjustment.
    </Tip>
  </Step>

  <Step title="Review and complete the skill structure">
    Review each section of the generated skill and complete any sections that need adjustment. See [Structuring a skill](#structuring-a-skill) for guidance on each section.
  </Step>

  <Step title="Save and attach the skill to your agent">
    Save the skill and attach it to your agent. Test the agent with questions that should trigger the skill to verify that it loads correctly and improves the agent's responses.

    Use [agent evaluations](/cdf/atlas_ai/guides/atlas_ai_agent_evaluating) to confirm behavior against expected responses before publishing.
  </Step>
</Steps>

## Structuring a skill

A well-structured skill contains these sections. Not every skill requires all of them, but each section you include should be specific and accurate.

<Steps>
  <Step title="Write a trigger description">
    The trigger description tells the agent when to load this skill. Write it as a direct statement that identifies the relevant question type, equipment category, or data domain.

    ```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    Use this skill when the user asks about maintenance orders, work orders, or planned maintenance for rotating equipment, including pumps, compressors, and turbines.
    ```

    A clear trigger prevents the agent from loading the skill for unrelated questions.
  </Step>

  <Step title="Add data model guidance">
    Tell the agent which views to query and which properties are relevant for this skill's domain. The Query tool can discover the schema at runtime, but explicit guidance reduces errors on frequently-used query patterns and helps the agent choose correctly when a data model has multiple date or status fields with similar names.

    ```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    Work orders are stored in the MaintenanceOrder view in the Cognite process industries data model.
    Key properties:
    - priority: integer, where 1 = high, 2 = medium, 3 = low
    - status: string, for example "OPEN", "IN_PROGRESS", "COMPLETED"
    - plannedStartDate: the scheduled start of the work
    - actualStartDate: the date work actually began
    - asset: a direct relation to the Equipment view

    Use plannedStartDate when the user asks when work is scheduled. Use actualStartDate when the user asks when work began.
    ```

    <Tip>
      When a view has multiple fields with similar names or unclear descriptions, add a note explaining which field to use for each question type. For guidance on making your data model clearer for agents, see [Optimizing data models for AI](/cdf/dm/dm_guides/dm_best_practices_ai_search).
    </Tip>
  </Step>

  <Step title="Map your vocabulary">
    Add mappings that translate the terms users are likely to use into the field values stored in CDF. This is one of the most effective ways to improve accuracy, because unclear terminology is a common source of errors in industrial data queries.

    ```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    Vocabulary:
    - "high priority" = priority = 1
    - "medium priority" = priority = 2
    - "overdue" = plannedEndDate is in the past AND status != "COMPLETED"
    - "open" = status = "OPEN" OR status = "IN_PROGRESS"
    - "rotating equipment" includes pumps (tag prefix P-), compressors (C-), and turbines (T-)
    ```
  </Step>

  <Step title="Define tool sequencing">
    Document the order in which the agent should call tools when answering questions in this skill's domain. These tabs show sequencing instructions for three common tool combinations.

    <Tabs>
      <Tab title="Sensor trend questions">
        When a user asks about sensor readings, trends, or anomalies on a piece of equipment, the agent should follow this sequence.

        ```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        1. Use the Query tool to identify the relevant time series for the equipment in the knowledge graph.
           Look for time series linked to the asset with a description or tag that matches the sensor type the user is asking about (for example, vibration, temperature, pressure).

        2. Use the Query time series data points tool to retrieve the values for the requested period.
           If the user does not specify a time period, default to the last 24 hours.

        3. If the user asks about trends, anomalies, or comparisons to a previous period, use the Analyze time series tool to perform the calculation. Do not estimate trends from raw values.
        ```
      </Tab>

      <Tab title="Document questions">
        When a user asks a question that refers to a procedure, manual, specification, or inspection report, the agent should follow this sequence.

        ```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        1. Use the Query tool to find the relevant file in the knowledge graph. Search for files linked to the equipment the user is asking about, and filter by document type or title if the user specifies one.

        2. Confirm the file name and its relationship to the asset before proceeding.

        3. Use Answer document questions to retrieve the answer from the file's contents.
           Quote the relevant excerpt in your response so the user can verify the source.
        ```
      </Tab>

      <Tab title="Follow-up analysis">
        When a user asks a follow-up question about data that was already retrieved in the same conversation, the agent should use the Examine data semantically tool rather than querying the knowledge graph again.

        ```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
        If the user asks a follow-up question about previously retrieved results (for example, "of those work orders, which ones were delayed?"), use Examine data semantically to analyze the existing result set.

        Do not issue a new knowledge graph query for follow-up questions that refer to data already in the conversation. This avoids duplicate queries and keeps the response focused on the results the user has already seen.
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Define the response format">
    Tell the agent what a complete answer looks like for this skill's domain. Include which fields to show and any formatting preferences.

    ```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    When listing work orders, always include the following fields:
    - Work order ID
    - Description
    - Priority (display as High, Medium, or Low rather than as a number)
    - Status
    - Planned start date
    - Asset name

    Present the results as a table when listing multiple work orders. If there are more than 10 results, summarize the total count and highlight the highest-priority items.
    ```
  </Step>

  <Step title="Add examples">
    Include examples that show the agent how to handle the most common question patterns for this skill. A few examples covering distinct scenarios are more effective than a long list of similar ones. Cover different question types: a simple lookup, an aggregation, a multi-tool question, and an ambiguous request.

    ```text wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
    Example 1: Simple lookup
    User: Show me the last 5 work orders for Pump P-101.
    Action: Query the MaintenanceOrder view, filter on asset = P-101, sort by plannedStartDate descending, limit to 5 results.

    Example 2: Aggregation
    User: How many open work orders are there for each equipment type?
    Action: Use the aggregate_instances operation to count open work orders grouped by asset type.
    Do not retrieve all work orders and count them manually.

    Example 3: Multi-tool
    User: Are there any active alarms on Compressor C-205 and is there a related open work order?
    Action: Query the knowledge graph for active alarms linked to C-205, then query for open work orders linked to the same asset. Summarize both sets of results together.

    Example 4: Ambiguous request
    User: Fix this pump.
    Action: Explain that you cannot take action on physical equipment. Retrieve the current status, open work orders, and recent alarms for the pump, and suggest that the user review the findings and raise a work order if needed.
    ```
  </Step>
</Steps>

## Limitations

| Limit                | Details                                                                                |
| -------------------- | -------------------------------------------------------------------------------------- |
| File format          | Single `.md` file only. Zip archives and associated files are not supported.           |
| File size            | 30 KB maximum.                                                                         |
| Name format          | Alphanumeric characters and hyphens (`-`) only. No other symbols are allowed.          |
| Reserved name prefix | Names must not start with `cdf-`. This prefix is reserved for Cognite packaged skills. |

## Related information

* [About Atlas AI agent skills](/cdf/atlas_ai/concepts/atlas_ai_agent_skills)
* [Building agents](/cdf/atlas_ai/guides/atlas_ai_agent_building)
* [Running agent evaluations](/cdf/atlas_ai/guides/atlas_ai_agent_evaluating)
* [Query tool](/cdf/atlas_ai/references/atlas_ai_query_tool)
* [Agent tools library](/cdf/atlas_ai/references/atlas_ai_agent_tools)
* [Optimizing data models for AI](/cdf/dm/dm_guides/dm_best_practices_ai_search)