# Scholar Ontology > Use when distilling an ontology, controlled vocabulary, or glossary of what a codebase, a repository set, or a written corpus calls things. - Skill: `tony/scholar-ontology` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add tony/scholar-ontology` - Raw SKILL.md: https://api.skillmd.com/api/skills/tony/scholar-ontology/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tony (https://skillmd.com/u/tony) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tony/scholar-ontology --- # this skill Distil what a corpus calls things into a type hierarchy, a controlled vocabulary, and an evidence layer. The product is a study directory, not a document, and every claim in it either cites a pinned source or carries a command that reproduces its number. Read `references/evidence-tiers.md` before starting; it decides what each claim must carry. `references/citation.md` governs every pin. `references/stage-gates.md` states each stage's exit condition. User arguments: $ARGUMENTS ## Core thesis An agent that has read a corpus usually returns a summary. A summary cannot be checked, does not compose, and rots without saying so. The test this pipeline is built against: ``` CAN A READER WHO WAS NOT PRESENT DISAGREE WITH A CLAIM, FIND WHAT IT RESTS ON, AND RE-DERIVE IT? ``` A study that fails that test is a summary with more sections. ## Context Repository — run this command and read the output: ```bash git remote get-url origin 2>/dev/null || echo "(not a git repository)" ``` Current ref — run this command and read the output: ```bash git rev-parse --short HEAD 2>/dev/null || echo "(unknown)" ``` Existing studies — run this command and read the output: ```bash ls notes/ontology/ 2>/dev/null || echo "(none)" ``` ## Stages Five stages, run in order. Each is separately invocable, so a study resumes where it stopped rather than restarting. 1. the `scholar-gather` skill — resolve and pin the corpus, inventory it, and record what was read and what was skipped, into `sources.jsonl`. 2. the `scholar-extract` skill — harvest the terms the corpus uses, with a citation and a locator each, into `terms.jsonl`. 3. the `scholar-distill` skill — build the three layers: types, members with discriminators, and the controlled vocabulary. 4. the `scholar-contest` skill — judge the ontology adversarially, one candidate at a time, recording the kills. 5. the `scholar-render` skill — write `brief.md` and the evidence documents, and gate the brief. For prose, run the `scholar-annotate` skill before `extract` to produce quotations with stable locators. `--resume=` starts at that stage against an existing study directory. ## Orchestration Plan Enter plan mode before touching anything — `EnterPlanMode` in Claude Code, `/plan` or Shift+Tab in Cursor, Codex, and Gemini. Where plan mode is unavailable, present the same plan in chat and wait. The plan states: - The corpus: each target, its resolved ref, and how it was resolved. - The kind — code, prose, or fleet — and what that changes about stages 1 and 2. - The output directory, and confirmation that it is not inside the corpus. - Which stages will run, and which are being skipped because a prior study already satisfies them. - The coverage boundary: what will deliberately not be read, and why. Present it, wait for approval, then exit plan mode and run stage 1. ## Rules - Never write into the corpus being studied. Output lands under `--out`, defaulting to `notes/ontology//` in the current repository. - Every claim carries a tier. A claim that fits neither tier does not go in the brief. - The brief carries no citation, no permalink, and no bare number. Where it wants one, it links into `evidence/`. - A stage may not hand off until its gate passes. Report a failed gate; do not work around it. - Terms are recorded as the corpus spells them. Variants are the evidence, not noise to normalize away. - The analyzer proposes; it never decides. Every finding gets a human or agent verdict recorded in `evidence/contested.md`. ## Output Open with a one-line hero (`✓ : terms, types, contested` or `⚠ Blocked: `), then exactly these sections: 1. `## Corpus` — each source, its resolved ref, and what was deliberately not read, with the reason. 2. `## Ontology` — the type hierarchy in prose, each type with its discriminator, and the vocabulary's preferred terms. 3. `## Contested` — what was challenged and how it resolved, including what was killed and what the kill revealed. 4. `## Where it lives` — the study directory path and which stages ran. End with an `ask-user-choice` panel offering next steps (for example: contest another round, compare against another study, publish the brief, stop here) — skip the panel only in plan mode. ## Portability notes - `ask-user-choice` — present the listed options and wait for the user to pick one. Hosts with a structured multiple-choice tool (Claude Code's `AskUserQuestion`) should use it; otherwise print a numbered list and wait for a numbered reply. Never proceed on an assumed answer. - `$ARGUMENTS` — the text the user passed when invoking this skill. If your host does not substitute it, read it as the user's request in the current turn, and ask when there is none. - Bundled files — every relative path in this skill points at a file shipped inside this skill directory. Read them from here, not from the host's plugin tree.