# Modbus Skills

PUBLIC REPOSITORY · VERSION 0.2.0 · 20 SKILLS · 11 WORKFLOWS · READ-ONLY

Modbus skills for coding agents. Use one skill for one result, or follow a workflow from a register map to a field test.

## First 10 minutes

1. Add the project once with the install steps below.
2. Ask for a user map from your local manual or spreadsheet, and name the measurements you need.
3. Open the readable map, JSON, and CSV that the skill writes.

You can say this in plain language:

```text
Use this manual to make a user map for temperatures, operating status, alarms, and power. Give me a readable map plus JSON and CSV.
```

- [When to use Modbus Skills](https://studioxvii.github.io/modbus-skills/when-to-use.html)
- [Worked compile example](https://studioxvii.github.io/modbus-skills/examples/compile-user-map.html)

## Install

Version [0.2.0](https://github.com/studioxvii/modbus-skills/releases/tag/v0.2.0). Licensed under [Apache-2.0](https://github.com/studioxvii/modbus-skills/blob/main/LICENSE).

### Codex

Clone the public repository, add its local marketplace, and install the canonical plugin source.

```bash
git clone https://github.com/studioxvii/modbus-skills.git
cd modbus-skills
codex plugin marketplace add "$PWD"
codex plugin add modbus-skills@modbus-skills
```

### Claude Code

Build and load the local Claude Code package. This loads the plugin for the current session.

```bash
git clone https://github.com/studioxvii/modbus-skills.git
cd modbus-skills
python3 scripts/build_plugin_variants.py
claude --plugin-dir "$PWD/dist/plugins/claude"
```

Use a skill as `/modbus-skills:skill-name`.

### Cursor

After Modbus Skills is published in Cursor Marketplace, type this command in Cursor:

```text
/add-plugin modbus-skills
```

### Build all client packages

```bash
python3 scripts/build_plugin_variants.py
python3 scripts/validate_plugin_variants.py --output dist/plugins
```

- **Codex:** canonical source; $skill-name.
- **Claude Code:** dist/plugins/claude; /modbus-skills:skill-name.
- **Cursor:** Cursor Marketplace; /add-plugin modbus-skills.
- **Agent Plugins 1.0:** dist/plugins/agent-plugin; client installation policy.

Installation adds the plugin files only. It does not install Python, PyModbus, Node-RED, Modpoll (BETA), Witte Modbus Poll (BETA), or ModScan (BETA).

- Source: https://github.com/studioxvii/modbus-skills
- Release: https://github.com/studioxvii/modbus-skills/releases/tag/v0.2.0
- Documentation: https://studioxvii.github.io/modbus-skills/
- When to use: https://studioxvii.github.io/modbus-skills/when-to-use.html
- Worked example: https://studioxvii.github.io/modbus-skills/examples/compile-user-map.html

## Which review skill should I use?

- **$parse-map:** Give it a csv, json, xml, xlsx, or text register file. You get a json register list. Use it when you need to put a register file into a consistent list.
- **$review-map:** Give it a pdf or structured register file. You get a checked draft and one list of questions. Use it when you want a complete source-map review in one request.
- **$check-map:** Give it a standard modbus map. You get validation.json. Use it when you need to find duplicate, overlapping, invalid, or unsafe read definitions.
- **$review-evidence:** Give it a map, its source, and check results. You get report.json with grouped questions. Use it when you need to know which details still require your answer.
- **$apply-review:** Give it a map and your approved answers. You get a new reviewed map. Use it when you are ready to add your answers and keep the original map unchanged.

## Choose the result you need

### 01 — Start here

Compile a complete user map from an OEM source, or ask which focused skill to use.

- **[$compile-user-map](/skills/modbus/compile-user-map.md)** — Turn an OEM register map and a list of the values you need into an organized user map, JSON, CSV, and optional field-tool files.
- **[$modbus-help](/skills/modbus/modbus-help.md)** — Describe what you need and what file you have. For an OEM manual or broad setup, start with $compile-user-map. For a named stage, you get that skill.
- **[$review-map](/skills/modbus/review-map.md)** — Review a PDF or structured register file in one run and return a checked draft with a short list of open questions.

### 02 — Review register maps

Turn a PDF or register file into a checked draft and a short exception list. Use extraction or parsing only when you need that stage by itself.

- **[$parse-map](/skills/modbus/parse-map.md)** — Read a CSV, JSON, XML, XLSX, or text register file and create a structured list of registers.
- **[$extract-pdf-map](/skills/modbus/extract-pdf-map.md)** — Find and extract register tables from a PDF manual, or limit the work to a page range you already know.
- **[$normalize-map](/skills/modbus/normalize-map.md)** — Convert a parsed register list to the plugin’s standard Modbus map format.
- **[$check-map](/skills/modbus/check-map.md)** — Check a normalized map for duplicate points, overlapping registers, missing packed-bit rules, invalid data widths, and unsafe read definitions.
- **[$review-evidence](/skills/modbus/review-evidence.md)** — Compare a register map with its source and show only the missing or contradictory details that need your answer.
- **[$apply-review](/skills/modbus/apply-review.md)** — Add your approved map-review answers to a new copy of the register map.
- **[$remap-addresses](/skills/modbus/remap-addresses.md)** — Convert a complete map between zero-based offsets and 40001-style register numbers, then return the converted map when it is safe.
- **[$compare-maps](/skills/modbus/compare-maps.md)** — Compare two map versions and show which points were added, removed, moved, changed, or left unresolved.

### 03 — Plan and run one read

Plan one safe read and use its raw result to determine byte order.

- **[$capture-sample](/skills/modbus/capture-sample.md)** — Create a manual, read-only probe pack for one defined register range and stop before the physical read.
- **[$check-byte-order](/skills/modbus/check-byte-order.md)** — Check which byte and word orders apply to one raw sample, then calculate every supported layout.
- **[$plan-reads](/skills/modbus/plan-reads.md)** — Group the points in a checked map into small, read-only Modbus requests for function codes 01–04 before building Node-RED, Modpoll (BETA), or ModScan (BETA) files.

### 04 — Create field-tool files

Create files for the Node-RED, Modpoll, or ModScan tool that you use.

- **[$build-node-red](/skills/modbus/build-node-red.md)** — Create a disabled Node-RED flow for one manual probe or a five-second read-only live view.
- **[$build-modpoll](/skills/modbus/build-modpoll.md)** — Create BETA read-only files for the selected Modpoll command-line or Witte Modbus Poll desktop product.
- **[$build-modscan](/skills/modbus/build-modscan.md)** — Create BETA documented setup and CSV files for a read-only ModScan test.
- **[$build-tool-pack](/skills/modbus/build-tool-pack.md)** — Create any selected combination of Node-RED, Modpoll (BETA), and ModScan (BETA) files from one map and read plan.
- **[$build-custom-export](/skills/modbus/build-custom-export.md)** — Create a repeatable text or CSV export that follows a documented example.

### 05 — Analyze read data

Find communication and signal problems in live or saved read data.

- **[$analyze-capture](/skills/modbus/analyze-capture.md)** — Check a saved set of Modbus samples for communication, timing, stale-value, range, rate, and byte-order problems.

## 11 complete Modbus tasks

A workflow selects the skills and order for a complete task. It pauses before a device read or any choice that you must make.

### Compile an OEM map into user outputs

Produce an organized user map and the requested offline outputs in one resumable run.

1. $compile-user-map: compile the requested user outputs
2. answer one grouped source question when required

**Stops when:** Stops only when one grouped source decision, device binding, or separate physical evidence is required.

### Review a raw source map end to end

Review a PDF or structured register file and return a checked draft with a short exception list.

1. $review-map: review the complete source map
2. answer all open questions together
3. $apply-review: add the approved answers

**Stops when:** A clean review continues without approval. Otherwise, answer every independent exception group together.

### Extract PDF register evidence

Extract traceable rows and grouped exceptions from a PDF without performing a complete source-map review.

1. $extract-pdf-map: extract the register evidence
2. $review-evidence: group the extraction exceptions
3. confirm the complete bounded source once

**Stops when:** Stops for an unreadable PDF, incomplete source coverage, or grouped extraction exceptions. It never asks page by page.

### Confirm byte order from one sample

Evaluate all supported layouts from one saved sample, record your confirmation, and update the map.

1. $check-byte-order: calculate each supported layout
2. confirm the matching layout
3. $apply-review: add the confirmed layout

**Stops when:** Stops when raw words or sample identity are missing, or when the question concerns coil or packed-bit numbering.

### Determine byte order from a one-read probe

Build one bounded probe, wait for one physical read, then run the byte-order confirmation workflow.

1. $capture-sample: build one bounded probe pack
2. run one device read
3. confirm-byte-order: confirm byte order from the saved sample

**Stops when:** Stops at the live-read gate. The operator must save the raw words before byte-order confirmation begins.

### Remap address notation

Convert a complete map between protocol offsets and 40001-style register numbers, then check the result.

1. $remap-addresses: convert the address notation
2. $check-map: check the converted map

**Stops when:** Stops when the source convention is unknown, information would be lost, or the conversion creates a duplicate address.

### Build a declarative custom export

Create a documented text or CSV export from a reviewed map without running code from the example file.

1. $check-map: check the map
2. $build-custom-export: build the custom export

**Stops when:** Stops when the example format is unclear, the map has an error, or the requested file is an undocumented binary format.

### Probe, resolve byte order, and finalize a tool pack

Use a selected tool to collect one sample, confirm byte order, then rebuild the final tool files.

1. $plan-reads: plan the read
2. $build-tool-pack: build the probe
3. run one device read
4. confirm-byte-order: confirm byte order from the saved sample
5. $plan-reads: rebuild the read plan
6. $build-tool-pack: build the final tool files

**Stops when:** Review the sample and layout before you build the final tool files.

### Build a multi-target tool pack

Create Node-RED, Modpoll (BETA), and ModScan (BETA) files from one validated map and read plan.

1. $check-map: check the map
2. $plan-reads: plan the reads
3. $build-tool-pack: build the selected files

**Stops when:** The validated map and its hash-bound read plan must pass all checks.

### Analyze bounded read data

Find communication and signal problems without a control command.

1. $analyze-capture: analyze the data
2. review the findings

**Stops when:** Review the limits, the sample period, and other possible causes.

### Compare map revisions

See what changed between devices, documents, or firmware versions.

1. review-source-map: review the first source map
2. review-source-map: review the second source map
3. $compare-maps: compare the maps
4. review the changes

**Stops when:** Review moved, added, removed, and changed points.