🧭 Agent Ontology Kit

Make AI agents understand a business before they act.

Agent Ontology Kit is a portable skill for AI agents. It reads a company, product, API,
market, or codebase and writes 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 an agent can use
before it acts.

No framework. No build step. It's markdown you hand to any capable agent (Claude Code, Codex,
Cursor, custom runners), plus a tiny Python validator.

▶ Live explainer — in plain English · Examples · Quick start

🤔 The problem

AI agents are great at doing things — issuing refunds, booking slots, calling APIs. They're bad
at understanding the business first. An agent will happily refund an order that was never paid,
because nobody told it that's impossible.

This kit makes that understanding explicit, checkable, and reusable.

🧱 What it builds: four layers

Imagine describing a coffee shop to a robot — from "true of anything" down to "this exact shop."

Layer	Plain English	Coffee-shop example
L0 · Upper	universal kinds of things	a thing, a person, an amount
L1 · Domain	the nouns of the trade	Order, Drink, Barista
L2 · Task	the actions + their rules	TakeOrder, Refund ("can't refund what wasn't paid")
L3 · Application	this exact system's files	the `orders` table, the "new order" button

The discipline that makes it worth doing: every L3 maps to an L1, every L1 anchors to an L0,
every L2 names the L1 nouns it touches. That cross-layer mapping table is the deliverable.

🚀 Quick start

Give any capable agent this:

Use AGENT_SKILL.md as your workflow.
Target:   <company, API, product, market, or codebase>
Consumer: <MCP agent tools | RAG | knowledge graph | DB/API schema | docs>
Boundary: <what is in and out of scope>
Deliver:  the YAML layers, the mapping table, validation notes, and the consumer binding.

That's it. The agent scopes the target, mines sources, builds the four layers, validates them,
and emits the output your consumer needs.

🛠️ Run the tooling locally (optional)

cd ontology-extraction
python3 scripts/scaffold.py init --name my-target --out ../my-target-ontology
# ...fill in the YAML layers...
python3 scripts/scaffold.py validate ../my-target-ontology   # 0 errors = structurally sound
python3 scripts/scaffold.py mappings ../my-target-ontology    # regenerate the crosswalk

The only dependency is pyyaml (pip install pyyaml). The skill itself needs nothing.

📦 What you get

A 7-file workspace plus a consumer-specific binding:

my-target-ontology/
  00-scope.md          target, consumer, boundary, competency questions
  10-upper.yaml        L0 — chosen universal anchors (selected, never invented)
  20-domain.yaml       L1 — the domain nouns + relations
  30-task.yaml         L2 — the actions, with inputs/outputs/preconditions/effects
  40-application.yaml  L3 — the concrete system artifacts
  50-mappings.yaml     the app → domain → upper crosswalk
  README.md

…then one binding: MCP tool schemas, an RDF/Turtle knowledge graph, TypeScript/Pydantic types,
RAG metadata, or a Mermaid diagram.

🧪 Worked examples

Five runs in examples/, each validated clean by the bundled script:

Eval	Target	Highlight
`eval-1-stripe`	Stripe (research)	API → safe MCP tools with preconditions baked in
`eval-2-realworld`	RealWorld app (retrofit)	map an existing codebase to its domain
`eval-3-prediction-markets`	a market (research)	a sparse / emerging domain
`eval-4-self`	the kit itself	it described its own code — 0 errors
`eval-5-adyen`	Adyen (research)	competitor swap vs Stripe: 8/9 domain concepts matched ⭐

The plain-English walkthrough of the last two is in explain.html.

💡 Why four layers (the payoff)

Because the middle layer belongs to the trade, not the vendor. We proved it: building the same
model for Stripe and Adyen, 8 of 9 core concepts matched — only the bottom, vendor-specific
layer differed (see examples/eval-5-adyen/comparison-vs-stripe.md).
Build your agent once on the shared layer; swap providers without re-teaching it the business.

🔌 Use it as a skill

Claude Code / Cursor / Codex: point the agent at AGENT_SKILL.md, or drop the
ontology-extraction/ folder into your skills directory (it has a ready SKILL.md with trigger
frontmatter).
Any runner: the workflow is plain markdown — no runtime lock-in.

🌐 Publish the site (GitHub Pages, zero build)

index.html (landing) and explain.html (explainer) are self-contained static HTML.
Settings → Pages → Deploy from a branch → main / (root).
Your live site: https://<your-username>.github.io/<repo>/.

🗺️ How it works

Work middle-out: scope → competency questions → mine sources → anchor L0 → build L1 → build L2
→ project L3 → validate → emit the binding. Full method in
ontology-extraction/SKILL.md; evidence rules, reuse catalog, and
production design principles in ontology-extraction/references/.

The design bias is deliberately domain-driven: model how the real business operates, not a 1:1 copy
of source tables or departmental systems. The validator now flags common ontology anti-patterns such
as God Objects, Kitchen Sink schemas, duplicated department/system classes, action sprawl, vague
misnomers, and over-deep hierarchies that should be replaced with reusable interfaces.

📁 Repo layout

.
├─ README.md
├─ AGENT_SKILL.md            ← the portable workflow — hand this to any agent
├─ index.html · explain.html ← zero-build site (deploy to GitHub Pages)
├─ ontology-extraction/
│  ├─ SKILL.md
│  ├─ scripts/scaffold.py    ← init · validate · mappings
│  └─ references/            ← source-mining · reuse-catalog · design-principles · output-formats
└─ examples/                 ← 5 worked, validated evals

🤝 Contributing

PRs welcome — new worked evals (a real company/API/codebase + its validated ontology) are the most
valuable contribution. Run python3 scaffold.py validate before opening a PR.

OntologyEX