studio-seventeen
WORKSHOP--:--
~/workshop/skills/modbus/README.md

# Modbus Skills · by Studio Seventeen

Modbus skills for coding agents.

Use one skill for one result, or follow a complete workflow from a register map to a field test.

Skills
20
Workflows
11
License
Apache-2.0

PUBLIC RELEASEv0.2.0 ↗GitHub repository ↗project docs ↗when to use ↗worked example ↗

PRIMARY PATH

Turn an OEM map into the outputs you need.

$compile-user-map takes an OEM PDF or register file plus the values you need, such as temperatures, alarms, status, or power. It returns an organized user map, JSON, CSV, and optional field-tool files.

open $compile-user-map →not sure? $modbus-help ↓
11 WORKFLOWSFollow a complete Modbus taskSee the ordered skills, one-device-read steps, and approval points ↓

INSTALL · VERSION 0.2.0 · Apache-2.0

Choose your coding agent

Open your client below. Copy the command, then follow the short note for that client.

Codex

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

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 the Claude package and load it for the current session. Invoke a skill as /modbus-skills:skill-name.

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"
Cursor

After marketplace publication, type this command in Cursor.

/add-plugin modbus-skills
Agent Plugins 1.0

Build the portable packages, then use dist/plugins/agent-plugin with your client’s installation process.

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

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

01 · SKILLS

Choose the result you need

Each skill starts with a clear engineering task and returns one useful result.

20 skills

FIVE REVIEW JOBS

Choose the review skill by the result you need

SKILLGIVE ITYOU GETUSE IT WHEN
$parse-mapA CSV, JSON, XML, XLSX, or text register fileA JSON register listYou need to put a register file into a consistent list.$review-mapA PDF or structured register fileA checked draft and one list of questionsYou want a complete source-map review in one request.$check-mapA standard Modbus mapvalidation.jsonYou need to find duplicate, overlapping, invalid, or unsafe read definitions.$review-evidenceA map, its source, and check resultsreport.json with grouped questionsYou need to know which details still require your answer.$apply-reviewA map and your approved answersA new reviewed mapYou are ready to add your answers and keep the original map unchanged.
01

Start here

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

Start with $compile-user-map

$compile-user-mapCompile User Map

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.

read skill →
$modbus-helpModbus Help

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.

read skill →
$review-mapReview Map

Review a PDF or structured register file in one run and return a checked draft with a short list of open questions.

read skill →
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.

Start with $review-map

$parse-mapParse Map

Read a CSV, JSON, XML, XLSX, or text register file and create a structured list of registers.

read skill →
$extract-pdf-mapExtract PDF Map

Find and extract register tables from a PDF manual, or limit the work to a page range you already know.

read skill →
$normalize-mapNormalize Map

Convert a parsed register list to the plugin’s standard Modbus map format.

read skill →
$check-mapCheck Map

Check a normalized map for duplicate points, overlapping registers, missing packed-bit rules, invalid data widths, and unsafe read definitions.

read skill →
$review-evidenceReview Evidence

Compare a register map with its source and show only the missing or contradictory details that need your answer.

read skill →
$apply-reviewApply Review

Add your approved map-review answers to a new copy of the register map.

read skill →
$remap-addressesRemap Addresses

Convert a complete map between zero-based offsets and 40001-style register numbers, then return the converted map when it is safe.

read skill →
$compare-mapsCompare Maps

Compare two map versions and show which points were added, removed, moved, changed, or left unresolved.

read skill →
03

Plan and run one read

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

Start with $capture-sample

$capture-sampleCapture Sample

Create a manual, read-only probe pack for one defined register range and stop before the physical read.

read skill →
$check-byte-orderCheck Byte Order

Check which byte and word orders apply to one raw sample, then calculate every supported layout.

read skill →
$plan-readsPlan Reads

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.

read skill →
04

Create field-tool files

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

Start with $build-tool-pack

$build-node-redBuild Node-RED

