What just happened

We asked a toolkit to describe itself — and it didn't trip.

This page explains, with no jargon, what that toolkit does, the simple idea behind it, and the proof we just produced by pointing it at its own code.

It passed its own quality check: 0 errors, 0 warnings — verified by running its built-in validator.

Then aimed at two rival payment APIs — 8 of 9 core concepts matched across Stripe and Adyen.

Start here

What is this thing, really?

AI agents are good at doing things — sending refunds, booking slots, calling APIs. They're bad at first understanding the business they're acting inside. They'll happily refund an order that was never paid for, because nobody told them that's impossible.

The Agent Ontology Kit fixes that. It's a reusable recipe that reads a company, product, or codebase and writes down a clean, structured map of how that world works — the things that exist, the actions you can take, and the rules between them — in a form a machine can actually use before it acts.

One sentence: it turns fuzzy "how this business works" knowledge into a precise map, so an AI doesn't have to guess.

The core idea

It sorts everything into four layers

Imagine describing a coffee shop to a robot. You'd naturally explain it at four levels of zoom — from "universally true of anything" down to "this exact shop's stuff." That's the whole method.

L0 · Universal

Basic kinds of things

a thing, a person, an action, an amount — true of any business on Earth

L1 · The trade

The nouns of the field

Order, Drink, Barista, Receipt — true of every coffee shop

L2 · The doings

The actions + their rules

TakeOrder, MakeDrink, Refund — "can't refund what wasn't paid"

L3 · This exact shop

The real files & buttons

their orders database table, the "new order" button

↑ Hover the stack to fan it out. Top = most universal, bottom = most specific.

The one rule that makes it powerful

Each layer must connect to the one above it. This shop's orders table (L3) points up to the idea of an "Order" (L1), which points up to a basic "thing" (L0). The actions (L2) say which nouns they use and what must be true first.

Because everything links upward, you get one connected map — not four disconnected sticky-note piles. That connection table is the actual prize.

Why bother with the top layer? Because "Order" in a coffee shop and "Charge" at Stripe are secretly the same kind of thing. Anchoring to universal categories lets different systems understand each other for free.

The interesting twist

We pointed the toolkit at itself

Instead of mapping a coffee shop or Stripe, we aimed the kit at its own codebase — like a dictionary that contains the definition of the word "dictionary," or a camera photographing itself in a mirror.

So the four layers came out describing the craft of map-making itself:

Layer	For the coffee shop, this was…	For the toolkit itself, it became…
L0 Universal	a thing, a person, an amount	the same universal categories (borrowed from a published standard — never invented)
L1 Nouns	Order, Drink, Barista	Ontology, Layer, Class, Relation, Task, Evidence — the vocabulary of map-making
L2 Actions	TakeOrder, Refund	ScopeTarget, MineSources, BuildDomainLayer, Validate, EmitOutput — the workflow steps
L3 Real files	the `orders` table	the actual repo files: `scaffold.py`, the `20-domain.yaml` template, the docs

The satisfying part: a self-description is a brutal honesty test — if the method were sloppy, describing itself would contradict itself. It didn't. The kit's own validator checked the result and found nothing broken.

The receipts

What actually came out

universal anchors (L0)

nouns + 14 links (L1)

workflow actions (L2)

real file artifacts (L3)

20-domain.yaml · one of the 13 nouns, in the kit's own words

- id: Relation
  definition: "A typed link between two ontology classes with domain,
    range, and cardinality; its presence is what makes an
    ontology more than a taxonomy."
  upper: Category        # ↑ anchors to a universal kind
  source: "SKILL.md modeling rules"  # ← evidence, or it didn't happen

In plain terms: every entry has a one-line definition, points upward to a universal category, and cites where it came from. No unsourced claims allowed — that "source" rule is what keeps the map honest.

The payoff

One map, spoken in three languages

Here's the real point. From that single map, the kit generated three different outputs — each shaped for a different audience. Write the understanding once; everyone gets the version they can read.

A to-do list for an AI

Each workflow step becomes a tool the AI can call — with its safety rules written into the description.

e.g. "emit the output — only AFTER the check passes, never before."

Read by · an AI agent

A web of facts

The same map as a queryable database of connected facts. We literally asked it questions and it answered.

252 facts, machine-checked — a real parser read it with zero errors.

Read by · a knowledge graph

A picture for people

A clean diagram showing the layers stacked and the workflow flowing — so a human can grasp it in a glance.

Color-coded by layer, exactly like this page.

Read by · humans

the AI's to-do list · one step, with its rule baked in

