A Claude Code plugin for professional ontology design. Brings methodology, validation discipline, and independent review to OWL, RDF/Turtle, SHACL, and SKOS modeling sessions.

Three chained skills — designing-ontologies → planning-ontologies → implementing-ontologies — turn a domain brief into a validated, reviewer-approved Turtle artifact. An optional 4th skill, visualizing-ontologies, turns that artifact into a self-contained, offline HTML viewer you open in a browser.

Installation

In Claude Code:

/plugin marketplace add florian23/ontocraft
/plugin install ontocraft@ontocraft

After install, designing-ontologies auto-triggers on ontology / knowledge-graph / taxonomy / controlled-vocabulary tasks — even when the user doesn't say "ontology" explicitly. From there, the skills chain: each phase ends by invoking the next.

The three phases

Skill	Job	Output
designing-ontologies	Discovery: domain & purpose, competency questions, vocabulary reuse decisions, output flavor (OWL/SHACL/SKOS-mix). One question per turn. Self-review at the end.	design.md
planning-ontologies	Modeling plan: Mermaid classDiagram (high-level architecture), file-map, bite-sized sequenced modeling tasks (each citing the CQ it serves and the OOPS pitfall it avoids).	plan.md
implementing-ontologies	Build: write Turtle file-by-file. Two-gate validation loop until clean: (1) validate.py (parser + OWL-RL + SHACL + lint), (2) independent reviewer agent (OOPS, Gruber, FAIR, OQuaRE, CQ coverage).	<name>.ttl, review.md

Each skill is independently triggerable — if you already have a design.md, you can call planning-ontologies directly; same for implementing-ontologies with an existing plan.md.

Optional: visualize the ontology

The visualizing-ontologies skill turns any .ttl into one self-contained, offline HTML file — fonts and JavaScript are embedded, so there's no server, no npm, and no network request at load. It opens with two views toggled in the top bar:

• Read (Codex, default) — reads the ontology one class at a time: a collapsible subClassOf index on the left, and each class as a typeset "entry" — title, a plain-language gloss, its axioms as readable sentences (⊑ is a …, ⊑ <property> ∃/∀ …, ≡ …, ⊘ disjoint with …), multilingual labels, related-class chips, and a small relationship figure.
• Graph — the interactive Cytoscape.js relationship graph: layout switcher (hierarchy / a tunable non-overlapping force layout with a spacing slider / concentric), overview-first depth limit, filter panel, neighborhood focus, VOWL mode, asserted-vs-inferred distinction, PNG/SVG export.

When a paired design.md/review.md is found, CQ-coverage and reviewer-finding overlays are populated automatically. The skill runs standalone on any OWL/SKOS/SHACL Turtle file, and implementing-ontologies offers it after its three gates pass.

python skills/visualizing-ontologies/scripts/run.py viz.py <onto.ttl> [imports…] [--no-reason] [--slug <slug>] [--open]

→ writes docs/ontocraft/viz/<YYYY-MM-DD>-<slug>-viewer.html (shares the design/plan/review slug).

What it gives you

• Methodology — Ontology Development 101 (Noy & McGuinness 2001), competency questions as scope + acceptance test, vocabulary-reuse before coining, Content Ontology Design Patterns
• A two-gate validation harness in implementation phase:
  • Gate 1 — validate.py runs four layers: Turtle syntax (rdflib), OWL-RL consistency (owlrl), SHACL conformance (pyshacl), and an advisory lint layer (declared-but-unused prefixes)
  • Gate 2 — an independent reviewer agent applies five lenses: OOPS! pitfall catalog (41 modeling antipatterns), Gruber's five design principles, FAIR for ontologies (15 subprinciples), OQuaRE (ISO 25000-style 1–5 score per quality subcharacteristic), and competency-question coverage
• Reference material the reviewer cites and the designer reads on demand: full OOPS catalog, Ontology 101 walkthrough, competency-question patterns, reusable-vocabularies lookup table, OWL/Turtle cheat sheet, SHACL patterns, SKOS patterns, T/A/R/C-Box terminology
• Self-bootstrapping Python tooling — scripts/run.py creates an isolated .venv on first invocation and installs pinned dependencies. No system pollution.
• An offline, self-contained viewer — the optional visualizing-ontologies skill renders the ontology as a single HTML file (Codex reader + interactive graph). Vendored JS and base64-embedded fonts, no server/npm, and it reuses the existing rdflib/owlrl venv — no new runtime dependencies.
• Eval framework with a comparator agent that scores outputs against known goldstandard ontologies (Manchester Pizza, W3C SOSA, ISO 3166 SKOS) plus three greenfield briefs

Usage example

Just describe the domain in natural language:

"Wir betreiben eine Pizzeria und brauchen ein formales Modell unserer Speisekarte, das automatisch erkennen kann, ob eine Pizza vegetarisch ist..."

The workflow:

1. designing-ontologies elicits CQs, decides reuse + flavor → writes design.md → asks for approval
2. planning-ontologies writes plan.md with class diagram + sequenced tasks → asks for approval
3. implementing-ontologies executes the plan, runs validate-loop + reviewer-loop → hands over the .ttl + review.md

Quality evidence

In a 12-run benchmark across 6 domains (3 with established goldstandards, 3 greenfield):

Configuration	Auto pass-rate	Comparator coverage vs. goldstandards (mean)
with skill	96.7%	88.7 / 100
without skill	80.0%	66.0 / 100

The skill's main lifts come from validation discipline (one baseline run produced an artifact that didn't even parse), enforced vocabulary reuse (skos:broader instead of dct:subject), and production-ready hygiene (license, multilingual labels, declared-but-actually-used imports).

Requirements

• Claude Code with plugin support
• Python 3.10+ anywhere on PATH — scripts/run.py does the rest (creates an isolated venv, pins rdflib, owlrl, pyshacl)
• Optional but recommended for full DL reasoning: robot reason (Java-based; the skill notes when DL goes beyond what owlrl can verify)
• The visualizing-ontologies viewer needs no extra dependencies — it reuses the pinned rdflib/owlrl and vendors its JS + fonts offline; the output is a single self-contained .html you open with file:// (no network, no build)

Repository layout

ontocraft/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── agents/                          # SHARED across skills
│   ├── ontology-reviewer.md
│   └── ontology-comparator.md
└── skills/
    ├── designing-ontologies/
    │   ├── SKILL.md
    │   └── references/              # CQs, reusable vocabularies, box terminology, ontology-101
    ├── planning-ontologies/
    │   ├── SKILL.md
    │   └── references/              # OWL/Turtle, SHACL, SKOS patterns, ontology-101, box terminology
    ├── implementing-ontologies/
    │   ├── SKILL.md
    │   ├── references/              # OWL/Turtle, OOPS pitfalls, SHACL/SKOS patterns, ontology-101
    │   ├── scripts/                 # run.py, validate.py, compare_ontologies.py, lov_search.py
    │   ├── assets/templates/        # OWL, SHACL, SKOS skeletons
    │   └── evals/                   # eval suite + goldstandards
    └── visualizing-ontologies/      # OPTIONAL viewer skill
        ├── SKILL.md
        ├── references/              # graph-model schema (extractor→frontend contract)
        ├── scripts/                 # own run.py + viz.py, extractor.py, reasoner.py, overlays.py, render.py
        └── assets/                  # viewer-template.html, viewer-app.{css,js}, vendor/ (cytoscape, dagre, fonts)

Contributing

See CONTRIBUTING.md. Pull requests welcome, especially:

• New entries in references/reusable-vocabularies.md for domains the lookup table doesn't yet cover
• Additional pitfall checks in scripts/validate.py's lint layer
• Improvements to the reviewer agent's calibration

License

MIT — see LICENSE.

Acknowledgments

This skill leans heavily on:

• Noy & McGuinness, Ontology Development 101: A Guide to Creating Your First Ontology (Stanford KSL, 2001)
• Poveda-Villalón, Suárez-Figueroa & Gómez-Pérez, OOPS! (OntOlogy Pitfall Scanner!) — IJSWIS 2014, with the 41-pitfall catalog at https://oops.linkeddata.es
• Gruber, Toward Principles for the Design of Ontologies Used for Knowledge Sharing (1995)
• The W3C SOSA/SSN, OWL-Time, SKOS, and SHACL specifications
• The semantic-anchor design pattern (https://github.com/LLM-Coding/Semantic-Anchors)