concepts
Skill0 starsChanged 2 months agoApache-2.0View on GitHub
Run the concept-merger reducer subagent over the per-node enrichment sidecars to produce or refresh `lineage/{repo}/concepts.yaml` — the deduplicated concept catalog with cross-axis equivalences and canonicalisation candidates. Anchored on `documentation/docs/main-concepts.md` for the canonical vocabulary. Maintainer-curated entries preserved across refreshes.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- austintgriffith/ethskillstheir own version, first seen Oct 8, 2026
- clockworklabs/SpacetimeDBtheir own version, first seen Oct 8, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- clockworklabs/SpacetimeDB★ 26ksame name
- austintgriffith/ethskills★ 303same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository27 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- alignSkill
- code-walkSkill
- contributeSkill
- coverageSkill
- doc-gap-checkSkill
- enrichSkill
- enumerateSkill
- find-implicit-adrsSkill
- implementSkill
- ingest-docsSkill
- log-issueSkill
- navigateSkill
- next-batchSkill
- orientSkill
- panelSkill
- probe-defineSkill
- probe-runSkill
- probeSkill
- reflect-featureSkill
- retrieveSkill
- reviewSkill
- scanSkill
- statusSkill
- streamsSkill
- test-coverageSkill
- triageSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 2 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 25
Before spawning the subagent in default (incremental) mode, the skill computes:
- Distinctive: line 44
Read these (skip if already loaded this session):
- Very specific: line 55
Canonical-vocab source: prefer ../documentation/docs/main-concepts.md (local sibling repo).
- Very specific: line 56
Substrate state: read lineage/{repo}/manifest.yaml's last_scan_commit so the produced catalog can record generated_at_commit.
- Distinctive: line 78
After the subagent reports completion:
- Very specific: line 82
Verify the four top-level lists exist: entities, operations, invariants, audiences.
- Very specific: line 83
Verify each concept entry has name, nodes, contributors, evidence.
- Very specific: line 84
Verify every nodes entry references a real node ID — sample-check 5 random entries via jq against lineage/{repo}/nodes.jsonl.
- Very specific: line 100
Maintainer-curated preservation: If a concept entry in the existing concepts.yaml is flagged maintainer_curated: true, the subagent …
- Very specific: line 102
Reducer doesn't fix sidecar quality: If a sidecar's concepts block is sparse or unclear, concept-merger notes the contribution but does not …
- Very specific: line 103
Skip auto-write on validation failure: If the subagent's output fails schema validation, the file gets written to …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Concept catalog (DOC-164 slice 6+)
Build or refresh the cross-sidecar concept catalog at lineage/{repo}/concepts.yaml. The catalog clusters every per-node sidecar's concepts block by semantic equivalence, anchors names against the canonical vocabulary in documentation/docs/main-concepts.md, and surfaces canonicalisation candidates for the maintainer to decide on.
This skill is the second reducer in the agentic-code-ontology layer (per adrs/drafts/agentic-code-ontology.md rev 2). The first per-node enrichment slice was /enrich (slice 5). /concepts consumes the sidecars /enrich produced.
Argument forms
| Form | Behaviour |
/concepts [<repo>] | Default. Run concept-merger in incremental mode (per playbooks/reducer-incremental-mode.md) against lineage/{repo}/understanding/ (default repo: odd-platform). Refreshes lineage/{repo}/concepts.yaml by appending+annotating only the sidecars whose node_id is not yet in the prior catalog's processed_node_ids. Preserves any concept entries flagged maintainer_curated: true from a prior version. |
/concepts --full [<repo>] | Forces FULL mode — re-reads every sidecar and regenerates the catalog from scratch. Use when prior catalog is corrupt, prompt_version bumped, or after a schema change. |
/concepts --show [<repo>] | Read-only. Print the existing catalog's summary (concept counts per category, top-N concepts by node-count, canonicalisation candidates list). No subagent invocation; no writes. |
/concepts --diff [<repo>] | Read-only. Compare the existing concepts.yaml to a freshly-generated one (in a temp file) and surface the diff. Useful for previewing what a refresh would change before committing it. |
Incremental input resolution
Before spawning the subagent in default (incremental) mode, the skill computes:
PROCESSED_NODE_IDS— read from priorconcepts.yaml's frontmatterprocessed_node_ids:field. If the field is missing (pre-v0.2 catalog), fall back to--fullfor this run.NEW_SIDECAR_FILES—Glob lineage/{repo}/understanding/*.mdminus the set whose YAML frontmatternode_id:is inPROCESSED_NODE_IDS. Empty set → report "Nothing to refresh (no new sidecars)" and exit without invoking the subagent.PRIOR_HEAD— one line per concept from priorconcepts.yaml, derived viagrep -E '^ - name:'+ per-entrycontributing_fileslength count. Use the compact-head shape fromplaybooks/reducer-incremental-mode.md.CURATED_ENTRIES— verbatim YAML of every concept entry withmaintainer_curated: true, extracted by parsing the prior catalog.
These four values + MODE: incremental get passed to the subagent in place of the legacy EXISTING_CATALOG block.
Prerequisites
lineage/{repo}/understanding/{slug}.mdsidecars exist (i.e./enrichhas been run at least once).documentation/docs/main-concepts.mdis reachable (either local at../documentation/docs/main-concepts.mdor live athttps://docs.opendatadiscovery.org/main-concepts). The skill prefers the local file (faster, no rate limits); WebFetches the live URL only as a fallback.- The
concept-mergersubagent at.claude/agents/concept-merger.mdis loaded.
Protocol
1. Orient
Read these (skip if already loaded this session):
CLAUDE.md— quality baradrs/drafts/agentic-code-ontology.md— the layered ADR + reducer pattern.claude/agents/concept-merger.md— the subagent's system prompt- The active pillar's
cornerstones.md(currentlypillars/documentation/cornerstones.md) — Cornerstone 2 is the canonical-vocabulary discipline this skill upholds
2. Resolve inputs
- Sidecar set:
Globlineage/{repo}/understanding/*.md. Confirm at least one sidecar exists; otherwise report "no sidecars to merge — run/enrichfirst" and exit. - Existing catalog (if any):
lineage/{repo}/concepts.yaml. If present, capture itsmaintainer_curated-flagged entries to pass to the subagent for preservation. - Canonical-vocab source: prefer
../documentation/docs/main-concepts.md(local sibling repo). Fallback: WebFetchhttps://docs.opendatadiscovery.org/main-concepts. Pass the path/content to the subagent. - Substrate state: read
lineage/{repo}/manifest.yaml'slast_scan_commitso the produced catalog can recordgenerated_at_commit.
3. Spawn the concept-merger subagent
Invoke via the Agent tool with subagent_type: concept-merger (after .claude/agents/concept-merger.md is loaded; in this session general-purpose is the fallback). Construct the prompt as:
REPO: <repo>
WORKSPACE_ROOT_ABS: <absolute>
SIDECAR_DIR_ABS: /home/.../lineage/{repo}/understanding/
DOC_MAIN_CONCEPTS_PATH: <absolute path to ../documentation/docs/main-concepts.md, or the live URL if only the URL is reachable>
SUBSTRATE_LAST_SCAN_COMMIT: <from manifest.yaml>
EXISTING_CATALOG: <verbatim content of lineage/{repo}/concepts.yaml if present, else "(none)">
SIDECAR_FILES: <newline-separated list of sidecar paths>
SIDECAR_COUNT: <N>
TARGET_PATH: lineage/{repo}/concepts.yamlThe subagent's tool surface is Read, Glob, Grep, Write per its frontmatter. It writes the catalog and replies with Wrote: ... + Catalog: ....
4. Validate the resulting catalog
After the subagent reports completion:
- Confirm
lineage/{repo}/concepts.yamlexists. - Parse it as YAML (Bash
python -c "import yaml; yaml.safe_load(open('...'))"or skip if no Python available). - Verify the four top-level lists exist:
entities,operations,invariants,audiences. Empty lists are fine; missing keys are an error. - Verify each concept entry has
name,nodes,contributors,evidence. Missing fields = log warning + report. - Verify every
nodesentry references a real node ID — sample-check 5 random entries viajqagainstlineage/{repo}/nodes.jsonl. If a sample finds a fabricated node ID, that's a CRITICAL FAIL — the catalog is unreliable; report + ask the maintainer how to proceed.
5. Report
Concise output:
- Catalog path
- Counts:
<E> entities, <O> operations, <I> invariants, <A> audiences = <N> concepts - Cross-axis concepts: count concepts whose
axes_presenthas ≥2 entries (these are the most valuable — they prove the cross-axis join works) - Top-3 concepts by node-count (which concepts have the most contributing sidecars)
- Canonicalisation candidates count + brief list (one line each)
- Suggested next:
/find-implicit-adrs(slice 8 — adr-archaeologist) once the catalog is reviewed; or/enrich --batch <axis>to grow the sidecar set if cross-axis coverage is weak.
Rules
- Live-URL-only doc rule applies here too. The subagent's prompt requires that when it cites
documentation/docs/main-concepts.md, the citation is from a file Read in this session — not pretraining recall. The skill provides the path/content; the subagent does not invent canonical-vocabulary entries from memory. - Maintainer-curated preservation. If a concept entry in the existing
concepts.yamlis flaggedmaintainer_curated: true, the subagent preserves itsname,description, andnotesverbatim. Thenodes,contributors, andevidencefields may update if new sidecars contribute (they're auto-derived); the maintainer's prose stays. - Don't dedup canonicalisation candidates. Even if a candidate appears similar to an existing entry, surface both. The maintainer is the only judge of canonical-vocabulary changes.
- Reducer doesn't fix sidecar quality. If a sidecar's
conceptsblock is sparse or unclear,concept-mergernotes the contribution but does not "fill in" missing concepts. Sparse sidecars surface as a quality finding for/enrich --node <id>to refresh, not for the reducer to paper over. - Skip auto-write on validation failure. If the subagent's output fails schema validation, the file gets written to
lineage/{repo}/.concepts-staged.yamlinstead and the maintainer reviews before promoting toconcepts.yaml. (Slice-6 MVP: simpler — write directly and report failure.)
Failure modes to surface (not auto-fix)
- Subagent claims a concept appears in node X but X isn't in
nodes.jsonl→ catalog is rejected; maintainer iterates the prompt - Canonical-vocabulary fetch failed (local file missing, WebFetch returned non-200) → catalog uses
canonical_in_docs: unknownfor entries that can't be classified; maintainer re-runs after fixing - More than 30% of entries land in
canonicalisation_candidates→ either the canonical vocab is genuinely undersized (real signal worth maintainer review) OR the sidecars are noisy (refresh/enrichmay help). Surface to maintainer rather than silently emit a low-quality catalog.
Cross-references
- Subagent:
.claude/agents/concept-merger.md - Inputs:
lineage/{repo}/understanding/*.md(per-node sidecars from/enrich) - Output:
lineage/{repo}/concepts.yaml - Canonical-vocab source:
../documentation/docs/main-concepts.md(local) orhttps://docs.opendatadiscovery.org/main-concepts(live) - ADR:
adrs/drafts/agentic-code-ontology.mdrev 2 — agent set table, slice progression - Cornerstone enforced: documentation pillar Cornerstone 2 (vocabulary anchored in
main-concepts.md)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

