okf-bundles
CLAUDE.md2 starsChanged 3 months agoMITView on GitHub
This repo is a collection of knowledge bundles in the Open Knowledge Format (OKF v0.2). Each bundle is one self-contained folder at the repo root, readable by any AI agent with no SDK. The format is markdown files with YAML frontmatter; the spec is at GoogleCloudPlatform/knowledge-catalog. Authoring and maintenance run through the OKF skill installed at .claude/skills/okf/. It is the authoritative tooling; this file is the repo-specific overlay on top of it. Reach for the skill, do not reinvent its…
The file
We split this CLAUDE.md into the rules it gives an agent
6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 35
Add a log.md Creation entry dated today (## YYYY-MM-DD).
- Distinctive: line 36
Add a row to the Bundles table in README.md.
- Distinctive: line 41
Every bundle must stay conformant at all times, not just at creation.
- Very specific: line 48
No orphans: Every concept should link to, or be linked from, at least one other concept.
- Distinctive: line 82
Prefer structural markdown (headings, lists, tables, fenced code) over freeform prose.
- Distinctive: line 93
Never em or en dashes. Write natural prose with periods, commas, colons, parentheses.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md 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
OKF Bundles Repo Conventions
This repo is a collection of knowledge bundles in the Open Knowledge Format (OKF v0.2). Each bundle is one self-contained folder at the repo root, readable by any AI agent with no SDK. The format is markdown files with YAML frontmatter; the spec is at GoogleCloudPlatform/knowledge-catalog.
Tooling: the /okf skill
Authoring and maintenance run through the OKF skill installed at .claude/skills/okf/. It is the authoritative tooling; this file is the repo-specific overlay on top of it. Reach for the skill, do not reinvent its steps by hand.
- Commands. Invoke
/okf <command>:init(new bundle),add(one concept),attest(a computation an agent may run but not write),migrate(v0.1 to v0.2),enrichandexport(turn a source, a docs site, or a URL into concepts),link,index,log,validate,health,retrieve,consume. Each is detailed in.claude/skills/okf/commands.md. - Deep references. The normative spec is
.claude/skills/okf/spec.md; copy-paste starting points are.claude/skills/okf/templates.md. When this file and the spec disagree on anything beyond repo layout, the spec wins. - Implicit mode (the discipline this repo most needs). Whenever you touch a concept, keep the bundle conformant in the same change: refresh that concept's
generated(bothbyandat, since the actor may differ from whoever wrote it last), append alog.mdentry, regenerate the affectedindex.md(both the area listing and the root), and add the cross-links the new relationships imply. If you materially change a concept that carried averifiedevent, drop that event rather than letting it vouch for text nobody checked. Validate after each slice, not just at the end. This bookkeeping is where bundles silently rot. - Guard. OKF is for knowledge an agent reads. Do not convert human-only prose (a README, a blog post, a design doc) into a bundle; ask first when an artifact's audience is unclear.
Layout
bundles/
<bundle>/
index.md root, declares okf_version: "0.2" (the only index.md with frontmatter)
overview.md optional entry concept that orients the reader
log.md dated change history, newest first
<domain>/ concepts grouped by domain, not by file type
index.md directory listing, no frontmatter
<concept>.md one concept, frontmatter with a non-empty `type`The one rule
A bundle is conformant when every concept document carries YAML frontmatter with a non-empty type. That is the only hard requirement; everything else is recommended structure a consumer must tolerate. Nothing v0.2 added (sources, generated, verified, status, stale_after, attested computations) can make a bundle non-conformant, but this repo holds itself to the producer gate: okf-validate --strict on a bundle that declares "0.2" must pass.
Adding a bundle
/okf initunderbundles/<bundle>/: a rootindex.mddeclaringokf_version: "0.2"./okf addone concept at a time, grouped by domain. Reserved filenames areindex.md(listings) andlog.md(history). Never name a concept either, and never put aREADME.mdinside a bundle: the checker treats any other.mdas a concept and will fail it for missingtype.- Add a
log.mdCreation entry dated today (## YYYY-MM-DD). - Add a row to the Bundles table in
README.md. - Validate before committing.
/okf validate bundles/<bundle>checks one bundle;node scripts/check-bundles.mjsgates the whole repo (it wraps the same checker over every bundle and warns on a missing README row).scripts/okf-validate.mjsis a vendored copy of the skill'sokf-validate.mjs, kept in sync so the repo gate still runs where the skill is not installed.
Staying conformant
Every bundle must stay conformant at all times, not just at creation. Before committing any change that touches a bundle, run the gate and fix what it flags:
node scripts/check-bundles.mjsvalidates every bundle in the repo;node scripts/okf-validate.mjs bundles/<bundle>checks one, and--strictadds the producer gate (connectivity plus, on a bundle declaring"0.2", leftovertimestampor# Citations, asourcesentry with noresource, ageneratedwith noby, an out-of-rangestatus). The gate must report 0 errors. Treat its warnings (a non-ISOlog.mddate, a missing README row, a link whose target file is absent, an actor that is notproducer/version,human:idorprocess:id) as fix-on-sight, not noise.
The checker verifies the hard rule (every concept has a type), the link targets, and the v0.2 provenance shapes. It does not check that the knowledge is right or that the bundle covers its source. Hold the graph expectations too, which the default run reports as warnings and --strict gates:
- Link concepts to concepts, never to an
index.mdlisting or an in-page#anchor. Anindex.mdis navigation, not a concept node, so a concept that links to one is a dangling edge to a graph consumer even though the file exists and the checker stays silent. Point at the section's landing concept or a representative concept instead. Theindex.mdfiles themselves may link to otherindex.mdfiles: that is navigation, and it is fine. - No orphans. Every concept should link to, or be linked from, at least one other concept. A concept with no edges is invisible to graph navigation; give it a
# Relatedcross-link or weave one into its prose. - Exception for bulk corpora. A bundle that is a bulk, index-navigable corpus (one concept per record, reached through an
index.mdtree by id, date, or norm, likebgh-rechtsprechung) is exempt from the no-orphans expectation: its leaf records are legitimately reached through the index tree, and its overview may point to the index roots. This exemption is for corpora only. A curated bundle (concepts, techniques, norms, docs, one concept per idea) must be fully graph-clean: concept-to-concept links and no orphans. - Quick checks:
grep -rn '](/[^)]*index\.md)' bundles/<bundle> --include='*.md'finds concept-to-index links (ignore hits insideindex.mdfiles); a concept with no outbound](/...md)link and no inbound link is an orphan to wire up.
This is the same discipline as Implicit mode: when you touch a concept, leave the bundle both validator-clean and graph-clean in the same change.
Concept format
---
type: <descriptive, self-explanatory kind>
title: <human-readable name>
description: <one sentence>
resource: <canonical URL for the underlying asset, if any>
tags: [<tag>, <tag>]
generated:
by: <producer/version | human:id | process:id>
at: <YYYY-MM-DDThh:mm:ssZ>
sources:
- resource: <url or bundle path>
title: <human-readable label>
---
# <Section>
...Rules:
typeis the only required field. Drop any recommended field you cannot stand behind rather than guessing; add domain-specific keys freely.- Provenance is v0.2's point, so fill it honestly.
generated.byis the actor that actually wrote the content:<producer>/<version>for an agent or tool,process:<id>for automation (the BGH ingest scripts),human:<id>only for hand-authored text. Content this repo's agents write isclaude-code/<model>where the model is known andclaude-code/unrecordedwhere it is not, neverhuman:, because a consumer computes its trust tier off thehuman:prefix. - Never backfill
verified. It records a confirmation that actually happened, and it is the single field distinguishing reviewed knowledge from generated knowledge. Omit it until a real human or process confirms the concept. sourcesreplaces the old# Citationsbody section: one entry per source withresourceandtitle, plus anidfor any the body footnotes (...text.[^ga4-schema]).status(draft|stable|deprecated) andstale_after(absoluteYYYY-MM-DD) go only on concepts where they are real, never blanket-applied.- Prefer structural markdown (headings, lists, tables, fenced code) over freeform prose.
- Link with relative targets (
invest.mdfor a sibling,../techniques/invest.mdacross directories), and put the relationship in the prose around the link, not in the link itself. The spec recommends the bundle-absolute form (/techniques/invest.md), but GitHub resolves it against the repository root and serves a 404, so it breaks where humans read these bundles. Theokf,hello-okfandrezeptebundles are converted; the older bundles still carry absolute links pending conversion. After moving a file, run the validator, which reports the relative links the move broke. - External sources you mirror live under
references/<slug>.mdwithtype: Reference, the live URL inresource, and a datedgenerated. Absorb the substance into the body so the concept stands alone offline; summarize and cite, do not paste a third party's full text. - Where case law shapes the rule, not just the statute, add a
# Rechtsprechungsection with the leading decisions: court, date, and docket number (BGH, Urteil vom 06.05.2021 - IX ZR 72/20), each summarized in a sentence. Verify the docket number against the source; never invent one. The statute is the commodity, the case law is the value. - A leading decision may also be its own concept with
type: Gerichtsentscheidung(under arechtsprechung/folder), carrying court, date, docket, official Fundstelle (e.g.BGHZ 230, 28), the affected norms as cross-links, and either the verbatim amtlicher Leitsatz or a clearly-labelled Kernaussage. Norm concepts then link to it. Prefer the official source asresource:bundesgerichtshof.de(or the relevant court / rechtsprechung-im-internet.de / Curia) and the amtliche Sammlung; dejure.org and openJur are finding aids, useful for the norm-to-decision index and for non-BGH courts. - Court decisions and their amtlich verfasste Leitsätze are amtliche Werke and gemeinfrei (§ 5 UrhG), so their text may be reproduced. Commentary literature (Beck, Wolters Kluwer, juris and similar paid or AI-gated literature) is copyrighted: do not mirror it; name it at most as a pointer. A full-text corpus of all judgments is a search/RAG artifact, not this bundle, which stays curated and norm-linked.
- Dates and timestamps are ISO 8601.
Style
- Lead each section with the substance the reader needs, then any background.
- Never em or en dashes. Write natural prose with periods, commas, colons, parentheses.
Distribution
OKF has no standard installer yet, so this repo is something agents clone or get pointed at, not npx-installed. Each bundle is a plain directory you can also tar or drop into another repo.
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.

