Tools are under-specified
Without task preconditions and effects, agents can call the right-looking tool at the wrong time.
The pain
Most AI projects skip the business model.
Agents get tool names. RAG gets chunks. Databases get tables. But the system often lacks a shared map of what the business means, what can happen, and what software objects are allowed to touch it.
Retrieval is blurry
Chunks know words, not concepts. "What is a refund?" and "how do I process a refund?" get mixed.
Code hides domain meaning
Tables and API types encode implementation details, but not the business concepts they represent.
What it does
It turns messy inputs into agent infrastructure.
The skill gives an agent an operating procedure: mine evidence, build a four-layer ontology, validate the structure, then emit the format your system needs.
Messy input
Docs, APIs, source code, DB schema, job posts, help centers, standards, events, tests, and tool schemas.
->
Four-layer map
Upper anchors, domain nouns, task verbs, and app bindings tied together with evidence.
->
Useful output
MCP tool schemas, RAG metadata, graph schemas, JSON-LD, TypeScript/Pydantic types, and diagrams.
L0universal anchors
L1domain concepts
L2tasks and effects
L3app bindings
Quick start
One prompt gets any capable agent moving.
Lead with the consumer. The agent should know whether the output is for agent tools, MCP, RAG, a knowledge graph, DB/API design, or documentation.
Paste this into any AI agent
Use AGENT_SKILL.md as your workflow. Target: [company, codebase, product, API, docs, or market]. Consumer: [MCP agent tools, RAG, knowledge graph, DB/API schema, or docs]. Boundary: [what is in and out]. Deliver the YAML layers, mappings, validation notes, and the consumer binding.
# Universal agent usage
Give the agent AGENT_SKILL.md as instructions.
# Optional packaged-skill usage
unzip ontology-extraction.skill -d ./skills
cd ./skills/ontology-extraction
python scripts/scaffold.py init \
--name my-target \
--out ../../my-target-ontology
python scripts/scaffold.py validate ../../my-target-ontology
python scripts/scaffold.py mappings ../../my-target-ontologyProof
The evals show three credible use cases.
These are the examples to put near the top of the GitHub repo. They make the agent skill feel concrete in the first scroll.
Stripe support agent
Extracts Charge, Refund, Dispute, Evidence, Customer, and MerchantAccount, then maps tasks into MCP-friendly support operations.
RealWorld app
Maps Prisma models and Express routes to Member, Article, Comment, Tag, Follow, and Favorite concepts.
Prediction markets
Finds no strong published ontology, then recommends fresh L1 modeling with L3 alignment to Gnosis CTF vocabulary.
Why builders care
The edge is safer automation.
The launch angle is simple: do not let an AI agent act inside a business it does not understand.
Better tool contracts
L2 tasks become tools. Preconditions and effects become descriptions the model can reason over before acting.
Better metadata
L1 concepts and L2 tasks become filters, routing labels, and chunk tags that make retrieval less sloppy.
Better schema cleanup
Every L3 object must bind upward. Unmapped fields expose app-only details, missing concepts, or stale schema.
Better reverse engineering
Public docs, APIs, pricing pages, and job posts become a structured map of how a company operates.
Better interoperability
The skill reuses schema.org, gist, PROV-O, FIBO, FHIR, GS1, and other vocabularies where they fit.
Better shared language
Product, engineering, data, docs, and agents all get the same names for the same business objects.
Repo packaging
Ship it as a developer tool, not a document.
Put the examples and validator close to the top. Make the first minute feel obvious.
agent-ontology-kit/
README.md
LICENSE
AGENT_SKILL.md
ontology-extraction.skill
ontology-extraction/
SKILL.md
scripts/
scaffold.py
references/
output-formats.md
reuse-catalog.md
source-mining.md
examples/
stripe-support-agent/
realworld-express/
prediction-markets/
docs/
guide.html
launch.html
screenshots/
hero.png
examples.png- Lead with the agent/RAG problem, then explain ontology as the mechanism.
- Show the file tree output before deep explanation.
- Include the Stripe and RealWorld examples as proof.
- Add both paths: universal AI-agent usage and optional packaged-skill usage.
- Include a validator screenshot or terminal output.
- Use GitHub topics like ai-agents, mcp, rag, knowledge-graph, ontology, semantic-layer.
agent-ontology-kit
domain-map-for-agents
semantic-agent-maps
agent-schema-miner
agent-domain-modeler
Paste-ready opener
A README intro that sells the practical value.
This is the kind of opening that makes the project feel immediately useful instead of academic.
README.md opener
# Agent Ontology Kit
Make AI agents understand a business before they act.
Agent Ontology Kit is a portable skill for AI agents. It extracts
structured, agent-ready domain models from product docs, APIs,
companies, markets, and codebases.
Use it from Claude Code, Codex, Cursor, custom agent runners, or any
capable AI agent through AGENT_SKILL.md. Humans can also run the YAML
templates and validator script directly.
It produces a four-layer ontology:
- L0 upper anchors: universal categories like Agent, Event, Object
- L1 domain concepts: the nouns of the business
- L2 tasks: the verbs, workflows, preconditions, and effects
- L3 application bindings: DB tables, API types, events, tool schemas,
UI objects, and field mappings
Use it to generate:
- safer MCP tool schemas
- RAG metadata and routing labels
- knowledge graph schemas
- DB/API semantic mappings
- codebase audit notes
- market/company structure maps
Why this matters:
Most agent projects define tools before defining the world those tools
operate in. This skill gives the agent a grounded map first.