okf-frontmatter
Keep a repo's Markdown docs under the Open Knowledge Format — and find the right doc/schema fast.
· pure-Python stdlib · portable agent skill — Claude Code / Codex / any
Table of contents
What it is
okf-frontmatter is a portable agent skill: just a SKILL.md plus a small script, so any
agent that loads skills can pick it up (or you can run it as a plain CLI). It does two things.
Keeps docs in OKF shape. Each doc opens with a little YAML frontmatter — type, title,
tags, intent, schema_source, documents. The parts that are code — models, config
keys, endpoints — get a schema_source: file.py:Symbol pointer instead of being retyped into
prose. So docs stop drifting from the code and stop ballooning into thousand-line walls.
Finds the right doc fast. Hand find_docs.py a symbol, an endpoint, a config key, or just
a keyword, and it ranks the doc that actually owns the topic (by frontmatter intent). schema <doc> goes one step further and resolves those pointers straight to the code, so the agent
reads the authoritative definition without opening the prose at all.
One thing I want to be straight about: this is grep-first. The script isn't a replacement
for grep — it's what you reach for when grep is ambiguous (hits scattered across files, a
synonym mismatch, or nothing at all). On a clean literal hit, plain grep is already the best
move, and the skill tells the agent exactly that. The
full strategy is here.
Install
No dependencies — pure Python stdlib. It'll use PyYAML if you happen to have it, otherwise a
tiny built-in frontmatter parser kicks in. Pick the install that matches your agent.
Claude Code
The repo ships a .claude-plugin/plugin.json manifest, so it loads as a first-class plugin (not
just a loose skill). Clone into the skills dir; it auto-loads next session as
okf-frontmatter@skills-dir:
git clone https://github.com/longsizhuo/okf-frontmatter.git ~/.claude/skills/okf-frontmatter
# then in a session: /reload-plugins (or restart Claude Code)
Codex
Codex skills are plain folders under $CODEX_HOME/skills/; the same SKILL.md works as-is
(no manifest needed, Codex ignores .claude-plugin/):
git clone https://github.com/longsizhuo/okf-frontmatter.git ~/.codex/skills/okf-frontmatter
# picked up on the next Codex session
Any other agent
Works on Cursor, Cline, Gemini CLI, OpenClaw, and the rest — drop it wherever that agent looks
for skills, or just clone it anywhere and call the script directly:
git clone https://github.com/longsizhuo/okf-frontmatter.git
ln -s "$(pwd)/okf-frontmatter" ~/.claude/skills/okf-frontmatter # or wherever your agent looks
Once it's loaded, the agent follows the grep-first / script-fallback flow from SKILL.md. Don't
use a skill runner? Just call scripts/run.sh (or find_docs.py) from anywhere — it's the same
tool. See CLI usage below.
Background
I let my coding agents maintain the docs — wikis, design notes, postmortems. That's lovely for
the docs and rough on the agent: a repo slowly grows to dozens, sometimes hundreds, of markdown
files, and every "where's the doc about X?" turns into grepping thousands of lines and a few
rounds of find. Slow, and a quiet token sink. I looked at standing up RAG for it and it felt
like a cannon to swat a fly. 🦟
Then a colleague pointed me at Google's
Open Knowledge Format (OKF):
give each doc a small structured frontmatter block as its single source of truth, and link the
code-ish details to the code instead of copying them into prose. The thing that clicked for me
was that the same frontmatter makes a great index — so I built this.
Does it actually help? I measured it.
Short version: yes for structured or ambiguous lookups, a wash for clean keyword hits — and
I'd rather show you the wash than bury it.
The setup: 8 fresh agents, no shared context, the same LLM on both sides (Claude Sonnet 4.6),
read-only, each pinned to one checkout of openInvest.
Same questions, two states of the repo: