| name | okforge-query |
| description | Read-only browser for any Open Knowledge Format (OKF) knowledge bundle — a tree of markdown concept files. Use it whenever the user wants to browse, explore, map, or navigate a knowledge bundle; asks "what concepts are in <bundle>", "what links to X" / "what does X link to", "show me the OKF graph", "find orphan or broken concepts", or "summarize recent changes"; or points at a directory of markdown docs with frontmatter and `index.md` / `log.md` files — even when they never say "OKF". Prefer this skill for any read-only question about such a bundle's structure, concepts, links, or history. It never edits the bundle. |
Browse an OKF knowledge bundle
OKF is a plain-markdown knowledge format: a bundle is a directory tree, a
concept is any non-reserved .md file, and its Concept ID is the
bundle-relative path minus .md (tables/users.md → tables/users). index.md
and log.md are reserved at every level (listing and change-history). Concepts
cross-link with markdown links, forming a directed, untyped graph.
This skill is strictly read-only: never create, edit, move, or delete bundle
files. Identify every concept by its Concept ID. The format details — link
resolution, frontmatter, reserved files, hygiene definitions — live in
references/okf-rules.md; consult it whenever a link does
not resolve as expected or you are classifying files or reporting hygiene.
Tools: deterministic script first, built-ins as fallback
The graph-heavy queries (neighbors, orphans, broken links, shortest path, hub
ranking, the overview) are answered deterministically by:
npx okforge graph <op> --bundle <bundle-root>
Prefer the script for anything graph-wide (overview, orphans, broken, neighbors,
path) — it parses every doc once and resolves both link forms correctly. If npx okforge graph is unavailable (older okforge, offline, non-Node repo), fall back to
built-in tools: Glob to enumerate, Grep to find links/fields, Read for
content. Always grep before reading whole files, and lean on index.md for
progressive disclosure rather than reading everything.
Locate the bundle root
If the user gives a path, use it. Otherwise find the directory holding a root
index.md (ideally with okf_version: "0.1" in frontmatter): Glob **/index.md,
then prefer the shallowest, or grep for okf_version. A common location is .okf/ (or okf/).
Operations
- Overview / map —
graph overview. Report concept count, per-group counts,
the top hub concepts (most inbound), and orphan/broken counts. Fallback: read the
root index.md, count concepts with Glob, descend into nested index.md only
as needed.
- Open concept —
graph concept <id>. Show a one-line frontmatter summary
(type · title · description · tags), then the body (Read the file), then its
outbound and inbound links. Fallback: Read the file for body + outbound;
Grep the bundle for links resolving to it for inbound.
- Neighbors —
graph neighbors <id> [--hops N] (default 1 hop = inbound +
outbound). Grouped by distance.
- Search — match a term/tag across frontmatter and/or bodies. Use
Grep
(-i, output_mode: files_with_matches first, then targeted reads). Return
Concept ID + title + one-line description per hit.
- Filter — list concepts whose
type: or tags: match. Grep for
^type: / tags:.*<value> across the bundle, then summarize.
- Hygiene —
graph orphans and graph broken. Orphans = concepts with no
inbound link from another concept (an index listing does not count); broken =
in-bundle .md targets that do not exist. Broken links are valid in OKF — only
report them, never treat them as errors.
- Recent changes — Read
log.md files (root and nested). Respect newest-first
order and ISO ## YYYY-MM-DD headings; summarize the most recent entries.
- Path (optional) —
graph path <from> <to> for the shortest directed link
path between two concepts.
Output conventions
- Identify every concept by its Concept ID, with title + one-line description
where it aids reading.
- Keep listings compact; group by directory or
type.
- Clearly separate reserved files (
index.md, log.md) from concepts.
- Never modify the bundle, and never fabricate frontmatter, links, or counts — if
the script is unavailable and a query is expensive, say what you sampled.
