> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-6-1/guides/operations/writing-service-commissioning-files-with-ai-assistance.md).

# Writing Service Commissioning Files with AI Assistance

What an AI tool needs from you before it writes service commissioning files, and how to check what comes back.

Describe the machine you want to connect, and an AI tool drafts the connections, endpoints, and mappings for you. A controller with dozens of data points becomes a service commissioning file in one pass, and your work shifts from typing YAML to reviewing it.

An AI tool provides the best results when it works from the schema for the Connectware version you run, the documentation for that version, and the conventions of your own project.

## Prerequisites

To follow this guide, you will need the following:

* Knowledge of the Connectware version that you run, for example Connectware 2.6.1.
* The connection details, data point addresses, data types, and intended MQTT topic structure. An exported controller configuration can provide the addresses and data types.
* A development Connectware instance to install and test the generated service commissioning file.
* Outbound HTTPS access on port 443 to `download.cybus.io` for the schema and to `docs.cybus.io` for the documentation.

## Choose an AI Tool

| AI Tool                                                                              | Use It When                                                                                                    | What You Set Up                                                                                                                      |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| [Service commissioning file skill](/2-6-1/tools/service-commissioning-file-skill.md) | Your AI coding agent supports Agent Skills, and you want the schema checked before you see the generated YAML. | Install the skill and connect the documentation MCP server once.                                                                     |
| [Cybus Connectware GPT](/2-6-1/tools/cybus-connectware-gpt.md)                       | You want to draft or troubleshoot a service commissioning file in a chat interface, with no local setup.       | Open it in ChatGPT.                                                                                                                  |
| Any other AI tool                                                                    | Your AI tool does not support Agent Skills, or you already work in a different one and want to keep it.        | Supply the schema and documentation yourself, as described in [Provide Version-Specific Sources](#provide-version-specific-sources). |

Whichever AI tool you choose, a [context file](#write-a-context-file) is what makes the output yours. It carries your topic hierarchy, the values that belong in parameters, and the service commissioning file you want used as a model. An AI tool that reads your files picks it up from your project. In a chat interface, paste or attach it at the start of the session.

## Generate a Service Commissioning File

Set up the sources and the context file once. Then repeat the remaining steps for each service commissioning file you write.

{% stepper %}
{% step %}

### Provide Version-Specific Sources

Skip this step if you use the [service commissioning file skill](/2-6-1/tools/service-commissioning-file-skill.md). The skill downloads the schema itself and reads the documentation through the documentation MCP server that you connect when you [install the skill](/2-6-1/tools/service-commissioning-file-skill.md#installing-the-skill).

With Cybus Connectware GPT, name the Connectware version you run in your prompt.

With any other AI tool, supply both sources yourself. Name the version you run as well: the documentation hosts every Connectware version, and an AI tool that is not told which one to read can mix them.

#### Schema

Cybus publishes one JSON Schema file per Connectware version. It covers every resource type and protocol shipped with that version.

{% code lineNumbers="true" %}

```
https://download.cybus.io/${CONNECTWARE_VERSION}/schemas/scf.schema.json
```

{% endcode %}

Replace `${CONNECTWARE_VERSION}` with the version you run, or use `latest`. Versions before Connectware 2.0.0 have no published schema. For more information, see [Schema Files](/2-6-1/reference/schema-files.md).

Give your AI tool the URL when it can fetch files itself. Otherwise download the schema into your project and point the AI tool at the local copy.

#### Documentation

The schema identifies allowed properties, required fields, and allowed values. The documentation explains the properties and provides examples.

When your AI tool supports the Model Context Protocol (MCP), add an MCP server with transport `http` and URL `https://docs.cybus.io/~gitbook/mcp`. How you do that depends on your AI tool:

{% tabs %}
{% tab title="Claude Code" %}
{% code lineNumbers="true" %}

```bash
claude mcp add --transport http cybus-docs https://docs.cybus.io/~gitbook/mcp
```

{% endcode %}
{% endtab %}

{% tab title="GitHub Copilot in VS Code" %}
{% code lineNumbers="true" %}

```bash
code --add-mcp '{"name":"cybus-docs","type":"http","url":"https://docs.cybus.io/~gitbook/mcp"}'
```

{% endcode %}
{% endtab %}
{% endtabs %}

For AI tools without MCP support, use one of these plain-text sources:

| Form                | URL                                   | Use It When                                                            |
| ------------------- | ------------------------------------- | ---------------------------------------------------------------------- |
| Documentation index | `https://docs.cybus.io/llms.txt`      | The AI tool can fetch pages on demand and needs an index.              |
| Full documentation  | `https://docs.cybus.io/llms-full.txt` | The AI tool cannot make HTTP requests and you run the current version. |

{% hint style="warning" %}

## Tell the AI tool which Connectware version you run

`llms.txt` indexes every Connectware version. The current one is served without a version prefix in its URLs, so explicitly tell the AI tool to read the version that you run.

Older versions carry a hyphenated prefix. Append `.md` to a page URL to retrieve raw Markdown:

`https://docs.cybus.io/2-5-0/data-flows/service-commissioning-files.md`

`llms-full.txt` contains only the current version. Do not use it for an older version.
{% endhint %}
{% endstep %}

{% step %}

### Write a Context File

A context file provides the project information that the schema and documentation do not contain. Include your topic hierarchy, which values must be parameters, naming conventions, and a working service commissioning file the AI tool can follow.

Write it to `AGENTS.md` in the root of the repository that holds your service commissioning files. Many AI tools read that file by convention. For an AI tool that expects a different filename, keep the same content under the name it expects. In a chat interface, paste or attach the same content instead.

{% code title="AGENTS.md" lineNumbers="true" %}

```
# Service Commissioning Files for Cybus Connectware

This repository contains service commissioning files for Connectware 2.6.1.

## Sources of Truth

- Schema: https://download.cybus.io/2.6.1/schemas/scf.schema.json
  Take property names, required fields, and allowed values from the schema.
- Documentation: https://docs.cybus.io/ serves the current version, which is the
  one this repository targets. An older version would sit under a hyphenated prefix,
  for example https://docs.cybus.io/2-5-0/.
  Read the page for a resource type or protocol before using it.

## Conventions

- Use parameters for IP addresses, hostnames, and ports. Never hardcode them.
- Reference other resources with !ref. Every !ref must match a key under resources.
- Topics follow factory/<line>/<asset>/<tag-name>.
- File names follow <protocol>-<asset>.scf.yaml.
- Endpoints are read-only unless I ask for write access.

## Example

Use modbus-press-01.scf.yaml in this repository as the reference for
structure and naming.
```

{% endcode %}

Replace the Connectware version, project conventions, and example file name with your own. If you write your first service commissioning file and have no example to point to, leave the example section out.
{% endstep %}

{% step %}

### Describe the Service You Need

State the protocol, device address, data points and their types, polling interval, and topic structure. State whether you need a new service commissioning file or an edit to an existing one.

> Write a service commissioning file for a Siemens S7-1500 at 192.168.1.100. Read DB10.DBD0 (machine speed, real), DB10.DBD4 (cycle count, dword), and DB11.DBD0 (temperature, real) every two seconds. Publish each value under factory/line-3/press-02/.

Attach the exported controller configuration rather than transcribing addresses and types by hand. For an edit, name the existing service commissioning file that the AI tool has to change.
{% endstep %}

{% step %}

### Validate the Output

1. Check the service commissioning file against the schema. Pick whichever of these fits your setup:
   * The [service commissioning file skill](/2-6-1/tools/service-commissioning-file-skill.md) runs the check before it shows you the generated YAML.
   * The [Cybus Connectware Extension for VS Code](/2-6-1/tools/cybus-connectware-extension-vs-code.md) validates as you edit and lists errors in the **Problems** view. It handles `!ref` and flags references that point to no resource.
   * Any JSON Schema draft-07 validator works. Convert the YAML to JSON first, and replace the `!ref`, `!sub`, and `!merge` tags and the `${...}` placeholders with their values. The schema describes a resolved service commissioning file, so a validator reports errors on tags and placeholders that Connectware itself accepts.
2. Review the generated YAML against your context file. Confirm that parameters contain addresses, hostnames, ports, and other environment-specific values; topics follow your convention; and resource references match resource keys.
3. Install the service commissioning file on a development Connectware instance. Connectware rejects what it cannot process, so this is the check that covers what the schema does not. Confirm that the connection starts and data arrives on the expected topics before you promote it to production. See [Separate Development and Production Environments](https://docs.cybus.io/2-6-1/guides/operations/pages/sS1fbJKUmCn3jj9FOwIi#id-6.-separate-development-and-production-environments).

{% hint style="info" %}

## Custom connectors fail schema validation

The schema lists only the protocols shipped with a Connectware version, so a service commissioning file that uses a [custom connector](/2-6-1/connectors/custom-connectors.md) protocol is reported as invalid even though Connectware installs it. Read the validator's error paths and disregard the ones that point at the custom connector resource. The remaining errors still apply.
{% endhint %}
{% endstep %}
{% endstepper %}

## Result

Your AI tool now turns a description of a machine into a service commissioning file that matches the version you run and follows your project conventions. The work that remains is judgment. A schema check confirms the structure of the YAML, not that the connection reaches your machine or publishes the values you expect, so every draft still goes through a development instance before production.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cybus.io/2-6-1/guides/operations/writing-service-commissioning-files-with-ai-assistance.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.