Ontology-driven-dev: a three-stage skill that forces a coding agent to stop and ask

What the skill is and what it promises

Ontology-driven-dev is a skill for coding agents, not a library and not a running system. It encodes a three-stage method: requirement exploration, ontology modelling, then application build. You describe a business need in a sentence or a paragraph and the agent is supposed to walk you to a working browser-based management system.

Four promises are stated in the README. Every function traces back to an entry in the requirements document. The model is the source of semantics, so database tables, interfaces, menus, permissions, flows and rules are all generated from the seven-model YAML, which is aimed squarely at the common failure where the model says one thing and the code says another. The human gates cannot be skipped: requirement exploration has eight stages and each one pauses for confirmation. And the technical base is included rather than left to the agent to invent.

The audience is narrower than the promise suggests. This is built for CRUD-heavy internal business systems with approvals, roles and reports. A stateless service, a data pipeline or a mobile app gets little from an ontology registry and a flow engine.

The seven models and the gates between them

Modelling produces seven YAML files plus a manifest: M1 for objects, M2 for behaviours, M3 for rules, M5 for subjects, M6 for flows, M7 for queries and reports, and MU for the interface. Note the numbering skips M4, which is how the repository lists them. The output directory is yaml/.

The interesting part is not the list but the consistency gates the skill enforces between the files. Traceability is checked, M7 and M2 must correspond one to one, and M6 references must be acyclic. Those three rules encode the failure modes of model-driven development: a report that describes behaviour nobody implemented, and a set of flows that reference each other in a loop.

Input to this stage is tightly constrained. The README says stage two takes appendix C of the stage one requirements document as a deterministic baseline and does not re-open broad business decomposition. That is a deliberate narrowing: by the time modelling starts, the scope questions are meant to be settled, and the model is a translation exercise rather than a discovery one.

Stage one: eight stages, each with a hard stop

Requirement exploration runs through eight stages in order: overall understanding, business objects, business functions and rules, cross-object linkage, end-to-end collaboration and approval flows, queries and reports, roles and permissions, and an optional UI prototype.

At the end of each stage the agent must ask in a fixed format: the question, an AI suggestion, the reasoning, other options, and quick replies. Then it pauses and waits. The README states this pause is mandatory, and adds that enterprise-specific content must be asked with an AI suggestion attached, and that an unconfirmed stage cannot advance.

That is the most opinionated part of the design, and it cuts both ways. A hard stop at eight points turns a one-shot generation into a guided interview, which is slower and dramatically less likely to produce a system built on invented assumptions. It also means the human in the loop has to actually be there, eight times, per system.

The output is a requirements specification named for the business domain with a V9 suffix, containing appendix C as the modelling baseline.

Installing the skill and running the bundled example

The README is explicit that the skill depends on no WorkBuddy-specific mechanism and runs in Claude Code, Codex, Cursor and similar tools, with the only adaptation being that relative paths resolve from the SKILL.md directory. For Claude Code the frontmatter matches its skills format, so installation is a copy:

cp -r ontology-driven-dev ~/.claude/skills/ontology-driven-dev

The equivalent for WorkBuddy is a copy into ~/.workbuddy/skills/ontology-driven-dev, and for Codex a copy into .codex/skills plus one instruction line in codex.md or AGENTS.md. For Cursor, Aider or Cline the guidance is to treat SKILL.md as a methodology file, either in project rules or pasted at the start of a conversation.

The fastest way to see what the output looks like is the bundled example. Copy the technical base into a working directory as code-app, install both sides, and start them:

cd code-app/backend && pip install -r requirements.txt && python app.py

That serves the backend on http://localhost:5000. The frontend runs separately:

cd code-app/frontend && npm install && npm run dev

on http://localhost:5173. The documented default account is admin with the password admin123, and the environment requirements are Python 3.10 or newer and Node.js 18 or newer, with a network connection needed for the first install.

What code-paas hands you, and what it commits you to

The technical base is called code-paas and lives in techbase/. It is a Flask plus SQLite backend with a flow engine, an ontology registry and a service layer, and a React and TypeScript frontend built with Vite, plus example model files and its own README. Copying it is the intended starting point rather than generating a project from nothing.

What it commits you to is a specific shape of application. The build order in the guidance document is ten steps: write the seven-model YAML, generate DDL and tables, register the data dictionary, add behaviour and rule services, seed roles and permissions, wire the flow engine, add menu and page routes, implement the right-side AI chat, run a full-chain integration test, then acceptance.

That last but one item is not optional. The README lists a mandatory AI chat panel in every generated application, implemented through ontology registry injection, tool calling, SSE streaming and a read-only SQL safety boundary. That is a sensible design for letting a model answer questions over business data, and it also means an app built this way is expected to ship with a model connection, not just forms and tables.

The usual agent workflow is the alternative

The realistic comparison is not another skill, it is what most people already do: write a paragraph or a product requirements document, hand it to a coding agent, and iterate on the code until it looks right.

That approach is faster at the start and weaker later. Without a machine-readable model, the requirements document and the database schema are two artifacts that nothing keeps in sync, so the drift is invisible until a report disagrees with a screen. There is also no gate: the agent fills every gap with a plausible guess and moves on, and the guesses are buried in code rather than listed as open questions.

This skill trades speed for those two properties. You spend eight confirmations up front and maintain YAML afterward, and in exchange the tables, menus, permissions, flows and reports descend from one description, and anything the agent was unsure about surfaced as a question you answered. Whether that is worth it depends entirely on whether the system will live long enough for drift to matter.

Limitations, documentation language and upkeep

Several limits are visible from the repository itself. The default persistence is SQLite, which is fine for the bundled example and a poor fit for concurrent multi-user use, and the documented default account is admin with password admin123, which must be changed before anything leaves a laptop. The example ships with its AI API key cleared, so the assistant does nothing until an OpenAI-compatible service is configured in the interface.

Documentation is primarily Chinese, with a separate README_EN.md at the root, and the five methodology documents under references are described as mandatory specifications. That makes the skill token-hungry: an agent is expected to read a requirements specification standard, a modelling framework, a development guide, an architecture document and a UI specification before producing anything. On a small model or a tight context window that is a real cost.

Maintenance is quiet but recent. The repository publishes no releases, and the last push was on 2026-09-07. Both the skill and the code-paas base are MIT licensed, so you can fork and modify freely, including commercial use, subject to keeping the notice. The bundled example, a sales contract execution system with tiered approval, invoicing, payment collection, cross-object status linkage and fixed reports, is the best evidence of whether the method produces something you would want to own.

Editorial conclusion

Reach for this skill if you use a coding agent to build business admin systems and you keep hitting the same failure: the code and the requirements drift apart, and nobody notices until the demo. Its answer, a machine-readable seven-model YAML as the single source for tables, APIs, menus, permissions, flows and rules, plus a human gate at each of eight exploration stages, is a genuine answer to that problem. Do not adopt it if you want fast throwaway prototypes or if nobody will sit through the confirmation stages, because the discipline is the product. Before committing, install it for one tool, run the bundled sales contract example end to end, and decide whether the YAML is something your team will actually maintain.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. sharptoolbox/ontology-driven-dev on GitHub