"name": "emit_consumer_binding",
"description": "Emit the final output (tools, graph, diagram…).
  PRECONDITION: validation passes — emit AFTER validation, never before."

Why this matters: the AI can't skip a safety step, because the rule travels with the tool. The understanding and the guardrail are the same object.

the web of facts · we asked it a question, it answered

# Question: "what does the BuildDomainLayer step produce?"
SELECT ?c WHERE { :BuildDomainLayer :producesClass ?c }

# Answer it gave back:
  → :OntologyClass
  → :Relation

In plain terms: it's not just a document — it's a thing you can interrogate. Ask it how the world fits together and it replies with exact answers.

And they stay in sync. Because all three come from the same source map, fixing the map once regenerates all three. No more updating a diagram, a database, and a config file by hand and watching them drift apart.

The real test · round two

But does it work on someone else's business?

Describing itself is neat — but here's the bolder promise: the middle layer (the nouns of a trade) should come out the same for any company in that trade. Only the bottom layer — one firm's specific files — should differ. So we pointed the kit at two rival payment companies: Stripe and Adyen.

Everyday version: learning to drive transfers from a Toyota to a Honda — "steering wheel," "brake," "indicator" mean the same thing; only the dashboard layout changes. If the kit is any good, an AI taught the concepts of payments shouldn't need re-teaching when you switch providers.

8/9 core concepts in Stripe had an exact counterpart in Adyen — the shared vocabulary an AI could reuse across both, with zero relearning.

Stripe's word	Adyen's word	Same idea?
Charge	Payment	✅ a fund movement
Refund	Refund	✅ identical
Dispute	Dispute	✅ identical
Dispute Evidence	Defense Document	✅ proof to contest a charge
Customer	Customer / Shopper	✅ the payer
Merchant Account	Merchant Account	✅ identical
Support Agent	Payments Agent	✅ the operator
Monetary Amount	Monetary Amount	✅ identical
Payment Intent	—	⚠️ a Stripe-only framing

The single mismatch is genuinely a Stripe-specific idea — an honest result, not a fudged one. And Adyen actually contributed more concepts (it exposes a separate "capture" step and staged chargebacks that Stripe's setup keeps hidden), so the shared map got richer, never contradictory.

The whole idea, in one strip

Top = universal and identical. Bottom = each company's private plumbing. The further down you go, the less transfers — exactly as the four layers promise.

identical — same universal anchors

8 of 9 shared — the trade, not the vendor

diverges — actions follow each API's buttons

0% shared — each firm's files are its own

Why this is the result that pays for itself: build your AI agent once on the shared middle layer, and you can swap payment providers without re-teaching it the business. Only the bottom wiring changes — and the kit regenerates that part for you. Both maps validated clean, and the 8/9 figure was computed from their own files, not asserted by hand.

So why should anyone care?

Because the expensive, error-prone part of building AI tools isn't the code — it's making sure the AI actually understands the rules of the world it's touching. This kit makes that understanding explicit, checkable, and reusable.

Safer agents. Rules like "you can't refund an unpaid order" become part of the tools, not folklore.

Less drift. One source of truth feeds the AI, the database, and the docs at once.

Proven on itself. The method survived describing its own code with zero contradictions.

Proven across rivals. The domain layer matched 8/9 between two competing payment APIs — Stripe ↔ Adyen.

Jargon, defused

If you bumped into a scary word

Ontology

A structured map of what exists in some world and how it all connects. Fancier than a list, because it records the relationships and rules, not just the items.

The four layers (L0–L3)

Four levels of zoom: L0 universal kinds → L1 the nouns of the trade → L2 the actions → L3 this exact system's files. Each connects to the one above it.

MCP tools

A standard way to hand an AI a set of "buttons it can press," each with a description of what it does and the rules for using it. The kit generates these automatically from the action layer.

Knowledge graph / Turtle / RDF

A way of storing facts as a web of connected dots that a computer can search and reason over. "Turtle" is just the text file format we wrote it in. We confirmed it's valid by loading it into a real database tool.

Validation / "0 errors"

The kit ships a script that checks the map for mistakes — broken links, things that point nowhere, duplicates. Running it on our self-map returned a clean bill of health.

Retrofit mode

Pointing the kit at code you already own (versus researching an outside company). That's the mode we used on the kit's own repository. For Stripe and Adyen we used research mode instead — reading their public docs.

Competitor swap

The kit's promise that the middle "nouns of the trade" layer stays the same when you switch from one company to a rival in the same business — only the company-specific bottom layer changes. We checked it on Stripe vs Adyen: 8 of 9 concepts matched.