Build spec · Free · No call required
The Agent Build Spec Pack
Most agent specifications describe behaviour and skip contracts, which is why they produce something that demonstrates well and cannot be left running. This is the shape that survives production: four skills with explicit inputs and outputs, the record every agent reads from, and tests that can actually fail.
Published August 23, 2026· 11-minute read · Written so you can build it without hiring anyone
The four-skill decomposition, on a real agent
Worked here on a review-response agent, because it is the one most operators try first and the one where the failure modes are easiest to recognise. The shape holds for any agent that reads a stream, decides something, produces output and reports back.
Skill 1 — Ingest
- Reads
- The source systems, each named explicitly with an owner. For a review-response agent: the review platforms, the location record, and the brand voice spec.
- Writes
- A normalised event with a stable identity — platform, location id, author, rating, body, timestamp, and a hash that makes the same review arriving twice idempotent.
Never emits an event it cannot attribute to exactly one location in the canonical record. An unattributable review goes to an exception queue rather than to a default location, because a default is how one store silently accumulates another store’s reputation.
Skill 2 — Decide
- Reads
- The normalised event, the location’s autonomy profile, and the policy set that applies to that jurisdiction and vertical.
- Writes
- A decision record: respond automatically, respond after review, escalate, or take no action — plus the rule that produced it and a confidence value.
Every decision is explainable by naming the rule that fired. A decision that cannot name its rule is a defect, not a judgement call, because nothing downstream can audit it and nobody can tune it.
Skill 3 — Act
- Reads
- The decision record, the brand voice spec, and the platform’s own constraints on length, links and formatting.
- Writes
- A draft plus the metadata the gate needs: the voice score, the claims detected, and the platform the draft is shaped for.
Produces a draft and never publishes one. Publication is a separate, gated step, so the difference between an agent that is helping and an agent that has gone wrong is always one approval away rather than already in public.
Skill 4 — Emit
- Reads
- The published or rejected outcome, and the original event identity.
- Writes
- A change event other agents subscribe to, and an audit row that records what happened, which rule decided it, who approved it, and when.
Emits on rejection as well as publication. Systems that only emit successes cannot be measured, because the interesting number is the rejection rate and the reasons behind it.
The data-fabric contract
The part that decides whether the second agent takes a week or a quarter. Three questions, answered in writing before anyone opens an editor.
- What it reads
- Name the canonical record for every input and the system that owns it. If two systems can answer the same question, one of them is the source and the other is a cache — write down which, because that decision gets made by accident otherwise.
- What it writes back
- An agent that only consumes is a reporting tool. The write-back is what makes the next agent cheaper to build: normalised events, decision records with the rule that fired, and outcomes with an identity other agents can join on.
- How it stays consistent
- Idempotency on a stable event identity, so replay is safe. Optimistic concurrency on the canonical record, so two agents writing the same location do not silently overwrite one another. And a schema version on every emitted event, so a consumer built today does not break when the producer changes next quarter.
The acceptance tests
Every one of these can fail, which is the only property that matters. Run them before the agent touches a live account, and again on every model or prompt change.
- 1Replay the last 30 days of events. Output must be byte-identical on the second run — if it is not, something in the pipeline is reading wall-clock time or unsorted input.
- 2Feed a review that matches no location. It must land in the exception queue, and no default location may be assigned.
- 3Set one location’s autonomy profile to review-required. Every draft for that location must stop at the gate, including the ones the model scores as high confidence.
- 4Submit a draft containing a claim the policy set forbids. It must be blocked and the specific rule named in the audit row.
- 5Kill the process mid-run. On restart, no event is processed twice and none is lost.
- 6Revoke a platform credential. The agent must degrade to queueing rather than failing silently or dropping the work.
- 7Ask the audit trail who approved the last twenty published responses. If that takes more than one query, the audit design is not finished.
The first is the one most builds fail. Non-determinism usually traces to unsorted input or a timestamp read at execution rather than carried on the event, and both are cheap to fix early and expensive to find later.
Four ways a spec fails
- A spec that names models rather than contracts. The model is the most replaceable part of the system and the one most likely to change before you ship.
- Acceptance tests written as "responses should be high quality". If it cannot fail, it is not a test — it is a hope with a checkbox.
- No exception path. Every real deployment is mostly exceptions, and a spec without an exception queue is a spec for the demo.
- Autonomy treated as one global setting. It varies per location, per skill and per risk class, and a single switch means the most cautious location sets the pace for everyone.
If you would rather not build it yourself
The Setup Sprint builds this shape inside your operation and hands it over with the spec, the tests and the audit design intact. You own every artifact whether or not anything follows.
Ready to talk instead? Book the 30-minute consultation. Thirty minutes, no deck.