Reducing LLM token consumption by organising skills with Google’s OKF

Turn scattered architecture notes into OKF (open knowledge format) skills. Claude loads on demand and gets a browsable docs site for free.

In this article, I will share how I have organised my Claude code skills to reduce my token consumption and turn these skills into a valuable knowledge-sharing format. So let’s start.

Every time you open a fresh Claude session on a real codebase, the same thing happens: you re-explain your project. Claude greps around, opens a dozen files to rebuild the context it had yesterday, and you pay for every one of those tokens. I create .md-style documents of everything I do, including research, fixes, future projections, tradeoffs, and product decisions, among other things.

Html preview of skills. Check this live here.

Typically, when we start working on a feature/fix, we humans tend first to get context around that feature. The same thing happens to agents. So I like Borris Tane's style of augmented programming. Here is the link for full article. Obviously, for small fixes we might dont need all stages, but even for that we should at least plan it.

After we are done with the fix/feature. I made 1–2 .md documents for it. Context (research) of the feature and what implementation we have added to it. Also, I used to add these documents under .claude/skills folder so I can load them into Claude code skills anytime with just /command. But after some time, these documents will be scattered, and you will probably forget what you have saved and where you have saved them. That's exactly what our OKF style format helps us.

A normal knowledge skills under .claude folder.

Google’s OKF is just:

• a directory of markdown files
• each with a little YAML frontmatter (one required field: type)
• cross-linked to each other with normal markdown links

That’s it. Simple and easy to maintain.

A folder of markdown notes already is an OKF bundle. Adopting OKF wasn’t a rewrite: it was adding two frontmatter fields and a few links. Check out this sample repository, which we will walk through below as well.

The idea: skills as OKF bundles

Claude (and Claude Code) can load skills. Folders of markdown that the model reads on demand. The trick is structuring each skill as an OKF bundle so the model loads little:

• An index file describes the skills and routes for children
• Reference files each hold one concept
• Tags tell the model which child matches the task
• cross-links let it walk to related knowledge in other folders

Instead of “grep the repo and read 12 files,” the flow becomes “read one tiny index, follow one tag, read one reference.” That’s the token saving, you pay for a small index plus a single doc, not a repo-wide search every session.

Anatomy: indexes, references, tags

An index (SKILL.md) the front door. It says what the skill is and lists its children with tags:

---
name: pos-flow
description: Architecture reference for the POS checkout flow.
type: index
title: POS flow
tags: [pos, checkout, catalog, invoice, cart]
timestamp: 2026-06-18T00:00:00Z
---

| Topic | Doc | Tags |
|-------|-----|------|
| Product catalog & lookup | catalog.md | catalog, product, sku |
| Checkout — cart → invoice | checkout.md | checkout, invoice, total |

A reference to one concept, tagged, optionally pointing at the real source file:

---
type: reference
title: POS — checkout (cart → invoice)
tags: [pos, checkout, invoice, total]
resource: src/pos.ts
timestamp: 2026-06-18T00:00:00Z
---

The tags are the search surface. When you ask Claude about "the checkout total," it matches that against tags and opens exactly one file.

Cross-links: the part that fixes deep nesting

OKF’s cross-links solve this at the content layer. The reports depend on the checkout invoice shape, so I link them both ways:

<!-- in reports/sales-by-product.md -->
## See also
- [../pos-flow/checkout.md](../pos-flow/checkout.md) — where the Invoice shape is built

Now Claude doesn’t need me to name a nested skill. It reads an index, matches a tag, and walks the links across folders. The graph is the search index; the model is the search engine.

See the .claude/skills folder:

.claude/skills/
├── pos-flow/
│   ├── SKILL.md          # index → catalog.md, checkout.md
│   ├── catalog.md        # reference
│   └── checkout.md       # reference
├── reports/
│   ├── SKILL.md          # index → sales-by-product.md, sales-by-invoice.md
│   ├── sales-by-invoice.md
│   └── sales-by-product.md
└── skill-authoring/
    ├── SKILL.md          # index → the 5 docs below
    ├── frontmatter-spec.md
    ├── structure.md
    ├── cross-linking.md
    ├── authoring-workflow.md
    └── checklist.md

Bonus: a browsable HTML site

I wrote a small 120 lines of vide coded script that turns these markdown files into HTML. The output lives in the /docs folder. The catch is that this can go stale the moment you edit something under /skills. I close that gap with a committed PostToolUsehook .claude/settings.json runs a small script whenever a skill file is edited:

# .claude/hooks/rebuild-site.sh (abridged)
fp="$(… read file_path from the hook's stdin JSON …)"
case "$fp" in "$SRC"/*) ;; *) exit 0 ;; esac   # only on skill edits
node "$ROOT/tools/build-html.mjs"

Bonus: a skill that writes skills

One more thing worth doing. Write a skill whose job is to author other skills. It sounds circular, but it keeps you honest. Every time you edit a skill or add a new one, this skill makes sure the OKF pattern is followed. The format stays consistent, and you never have to remember the rules yourself.

See it live:

• Repo: https://github.com/hamsof/okf-claude-skills-demo
• Rendered skills site: https://hamsof.github.io/okf-claude-skills-demo/

It’s a deliberately tiny POS (a cataloguecheckout(), two reports), just enough real code to document. The interesting parts are .claude/skills/, tools/build-html.mjs, and the auto-rebuild hook in .claude/hooks/.

Takeaways

• OKF is just markdown, frontmatter, and links. You likely have most of it already.
• Structure for small reads. One index, one tag, one reference beats grepping the repo every session. That is where the tokens go.
• Cross-link both ways so the model finds nested knowledge on its own.
• Write a meta-skill for your format and let it keep you consistent.
• You get a docs site for human-readable searching easily, which can become a knowledge-sharing site as well.

If your team keeps re-explaining the same systems to Claude, turn those explanations into an OKF bundle.

Happy Learning!