# The /logisticshub Skill

> Cross-check a shipment's invoice, packing list, CMR and contract. Every discrepancy comes back with the exact quote and page.

- Category: Trade documents
- Status: Stable
- Version: 1.0.0
- License: MIT
- Updated: 17 Nov 2026
- Source: https://github.com/tsirbiladze/logisticshub
- Full SKILL.md: https://github.com/tsirbiladze/logisticshub/blob/v1.0.0/skills/logisticshub/SKILL.md
- Page: https://tsirbiladze.com/skills/logisticshub
- Georgian version: https://tsirbiladze.com/ka/skills/logisticshub.md

## Install

### Agent skill

```bash
npx skills@latest add tsirbiladze/logisticshub
```

Works with Claude Code, Codex, Cursor, Gemini CLI and other agents. Then ask: “Check the documents in ./docs for discrepancies.”

### Claude Code

```text
/plugin marketplace add tsirbiladze/logisticshub
```

```text
/plugin install logisticshub@logisticshub
```

Run both in Claude Code.

### claude.ai

Download the zip: https://github.com/tsirbiladze/logisticshub/releases/download/v1.0.0/logisticshub-skill.zip

Upload it under Settings → Capabilities → Skills. claude.ai runs the Python checker, so you get reports but no marked PDFs.

### CLI

```bash
npx logisticshub check ./docs
```

Reads the documents with a model you choose, using your own API key.

### MCP

```json
{
  "mcpServers": {
    "logisticshub": {
      "command": "npx",
      "args": [
        "-y",
        "logisticshub",
        "mcp"
      ]
    }
  }
}
```

Add it to your MCP client’s config. The client gets two tools: the extraction guide and the check.

## What it does

`logisticshub` compares the documents of one shipment (commercial invoice, packing list, CMR and sales contract) with each other, and checks each one on its own. It reports every discrepancy its rules find, with the verbatim quote and the page it came from.

It never corrects a document and never guesses. Your agent only reads: from each PDF or page image it writes down every fact exactly as printed, with its quote and page. Everything after that is code. The checker first makes sure that each number and date is what its own quote says, and that each quote is printed on the page it cites. Then come exact decimal arithmetic, a parser that turns an amount written in words (English, Georgian, Russian, Turkish) into a number, and 16 fixed rules. Run it twice on the same extraction and you get the same report.

The output is a report in Markdown, HTML and JSON, in English, Georgian, Russian or Turkish. Each finding names the document, the page and the field, quotes the printed text, and ends with a line that says what to verify. Each PDF that has a finding also comes back as a copy with the findings boxed and numbered.

![A marked invoice: line 2 does not add up, and the subtotal does not match the lines](https://tsirbiladze.com/skills/logisticshub/marked-invoice.png)

## When to reach for it

Ask your agent in plain words: "check the documents in this folder", "do the invoice and the CMR agree?". The skill is for the export or customs documents of one shipment. One invoice can be checked on its own too: its line totals, its sums and its amount in words. It is not for paying an invoice or booking it.

| Situation | What it finds |
|---|---|
| Before a shipment leaves | Quantities, packages and weights that differ between the invoice, the packing list and the CMR |
| Before the documents go to a bank or to the buyer | An amount in words that does not match the figures, line totals and subtotals that do not add up |
| Before customs | A CMR that lacks required particulars, a sea-only Incoterms rule on a road shipment, CIF or CIP with neither an insurance policy nor an insurance amount |
| Reviewing a supplier's set | Wrong or missing references between the documents, dates in the wrong order, a seller or buyer named differently |

## What it checks

- **Amounts.** The amount in words equals the amount in figures, currency included. Quantity × price equals each line total. The line totals add up to the subtotal, and the subtotal with discount, freight, insurance, other charges and tax gives the total. Invoice and contract are in one currency.
- **Quantities and weights.** Packing-list and CMR lines add up to their totals. Invoice and packing list give the same quantity per item, and invoice, packing list and CMR the same number of packages. Gross weight is not below net weight, and the weights are the same on every document.
- **References and parties.** The packing list cites the invoice's number and date, the invoice cites the contract's, and the CMR lists both among its attached documents. Contract date ≤ invoice date ≤ taking over of the goods. The same seller, buyer and consignee on every document. An invoice, a packing list and a CMR in the set.
- **Terms and the CMR.** The same Incoterms 2020 rule on invoice and contract, no sea-only rule on a road shipment, insurance under CIF or CIP, and the particulars the CMR Convention requires in Art. 6(1)(a)–(k).

Each rule is stated exactly, with every finding, its severity and its tolerance, in the [rules reference](https://github.com/tsirbiladze/logisticshub/blob/v1.0.0/skills/logisticshub/references/rules.md).

## It's working if

- Every finding cites a quote you can find, word for word, on the page it names.
- Documents that agree give "Errors: 0 · Warnings: 0", not a list of nitpicks.
- Running it again on the same extraction gives the same report.
- Where something cannot be read for certain (an amount in words with a typo, for example), you get a warning that says so, not a guess.
- A quote or a page number your agent got wrong does not pass unseen: every quote the checker does not find on its PDF page is listed after the report.

## Limits

How it reads:

- One run checks one shipment. The documents of several shipments are checked one run at a time.
- Scans: a page without a text layer is read from its picture. Nothing on it can be marked and no quote on it can be looked up; the notes say so.
- Page images (JPG, PNG) are read, never marked, and their quotes are not looked up.
- An amount in words is read in English, Georgian, Russian and Turkish. In any other language you get a warning that it could not be read.
- The Python checker writes the same reports but reads no PDFs: no marked copies, and no quote is looked up.

Not checked:

- **Incoterms place and edition**: recorded, not compared. Whether the named place suits the rule is not judged.
- **Contract value and goods**: the invoice total against the contract value, unit prices against the contract, the contract's goods against the invoice lines.
- **Volumes across documents**: a packing list's volumes are added up to its own total, not compared with the CMR.
- **Weights per line across documents**, and net weight on a CMR.
- **Origin and HS codes**: recorded only. No tariff classification, no duty or tax calculation, no customs declaration.
- **Addresses, countries, registration and tax numbers, bank details, signatures and stamps**. Only the parties' names are compared, and not across scripts.
- **Tax**: the rate, whether tax is due, and tax included in the prices. A printed tax amount is only added into the invoice total.
- **A discount printed only as a rate**: the invoice total is then left unchecked.
- **Units**: nothing is converted. Quantities in different units are not compared, and neither are package counts of different packing methods.
- **Other dates**: delivery and payment terms, validity, the packing list's date.
- **Further documents of a type**: a second invoice, packing list, CMR or contract is checked on its own, but the rules that compare documents (QTY-01, WGT-02, REF-01, DATE-01, PTY-01) use the first of each type. The report says when there are more.
- **Other document types**: a bill of lading, certificate of origin, insurance policy or specification is not read. Only its title counts, for the insurance check.
- **The documents against reality**: the goods actually loaded, whether a document is genuine, and whether the extraction left out something the document prints.

## Where it fits

There are three ways to run it, all built on the same checker:

- **The skill** runs inside your agent (Claude Code, Codex, Cursor, claude.ai and others). Your agent reads the documents with its own model, and the check runs where the agent runs: on your machine, or on claude.ai, where the skill's instructions call for its Python checker.
- **The CLI** (`logisticshub` on npm) reads the documents with a model you choose, using your own API key, one document per file. It also checks an extraction you already have, without a model. Use it in scripts or without an agent.
- **The MCP server** (`logisticshub mcp`) gives any MCP client two tools: the extraction guide and the check.

The skill's checker and the CLI end with exit code 0 when the documents were checked, with or without findings; 1 when the check is not complete and the reports say why; 2 when nothing was checked.

Logisticshub has no server, so nothing is sent to it. With the CLI, the documents go to the model provider you choose. All companies, people and numbers in the demo documents are fictional.

## Changelog

### 1.0.0 (17 Nov 2026)

First release.

- 16 deterministic rules across the commercial invoice, packing list, CMR and sales contract of one shipment: amounts and totals, the amount in words (English, Georgian, Russian, Turkish), quantities, packages, weights, references, dates, parties, Incoterms 2020 and CMR Art. 6(1). One invoice can be checked on its own: its line totals, its sums and its amount in words.
- The checker checks the extraction before it trusts it. A value that is not what its own quote says is listed as an extraction issue and kept out of every rule, so a misread number, date or currency does not turn into findings.
- Every finding cites the verbatim quote, the page and the field, and ends with a line that says what to verify. Reports in Markdown, HTML and JSON, in English, Georgian, Russian or Turkish.
- Each PDF with a finding comes back as a copy with the evidence boxed and numbered. Every quote is looked up on its PDF page, and what is not found is listed under `Notes:` with the reason. Where a copy cannot be tied to a field, every copy is boxed and a note says so.
- Agent skill with a single-file Node.js checker, and a Python port for claude.ai that gives byte-identical reports and does not read the PDFs.
- `logisticshub` npm package: a CLI that reads the documents with a model you choose (Anthropic, OpenAI, OpenRouter) and your own API key, and an MCP server with two tools, the extraction guide and the check.
- 29 demo sets of synthetic documents in four languages, each with the findings it must give.
