Configuring skills for agents

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

Open the skill builder

In CDF, navigate to Atlas AI > Agent builder and open your agent.Select Skills, then select + Add skill.

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.

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.

Review and complete the skill structure

Review each section of the generated skill and complete any sections that need adjustment. See Structuring a skill for guidance on each section.

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 to confirm behavior against expected responses before publishing.

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.

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.

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.

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.

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.

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.

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.

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-)

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.

Sensor trend questions
Document questions
Follow-up analysis

When a user asks about sensor readings, trends, or anomalies on a piece of equipment, the agent should follow this sequence.

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.

When a user asks a question that refers to a procedure, manual, specification, or inspection report, the agent should follow this sequence.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

​Before you start

​Creating a skill

​Structuring a skill

​Limitations

​Related information

Before you start

Creating a skill

Structuring a skill

Limitations

Related information