okf-reader

OKF Bundle Reader Guidance Skill

Procedural rules for reading and traversing any OKF bundle efficiently, no matter how its producer organized it. Following them reduces token consumption, speeds execution, and avoids recursive directory walks.

OKF is deliberately flexible: the directory layout, the concept type values, and whether concepts cross-link are all producer-defined. So these rules key off the spec's universal structures — frontmatter type, index.md, markdown links, and resource — and never off any one source's conventions (there is no required tables/ folder, no fixed type vocabulary, no guaranteed cross-links).

When to Use

Load this skill whenever you are tasked with reading, parsing, querying, or analyzing an existing OKF bundle.

Instructions for Agents

1. Index-first discovery (descend nested indexes)

• Rule: NEVER recursively read or load every markdown file at startup.
• Protocol:
  1. Read the bundle-root index.md first if present — it is the directory listing.
  2. Follow its links to map the available concepts. The index may be flat (every concept — including container/directory concepts — listed at the root as peers) or hierarchical (subdirectories carry their own index.md or sub-index concept). Descend any nested indexes for progressive disclosure instead of walking the tree.
  3. If there is no index.md, discover concepts cheaply — a shallow listing or a *.md glob — without reading bodies yet.
  4. Sanity-check it is an OKF bundle: concept files have YAML frontmatter with a type; the root index.md may declare okf_version.

2. Route directly to a concept (layout is producer-defined)

• Rule: Do not assume a fixed directory layout. There is no required tables/ (or any other) folder — producers organize concepts however suits the domain (SQL connectors group under tables/; filesystem/git bundles mirror the source tree; others differ).
• Protocol:
  • Resolve a concept's location from the index.md links — use each link target verbatim; do not guess, strip, or rewrite paths (filenames and separators are producer-defined).
  • When the layout mirrors a source path, the concept file is usually that path; otherwise trust the index links or the directory tree.
  • Open only the one file you need — don't list or read its siblings.