okf-frontmatter

---

Table of contents

• What it is
• Install
  • Claude Code
  • Codex
  • Any other agent
• Background
• Does it actually help? I measured it.
• CLI usage
• Commands
• Frontmatter schema
• Layout
• License

---

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: