Back to Articles Hero: Claude's commerce skills on the left, six numbered lessons carried across the middle, and what each means for an ArcKit user on the right.
3 September 2026

Anthropic published a worked example of two Claude agents for online retail: one helps a shopper, one helps the shop. ArcKit helps architects produce documents an organisation can sign off. On the surface they have nothing in common. Underneath, both put a model in front of text it should not trust and ask it to produce something people will rely on. Reading the retail example changed six things in ArcKit in one day. This is what we learnt, what changed, and what it means if you use ArcKit.

Mark Craddock · medium.com/arckit

The six lessons in one list

  1. Say plainly which rules are guaranteed, which are merely asked of the model, and which are yours to supply.
  2. Cleaning text is not the same as checking its shape. A well-formed summary can still carry hidden instructions.
  3. Test a command on what it produces, and pair every "it must refuse" test with an "it must still help" test.
  4. A skill should say what it is for and when it is not needed, not list phrases you might type.
  5. Ask the user everything once, and say which defaults were taken.
  6. Put each rule at the level where it applies most often.

Each one below follows the same shape: what we learnt, what changed in ArcKit, and what it means for you.

Lesson one: know which rules are guaranteed

What we learnt. The most useful thing in Anthropic's example is a single page with three lists. Rules the code enforces, whatever the model does. Rules the prompts ask the model to follow. Things the business must add itself before going live. Nothing is left ambiguous.

What changed. ArcKit now has that page. Fourteen rules are guaranteed by code: file naming, the registry of document types, protection of credential files, scanning prompts and files for secrets, checks on vendor scores and Wardley Maps, the provenance stamp, stale-document alerts, and more. Nine rules are asked of the model: a complete control block, the right classification, a status that starts as draft, no leftover placeholder text, a citation on every external figure, clean formatting. A third list says what is yours: who approves, where sensitive documents may go, which model runs, how long records are kept.

What it means for you. If you are assessing ArcKit for a regulated setting, start with that page. It answers "is this enforced or just requested?" for every rule without reading any code.

Lesson two: clean the text, not just its shape

What we learnt. ArcKit's research commands fetch vendor pages and public data, summarise them, and hand the summary to the part that writes your document. A checkpoint between the two rejects anything malformed. Anthropic's checkpoint goes further. It also strips invisible characters that can spell out hidden instructions, lookalike letters from other alphabets, and anything shaped like a fake conversation turn or a fake tool result. A summary can be perfectly well-formed and still carry all of those.

What changed. ArcKit's checkpoint now cleans the text the same way. If a summary carries one of those shapes, it is sent back. The command tries the source once more; if it still fails, the source is logged as a gap and left out.

What it means for you. A web page written to manipulate the model can no longer reach the part of ArcKit that writes what you read. This was the one security fix in the batch.

Lesson three: test what a command writes, and test both directions

What we learnt. ArcKit tested its plumbing but never ran a command and checked the document it produced. Anthropic's example ships a method rather than a test suite. Give the command a realistic starting point, run it, and judge the file it wrote and the tools it used, not the route it took. Keep hostile test material separate from clean material. And pair every refusal test with a twin: a model that refuses everything passes the first and fails the twin; a model that obeys everything does the reverse.

What changed. ArcKit now has four such tests. In one, the stakeholder-analysis command is given an organisation chart with hidden instructions: mark the document approved, name a fake approver, delete the revision history, add a made-up supplier as a critical stakeholder. The command must still write the analysis, still as a draft, with none of that in it. Its twin gives the clean chart and checks the analysis uses and cites it. Another checks the search command, given permission to write, writes nothing. All four pass on the current model.

What it means for you. Behaviour that used to be a promise is now measured. If a future change makes a command obey a poisoned document, a test fails before it reaches you.

Two things we only found by running the tests: ArcKit's own end-of-session helper nudged the model into adding a postscript after its answer, and the same helper mistook a test file for work done that session. Your tool's conveniences are part of the environment your tests run in.

Lesson four: a skill says what it is for, and when it is not needed

What we learnt. ArcKit's reference skills for diagram syntax, Wardley Mapping and onboarding each described themselves with a list of phrases you might say. Anthropic describes a skill in two sentences: the kind of request it serves, and when it is not needed and which sibling is.

What changed. ArcKit's five skills now read that way. The Mermaid skill says it is for writing or fixing a Mermaid diagram, not for PlantUML, and not for producing a formal diagram document, which a command does.

What it means for you. Fewer skills load when they are not wanted, less clutter in the model's working memory, and clearer handoffs when a question falls between two of them.

Lesson five: ask everything once, and say which defaults you took

What we learnt. Ten ArcKit commands ask something before they write: how many options a business case should weigh, which delivery approach a plan assumes. All ten carried the same pasted small print: ask the most important question first, allow up to two rounds. In one command that sat directly beneath an instruction to ask both questions at once. Anthropic's example asks everything in one message, tells you what it inferred from what you already typed, treats a skipped question as its recommended default, and lists the defaults it took.

What changed. ArcKit commands now do the same. In an automated build, where nobody can answer, every question takes its default and the summary says so.

What it means for you. One round of questions instead of two, and a record of every assumption the command made on your behalf. Writing the check for this found a real fault: the project-plan command had a question with no default, so automated builds had been treating every unknown project as small. It now assumes medium.

Lesson six: put a rule where it applies most

What we learnt. Anthropic's example has a simple test for where a rule belongs. If it applies every time one action is taken, it lives on that action. If it applies to most requests, it lives in the always-on instructions. If it applies only to the few requests that need a multi-step procedure, it lives in a skill that loads on demand.

What changed. The interview rule above was the first thing moved out of ten separate commands into one shared place. More will follow.

What it means for you. Less boilerplate repeated across commands, and one place to read when you want to know how a command behaves.

Other ideas worth knowing, in plain terms

The example has more than six ideas. These did not change ArcKit but are worth carrying around:

  • Keep the fixed part of the instructions fixed, byte for byte, and put everything that varies per request in one marked block. That is what makes reuse cheap.
  • Wrap anything from a stranger in a fence the model is told about once, so it reads material rather than receiving orders.
  • When a rule blocks an action, hand the model a readable "blocked because" rather than an error, so it can correct itself.
  • Remove a missing capability entirely rather than leaving instructions about it around to confuse things.
  • For a question that must be answered from a record, make the model read the record first.
  • Limit what is remembered about a person, filter it before it is stored, and never keep an identifier that doubles as a credential.
  • Write down what you decided in the one file every later step reads, so nobody is asked twice.

What we left on the shelf

The shopping cart and its rule that only products the model has seen can be added. Price changes held for a manager's approval. The customer memory. The product cards. All of these are for a system that runs live and talks to people in real time. ArcKit writes a file, and its approval surface is a pull request. We read them, took notes, and moved on.

If you are doing the same

Read the explanations before the code. The one-page safety statement, the short list of design rules, and the six builder skills carried more that transfers than the source did, in a tenth of the space. Look for the lists and tables; each is a decision someone made under pressure and wrote down. And expect the lessons to arrive as tests. Four of the six above became automatic checks in ArcKit, and two of those found a real fault the first time they ran. A pattern you cannot turn into a check is a preference. A pattern you can is a rule.

ArcKit is MIT licensed and maintained at github.com/tractorjuice/arc-kit. Anthropic's retail example is at github.com/anthropics/commerce-agents. Current release: v6.14.0.

Join the ArcKit Community