Title image: Knowledge base for AI agents, OKF and IaC

Knowledge base for AI agents: OKF and showcasing it with IaC

The Open Knowledge Format (OKF) is a vendor neutral and very compact definition by Google of how AI agents can keep context. With OKF compatible skills, AI agents can maintain a knowledge base without requiring humans to constantly update context. Parsing artifacts like code bases, documents or vector databases instead can become very inefficient.

OKF is something like Obsidian for AI agents.

The idea in one picture: an Obsidian vault for the agent

If you are using Obsidian or a similar tool, you know the principle: a folder of Markdown notes, linked to each other, each one about one topic. You do not read everything. You open the note you need and follow the links.

OKF applies this to AI context. The knowledge base is a folder of Markdown files, and the agent does not have to parse the whole code base to understand a system. It can read a conceptual description first and goes into the details only where the task requires it.

Put simply: OKF is documentation, but written for AI agents. Classic documentation is written for humans. It is prose, often long, and it assumes the reader can skim, judge what is relevant and fill gaps from experience. An agent cannot do that cheaply. It has a limited context window and pays for every token it reads. So documentation for agents has to be organized differently: small, focused documents, a declared type for each one, and tags and links that tell the agent which documents belong together. The content is still something a human can read and review, but the structure is made for selective loading.

What OKF specifies

Every knowledge document starts with a small YAML header (front matter) that carries structured information, for example:

---
type: decision
tags: [networking, ingress]
status: accepted
---

The type tells the agent what kind of document it is looking at (concept, decision, log, …). The tags connect documents with each other. Together with ordinary Markdown links they form a graph, or a dependency tree, of knowledge. The agent can load exactly the documents that are relevant for the current task instead of everything.

It is deliberately simple: plain text, readable by me, diffable in Git, and readable by the agent without any adapter.

The critical point: the agent maintains it

A knowledge base that a human has to keep up to date will be out of date soon. I have seen that with every code base I ever worked in.

What makes the approach interesting is that the agent updates the knowledge base on the go. When it makes a decision, it writes it down. When it changes a setting, it records it. When it finds out something is missing, it notes that too. The knowledge base is not documentation written afterwards, it is a side effect of the work.

And because it is just files in a repository, I can review these updates like code. The agent proposes, I read the diff, and I stay accountable for what ends up in the knowledge base. Automated PR reviews with AI agents also benefit, because they get another source of information that they can compare against. Code base (or infrastructure as code), PR descriptions and the knowledge base can be matched.

Showcase: Setting up a Kubernetes cluster

For this demo let’s set up a Kubernetes cluster with IaC (infrastructure as code) with Claude Code and the OKF skill written by Marco Boffo (okf-skills).

The starting point:

  • Three VMs to be used

  • An empty git repo, with the .okf directory (the okf-skill will use it for creating the knowledge base)

  • An AGENTS.md and a soft link CLAUDE.md to remain AI backend agnostic.

The AGENTS.md file gives the agent its initial scope and points it to the OKF knowledge base:

We're setting up and operating a Kubernetes cluster (vanilla k8s with `kubectl` and `etcd`).

There are 3 VMs at our disposal:

- `vm1.local`
- `vm2.local`
- `vm3.local`

Provide Ansible and OpenTofu files for the deployment (gitops).

Use the `okf-skill` and the `.okf/` folder to continuously add knowledge based on your work.

For demonstration purposes we’ll stop after the Ansible playbooks were created. When creating the K8s cluster in consecutive sessions, the AI agent is able to retrieve its information from the knowledge base and extend the infrastructure definition.

Installing the OKF skill

Typing the OKF skill installation prompt in Claude Code

Claude Code prompt. View the prompt text.

After reloading Claude, the OKF skill is ready to be used. A big thanks to Marco Boffo for providing this implementation.

Starting the IaC definition

Typing a Kubernetes deployment prompt in Claude Code

Claude Code prompt. View the prompt text.

Claude asks some questions and then creates the Ansible playbooks for the deployment.

The most interesting part is what happened in the .okf/ folder:

.okf/
  decisions/
    ha-endpoint-kube-vip.md # type: Decision, tags: [kubernetes, ha]
  infrastructure/
    cluster.md         # type: Infrastructure
  index.md             # Entry point of the knowledge tree
  log.md               # type: log       - chronological changes

Claude generated the first knowledge base files. These files can now be used as context about how the infrastructure is built up. The Ansible playbooks could also be used as context, but this format

  • contains more conceptual information,

  • is human readable,

  • can be used to derive a knowledge tree for optimized context loading.

Let’s see inside some files:

.okf/index.md

index.md is the entry point where the okf-skill can start looking for relevant context depending on the next prompt.

---
okf_version: '0.2'
---

# Kubernetes cluster

* [infrastructure/cluster.md](infrastructure/cluster.md) - the 3-node HA cluster
* [decisions/ha-endpoint-kube-vip.md](decisions/ha-endpoint-kube-vip.md) - kube-vip VIP and its super-admin.conf gotcha

.okf/log.md

The log file is like an audit trail for the knowledge base. It is a date-grouped log.

# Update Log

## 2026-11-02
* **Creation**: Scaffolded the Kubernetes cluster bundle with `okf_init.py`.

.okf/infrastructure/cluster.md

The .okf/infrastructure/cluster.md file contains the conceptual description of what is defined in the Ansible playbook. Basically it tells consecutive Claude sessions important information about the content of the Ansible playbooks, without loading the playbooks, unless it is necessary.

As can be seen, the content of the files just makes sense and the best part is, it was generated automatically. Future prompts will maintain the knowledge base and it will keep growing together with the project.

---
type: Infrastructure
title: Kubernetes cluster on vm1-vm3
description: HA vanilla Kubernetes cluster, 3 control-plane nodes with stacked etcd.
tags: [kubernetes, etcd]
status: draft
generated:
  by: claude-code/sonnet-5.5
  at: "2026-11-02T12:45:00Z"
---

# Overview

Nodes: vm1.local, vm2.local, vm3.local (Ubuntu 24.04, do not exist yet at authoring time).
All three are control-plane nodes with stacked etcd, and also run workloads.
The API server is reached through a kube-vip VIP, see [/decisions/ha-endpoint-kube-vip.md](/decisions/ha-endpoint-kube-vip.md).

| Item | Value |
|---|---|
| Kubernetes | 1.37.2 via kubeadm |
| Runtime | containerd 2.x, systemd cgroups |
| CNI | Cilium 1.20.4, kube-proxy replacement |
| Pod CIDR | 10.244.0.0/16 |
| Service CIDR | 10.96.0.0/12 |

# Deployment

Ansible, see `README.md` in the repository root.
Run `ansible-playbook playbooks/site.yml` after setting `kube_vip_address` in `group_vars/all.yml`.
Not yet executed against real VMs.

Conclusion

To me the OKF is a standard that formalizes the next step for agentic development. It also shows that today the same basics apply: a good code base requires good documentation. The better the documentation, the easier code maintenance. This applies to human programmers as well as AI programmers.