Create a disabled Node-RED flow for one manual probe or a five-second read-only live view.

read skill →
$build-modpollBuild Modpoll (BETA)

Create BETA read-only files for the selected Modpoll command-line or Witte Modbus Poll desktop product.

read skill →
$build-modscanBuild ModScan (BETA)

Create BETA documented setup and CSV files for a read-only ModScan test.

read skill →
$build-tool-packBuild Tool Pack

Create any selected combination of Node-RED, Modpoll (BETA), and ModScan (BETA) files from one map and read plan.

read skill →
$build-custom-exportBuild Custom Export

Create a repeatable text or CSV export that follows a documented example.

read skill →
05

Analyze read data

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

Start with $analyze-capture

$analyze-captureAnalyze Capture

Check a saved set of Modbus samples for communication, timing, stale-value, range, rate, and byte-order problems.

read skill →

02 · FIELD TOOLS

Create files for the field tool you use

Select one tool or create all three outputs. Each output uses the same validated map and hash-bound read plan.

VERIFIED · FLOW JSON

Node-RED

Import a disabled flow. The public release records native acceptance for the one-time probe and final five-second live view.

open build skill →BETA · CLI + CSV

Modpoll

Build read-only files for gavinying/modpoll or Witte Modbus Poll. Native application verification has not been run.

open build skill →BETA · READ PLAN

ModScan

Build a read-only setup and CSV plan for ModScan32 or ModScan64. Native application verification has not been run.

open build skill →

03 · WORKFLOWS

Eleven complete Modbus tasks

A skill does one job. A workflow runs one or more skills and pauses for your approval or one device read. OEM work uses $compile-user-map; it does not expand into a field-tool specialist chain.

11 workflows
AUTOMATIC SKILLONE DEVICE READYOUR APPROVAL
01

Compile an OEM map into user outputs

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

USES 1 SKILL

$compile-user-map

PAUSES

your approval

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

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

02

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.

USES 2 SKILLS

$review-map$apply-review

PAUSES

your approval

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

Pause rule: A clean review continues without approval. Otherwise, answer every independent exception group together.

03

Extract PDF register evidence

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

USES 2 SKILLS

$extract-pdf-map$review-evidence

PAUSES

your approval

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

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

04

Confirm byte order from one sample

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

USES 2 SKILLS

$check-byte-order$apply-review

PAUSES

your approval

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

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

05

Determine byte order from a one-read probe

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

USES 1 SKILL

$capture-sample

PAUSES

confirm-byte-order workflow · one device read

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

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

06

Remap address notation

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

USES 2 SKILLS

$remap-addresses$check-map

PAUSES

no required pause

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

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

07

Build a declarative custom export

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

USES 2 SKILLS

$check-map$build-custom-export

PAUSES

no required pause

  1. 01$check-map check the map
  2. 02$build-custom-export build the custom export

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

08

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.

USES 2 SKILLS

$plan-reads ×2$build-tool-pack ×2

PAUSES

confirm-byte-order workflow · one device read

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

Pause rule: Review the sample and layout before you build the final tool files.

09

Build a multi-target tool pack

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

USES 3 SKILLS

$check-map$plan-reads$build-tool-pack

PAUSES

no required pause

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

Pause rule: The validated map and its hash-bound read plan must pass all checks.

10

Analyze bounded read data

Find communication and signal problems without a control command.

USES 1 SKILL

$analyze-capture

PAUSES

your approval

  1. 01$analyze-capture analyze the data
  2. 02review the findings

Pause rule: Review the limits, the sample period, and other possible causes.

11

Compare map revisions

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

USES 1 SKILL

$compare-maps

PAUSES

2 review-source-map runs · your approval

  1. 01review-source-map review the first source map
  2. 02review-source-map review the second source map
  3. 03$compare-maps compare the maps
  4. 04review the changes

Pause rule: Review moved, added, removed, and changed points.

FOR AGENTScollection markdownskills.json ↗workflows.json ↗