okf-frontmatter

Name: okf-frontmatter
Author: longsizhuo

bylongsizhuo· 5 skills

Stars

Forks

How to install okf-frontmatter?

longsizhuo/okf-frontmatter

$npx -y skills add longsizhuo/okf-frontmatter --skill okf-frontmatter

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/longsizhuo/okf-frontmatter" --skill "longsizhuo/okf-frontmatter"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/longsizhuo/okf-frontmatter" that are relevant to the current task. Run `npx skills add "https://github.com/longsizhuo/okf-frontmatter"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	<div align="center">
2
3	# okf-frontmatter
4
5	Keep a repo's Markdown docs under the Open Knowledge Format — and find the right doc/schema fast.
6
7	[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
8	·  pure-Python stdlib  ·  portable agent skill — Claude Code / Codex / any
9
10	</div>
11
12	---
13
14	## Table of contents
15
16	- [What it is](#what-it-is)
17	- [Install](#install)
18	- [Claude Code](#claude-code)
19	- [Codex](#codex)
20	- [Any other agent](#any-other-agent)
21	- [Background](#background)
22	- [Does it actually help? I measured it.](#does-it-actually-help-i-measured-it)
23	- [CLI usage](#cli-usage)
24	- [Commands](#commands)
25	- [Frontmatter schema](#frontmatter-schema)
26	- [Layout](#layout)
27	- [License](#license)
28
29	---
30
31	## What it is
32
33	okf-frontmatter is a portable agent skill: just a `SKILL.md` plus a small script, so any
34	agent that loads skills can pick it up (or you can run it as a plain CLI). It does two things.
35
36	Keeps docs in OKF shape. Each doc opens with a little YAML frontmatter — `type`, `title`,
37	`tags`, `intent`, `schema_source`, `documents`. The parts that are code — models, config
38	keys, endpoints — get a `schema_source: file.py:Symbol` pointer instead of being retyped into
39	prose. So docs stop drifting from the code and stop ballooning into thousand-line walls.
40
41	Finds the right doc fast. Hand `find_docs.py` a symbol, an endpoint, a config key, or just
42	a keyword, and it ranks the doc that actually owns the topic (by frontmatter intent). `schema
43	<doc>` goes one step further and resolves those pointers straight to the code, so the agent
44	reads the authoritative definition without opening the prose at all.
45
46	One thing I want to be straight about: this is grep-first. The script isn't a replacement
47	for grep — it's what you reach for when grep is ambiguous (hits scattered across files, a
48	synonym mismatch, or nothing at all). On a clean literal hit, plain grep is already the best
49	move, and the skill tells the agent exactly that. The
50	[full strategy is here](references/lookup-strategy.md).
51
52	---
53
54	## Install
55
56	No dependencies — pure Python stdlib. It'll use PyYAML if you happen to have it, otherwise a
57	tiny built-in frontmatter parser kicks in. Pick the install that matches your agent.
58
59	### Claude Code
60
61	The repo ships a `.claude-plugin/plugin.json` manifest, so it loads as a first-class plugin (not
62	just a loose skill). Clone into the skills dir; it auto-loads next session as
63	`okf-frontmatter@skills-dir`:
64
65	```bash
66	git clone https://github.com/longsizhuo/okf-frontmatter.git ~/.claude/skills/okf-frontmatter
67	# then in a session: /reload-plugins (or restart Claude Code)
68	```
69
70	### Codex
71
72	Codex skills are plain folders under `$CODEX_HOME/skills/`; the same `SKILL.md` works as-is
73	(no manifest needed, Codex ignores `.claude-plugin/`):
74
75	```bash
76	git clone https://github.com/longsizhuo/okf-frontmatter.git ~/.codex/skills/okf-frontmatter
77	# picked up on the next Codex session
78	```
79
80	### Any other agent
81
82	Works on Cursor, Cline, Gemini CLI, OpenClaw, and the rest — drop it wherever that agent looks
83	for skills, or just clone it anywhere and call the script directly:
84
85	```bash
86	git clone https://github.com/longsizhuo/okf-frontmatter.git
87	ln -s "$(pwd)/okf-frontmatter" ~/.claude/skills/okf-frontmatter # or wherever your agent looks
88	```
89
90	Once it's loaded, the agent follows the grep-first / script-fallback flow from `SKILL.md`. Don't
91	use a skill runner? Just call `scripts/run.sh` (or `find_docs.py`) from anywhere — it's the same
92	tool. See [CLI usage](#cli-usage) below.
93
94	---
95
96	## Background
97
98	I let my coding agents maintain the docs — wikis, design notes, postmortems. That's lovely for
99	the docs and rough on the agent: a repo slowly grows to dozens, sometimes hundreds, of markdown
100	files, and every "where's the doc about X?" turns into grepping thousands of lines and a few
101	rounds of `find`. Slow, and a quiet token sink. I looked at standing up RAG for it and it felt
102	like a cannon to swat a fly. 🦟
103
104	Then a colleague pointed me at Google's
105	[Open Knowledge Format (OKF)](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/):
106	give each doc a small structured frontmatter block as its single source of truth, and link the
107	code-ish details to the code instead of copying them into prose. The thing that clicked for me
108	was that the same frontmatter makes a great index — so I built this.
109
110	---
111
112	## Does it actually help? I measured it.
113
114	Short version: yes for structured or ambiguous lookups, a wash for clean keyword hits — and
115	I'd rather show you the wash than bury it.
116
117	The setup: 8 fresh agents, no shared context, the same LLM on both sides (Claude Sonnet 4.6),
118	read-only, each pinned to one checkout of [openInvest](https://github.com/longsizhuo/openInvest).
119	Same questions, two states of the repo:
120
121	- baseline — plain `main`: monolithic docs, no frontmatter, no skill. grep + read only.
122	- current — the same docs with OKF frontmatter, skill available.

6 picks

Type

Run `npx skills use "https://github.com/longsizhuo/okf-frontmatter" --skill "longsizhuo/okf-frontmatter"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/longsizhuo/okf-frontmatter" that are relevant to the current task. Run `npx skills add "https://github.com/longsizhuo/okf-frontmatter"` and select the relevant skills, then follow their instructions.

okf-frontmatter

How to install okf-frontmatter?

Related

okf-frontmatter

How to install okf-frontmatter?

Related