> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duvo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Let a Skill Do the Math

> When results must be exact and auditable, package the calculation as a script inside a custom Skill. The Agent orchestrates; the engine computes.

Agents are excellent at reading messy documents, making judgment calls, and navigating systems. They are the wrong tool for performing the same financial calculation ten thousand times. When each output must be exact — and may be challenged line by line — put the calculation in a script inside a [custom Skill](/user-guide/skills/creating-custom-skills), and write the AOP so the Agent orchestrates the work instead of computing it.

One team that audits freight invoices at scale describes their audit Skill this way: *"it does all the math; you only orchestrate."* That sentence is the whole pattern.

## When This Pattern Applies

Reach for it when the output is **contested by nature** — someone downstream will check it, dispute it, or pay money based on it:

* Rate and invoice audits: is the billed amount what the contract says?
* Reconciliation: do these two systems agree, and by exactly how much do they differ?
* Compliance checks with hard thresholds: pass/fail per rule, with the margin.
* Fees, surcharges, and discounts derived from published tables.

For a handful of items, an Agent computing in prose is usually right. Across thousands of Cases, "usually right" compounds into results you cannot defend — and worse, into results that differ between two Runs over the same input.

## The Pattern

A custom Skill is a package of files: instructions, plus anything they reference — including a script and the reference data it needs.

```mermaid theme={"dark"}
flowchart LR
    A[Agent claims one Case] --> B[Gathers the inputs<br/>from the Case data]
    B --> C[Skill script computes<br/>expected values and verdict]
    C --> D[Agent writes results to the Case<br/>and acts on the verdict]
```

The division of labor:

* **The Agent** (via the AOP): claims the Case, assembles the inputs, runs the engine, records the results, and handles what happens next — escalate, complete, or hand over. All the judgment stays here.
* **The Skill script**: takes the inputs, looks up the contracted rates or rules from its reference files, computes the expected values, and returns a structured result — expected amount per line, the difference, and a verdict.

The freight-audit version: the Agent feeds in one shipment's identifiers and billed charges; the engine looks up the contracted lane rate, applies the fuel surcharge for that week, prices each accessorial charge, and returns the expected total with a per-line breakdown and an overcharged / clean / needs-review verdict. The Agent never adds two numbers itself.

<Tip>
  Put this sentence in the AOP, next to the step that uses the engine: "Run the engine for every Case. Never compute the charges yourself." Without it, the model will helpfully do arithmetic the day the script hits an edge case.
</Tip>

## Why Not the Alternatives

| Alternative                                         | What goes wrong                                                                               |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| The AOP describes the calculation in prose          | The model performs it slightly differently across Runs; results can't be reproduced or diffed |
| The Agent writes throwaway code during each Run     | Every Run reimplements the logic — unversioned, untested, and drifting                        |
| Each Agent embeds its own copy of the logic         | Three Agents, three answers; a rate change means three edits                                  |
| The calculation already lives in an external system | Then use that Connection — this pattern is for logic that has no system of record             |

## How to Build It

<Steps>
  <Step title="Write the script first" icon="flask-conical">
    Develop and test the calculation like any code: feed it known inputs, assert the outputs. If a domain expert can hand you five worked examples, those are your test cases.
  </Step>

  <Step title="Package it as a custom Skill" icon="package">
    Follow [Creating Custom Skills](/user-guide/skills/creating-custom-skills): instructions that explain when and how to run the script, and its reference data (rate tables, rule lists) as files in the package.
  </Step>

  <Step title="Write the description as a trigger" icon="zap">
    The Agent decides to load a Skill from its description, so write it like a "use when" sentence: "Use this skill whenever auditing a freight invoice — to compute the exact expected charges for a shipment against the contracted rate cards." A vague description means the Skill sits unused.
  </Step>

  <Step title="Attach it and slim the AOP" icon="link">
    Attach the Skill to each Agent that needs it. The AOP keeps the orchestration steps and the "never compute yourself" rule — and loses every formula.
  </Step>
</Steps>

## What You Get

* **Determinism.** Same Case in, same verdict out — today, next month, and on the Run where someone disputes the result.
* **Testability.** The engine is a script; you can prove it correct against known examples before any Agent touches it, and re-run those examples after every change.
* **A reviewable audit trail.** The structured output (expected value per line, difference, verdict) is written to the Case, so a human can check the reasoning without re-deriving it.

## When Not To

Keep the model in charge where judgment is the work: categorizing a complaint, drafting a reply in the customer's language, deciding whether a mismatch is worth escalating, summarizing findings. A script that tries to encode taste or tone fails in stranger ways than a model ever will. The dividing line: **if two careful humans would get the same answer with a calculator, script it. If they might reasonably disagree, it's the Agent's call** — guided by the AOP.

## Related

<CardGroup cols={2}>
  <Card title="Creating Custom Skills" icon="package" href="/user-guide/skills/creating-custom-skills">
    How to package instructions, scripts, and reference files into a Skill.
  </Card>

  <Card title="Skills" icon="book-open" href="/user-guide/skills/skills-overview">
    How Skills attach to Agents and load during Runs.
  </Card>

  <Card title="Where Knowledge Belongs" icon="layers" href="/best-practices/where-knowledge-lives">
    AOP, Skills, Files, or Memory — route each piece of knowledge to the right layer.
  </Card>

  <Card title="Queue" icon="inbox" href="/user-guide/assignment-features/case-queue">
    The per-Case processing model these engines plug into.
  </Card>
</CardGroup>