> ## 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.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK https://cognite-sdk-python.readthedocs-hosted.com/en/stable/; Atlas AI /cdf/atlas_ai/index.md; plan an Atlas AI agent /cdf/atlas_ai/concepts/atlas_ai_agent_planning.md; Flows apps /cdf/flows/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Skill structure reference

> Reference for the sections of an Atlas AI agent skill, with examples for trigger descriptions, data model guidance, vocabulary mappings, tool sequencing, response formats, and examples.

The sections below describe what a well-structured Atlas AI agent skill contains. Not every skill requires all of them, but each section you include should be specific and accurate. To create a skill in the Agent builder, see [Configuring skills for agents](https://docs.cognite.com/cdf/atlas_ai/guides/atlas_ai_agent_configure_skills.md).

## 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"]}}
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.

## 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"]}}
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](https://docs.cognite.com/cdf/dm/dm_guides/dm_best_practices_ai_search.md).

## Vocabulary mappings

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"]}}
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-)
```

## 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.

> [tab] 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"]}}
> 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] 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"]}}
> 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 Ask documents to retrieve the answer from the file's contents.
>    Quote the relevant excerpt in your response so the user can verify the source.
> ```

> [tab] 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"]}}
> 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.
> ```

## 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"]}}
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.
```

## 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"]}}
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.
```

## Related information

* [About Atlas AI agent skills](https://docs.cognite.com/cdf/atlas_ai/concepts/atlas_ai_agent_skills.md)
* [Configuring skills for agents](https://docs.cognite.com/cdf/atlas_ai/guides/atlas_ai_agent_configure_skills.md)
* [Optimizing data models for AI](https://docs.cognite.com/cdf/dm/dm_guides/dm_best_practices_ai_search.md)
