Maksym Prokopov
Personal blog powered by a passion for technology.

Knowledge Should Be Files

· 6 min read · aiagentsknowledge-managementdevopsdora

Google Cloud published the Open Knowledge Format this week.

The name sounds bigger than the thing itself.

And that is good.

OKF is basically this:

  • markdown files
  • YAML frontmatter
  • normal links between files
  • optional index.md
  • optional log.md
  • one required field: type

That is almost offensively boring, in the best possible way.

You can leave knowledge where a lot of useful technical knowledge already lives: plain text, next to the work, readable by humans and machines.

The real problem is retrieval

Most organizations already have the knowledge. The problem is that nobody can reliably find it at the moment when it matters.

It lives in:

  • Confluence pages
  • Google Docs
  • Slack threads
  • GitHub issues
  • runbooks
  • dashboards
  • code comments
  • Jira tickets
  • one senior engineer’s head

This is especially painful for AI agents.

An agent can write code, inspect logs, open pull requests, summarize incidents, and help debug production. But only if it has the right context.

Without context, it hallucinates confidently.

With context, it becomes useful.

The model is only one side of the equation. The other side is the boring operational knowledge that humans accumulate over years:

  • what this metric actually means
  • where the dashboard lives
  • which system owns this data
  • what not to compare
  • what command lies about being finished
  • which incident pattern keeps repeating
  • what the team decided last time

That knowledge should not be trapped in a vendor catalog.

It should be portable, reviewable, searchable, and close to the work.

So I tried it immediately

After reading the OKF post, I asked my agent to prototype one domain.

First: DORA metrics.

Then: my Harbour.Space DevOps course.

The DORA bundle became a small directory in my Obsidian vault:

DORA Metrics OKF/
  index.md
  log.md
  overview.md
  metrics/
    change-lead-time.md
    deployment-frequency.md
    failed-deployment-recovery-time.md
    change-fail-rate.md
    deployment-rework-rate.md
  references/
    dora-metrics.md
    okf-spec.md

Each concept file has frontmatter:

---
type: Metric
title: Deployment frequency
description: How often production deployments happen for a service.
tags: [dora, devops, software-delivery]
timestamp: 2026-06-13T09:50:00Z
---

Then the body explains:

  • what the metric means
  • how to interpret it
  • common traps
  • related metrics
  • citations

Nothing magical.

But this already makes the knowledge more useful than a random note called “DORA stuff”.

An agent can start at index.md, understand the domain, follow links, and answer questions without loading my entire vault into context.

That is the point.

DORA taught one lesson. The course taught another.

DORA metrics are a good first example because they are clean.

There are definitions. There are relationships. There are traps, like turning metrics into team rankings or treating service-level signals as company-wide vanity numbers.

The Harbour.Space DevOps course pushed the format harder.

A course has more than definitions. It has reasoning.

The bundle looks more like this:

Harbour Space DevOps Course OKF/
  index.md
  log.md
  overview.md
  principles/
    teaching-principles.md
    artifact-lifecycle.md
    transfer-over-recall.md
  curriculum/
    course-arc.md
    ai-assisted-devops-unit.md
    pacing-lessons.md
  assessment/
    assessment-model.md
    grading-rubric.md
    ai-assisted-assessment.md
    exam-design.md
  operations/
    delivery-operations.md
    student-environment.md
  references/

This is where the format starts to earn its keep.

The course cannot be reduced to “teach Docker, Kubernetes, CI/CD, observability”.

The real knowledge is:

  • students have very different starting levels
  • the course is intensive and time-compressed
  • AI is allowed, so assessment must test judgment, debugging, and transfer
  • students need preconfigured environments because setup pain destroys teaching time
  • the course arc is build, deploy, observe
  • the hard part is understanding whether the system works

That is exactly the kind of knowledge that disappears between semesters.

And it is exactly the kind of knowledge an agent needs if I ask:

Help me redesign the exam for this year’s AI-assisted DevOps course.

Without the OKF bundle, the agent has to search my entire Obsidian vault, infer structure, and hope it found the right notes.

With the bundle, it has a map.

Index files are underrated

The most useful OKF convention may be index.md.

This sounds tiny, but it matters a lot for agents.

Humans can visually browse folders. Agents need progressive disclosure.

Start here. Read this before that. If the task is grading, go there. If the task is curriculum design, read these two files first. If the task is about AI assessment, do not skip this concept.

That is what an index.md can do.

It turns a directory into a navigable knowledge surface.

The agent does not need to ingest everything. It can move through the knowledge the same way a good engineer moves through a codebase: start from the entry point, read the relevant files, follow links only when needed.

This matches how I already think about agent skills.

Progressive disclosure beats giant prompts.

Logs matter too

The other small but important convention is log.md.

Knowledge without history becomes suspicious.

When was this updated? Why did we change the definition? Was this generated from a source? Did a human review it? Is this still a prototype?

A simple chronological log answers those questions cheaply.

Again: boring.

Again: useful.

Backstage, Confluence, and OKF

I would keep Backstage for service catalog use cases.

I would keep Confluence where teams already collaborate there.

OKF fits a different role: interchange.

Backstage can point to OKF. Confluence can export to OKF. An agent can maintain OKF. A static site can render OKF. A repository can store OKF next to code. Obsidian can edit OKF because it is just markdown.

The value is mobility. Knowledge can move between tools without losing its basic structure.

Where I would use it at work

For SRE and platform teams, I can immediately see useful domains:

  • DORA metrics and delivery health
  • GCP project ownership
  • Confluent access model
  • incident runbooks
  • service ownership
  • data schemas and business metric definitions
  • Terraform module conventions
  • onboarding paths
  • production access procedures

The trick is to avoid boiling the ocean.

Starting with “let’s catalog the company” is how these efforts become expensive and useless.

Start with one painful domain where agents already struggle because context is fragmented.

For me, DORA metrics are a decent first slice. The Harbour.Space course is an even better one. A production SRE example would probably be better still: “everything an agent needs to know before touching Confluent access” or “how we reason about GCP project cleanup”.

Small bundle. Real task. Real consumer.

Then see if it helps.

My current opinion

The restraint is the point.

The format is basically saying:

Stop building another knowledge platform. Write the knowledge down in files, add just enough metadata, link the concepts, and make it easy for humans and agents to consume.

That is the right instinct.

I already believe skills should travel with the work. I now think knowledge bundles should too.

Project workflow? Put it near the repo.

Metric definitions? Put them near the dashboards and data sources.

Course design? Put it near the teaching material.

Personal operational memory? Put it in the vault.

The exact tool matters less than the property: durable, versioned, readable, linkable, and boring enough to survive.

Better models will matter.

Better context will matter just as much.

And sometimes better context is just a directory of markdown files with a tiny bit of YAML on top.