Procedures Travel. Knowledge Stays Home.

ai / agents / skills / knowledge / claude / okf / leadership / organizational learning / tooling

A couple weeks ago I wrote that your organization has to learn as fast as your best AI adopter. Externalize, combine, socialize, internalize. Run Nonaka’s spiral or get left behind. A bunch of you wrote back with the same question: okay, but where does the knowledge actually go?

Fair. I waved my hands at “a shared place” and “a skills repo” and moved on. Let me fix that, because there’s a real answer now, and it’s two answers, not one. And along the way I’ll show you how to stand up your own internal equivalent to apt install for your skills — your own private marketplace, no cloud required.


One side ships to everyone. The other side is yours and only yours.

Two Kinds of Knowledge, and We Keep Confusing Them

Here’s the distinction that took me embarrassingly long to say out loud. There are two completely different things we shove into our agents and call “knowledge,” and they behave nothing alike.

We used to just call them procedures. How to do things. Run the tests before you open the PR. Update REQUIREMENTS.md before you touch code. When you debug, reproduce first, then bisect. The discipline, the workflow, the muscle memory. Every shop I’ve ever worked in had a binder or a wiki full of them.

In the AI world we gave procedures a new name: Skills. Same idea your team has had forever — how we do it here — just packaged so an agent can pick it up and run it. This is procedural knowledge.

Declarative knowledge is what things are. The orders table joins to customers on customer_id but watch out, there’s a soft-delete flag nobody documented. The billing service owns idempotency keys. Weekly Active Users means this specific thing and not the three other things people assume. This is the map of your actual systems.

Skills you trigger with /skill-name, or they fire when the agent recognizes the situation. Declarative knowledge is getting a name too — it’s starting to live in something called OKF, the Open Knowledge Format, which Google Cloud shipped on June 12 of this year.

They are not competitors. I’ve seen a few hot takes framing it as “Skills vs OKF” and that’s the wrong frame. They’re two layers of the same stack. One tells the agent how to work. The other tells it what it’s working on.

Think about that for a minute. You can’t do either job with only half.

We Solved Distribution Already. It’s Called a Package Manager.

I’ve been pulling software off a distribution server since before some of you were born. My first Linux kernel was before it was 1.0, and even then there was a clean instinct baked into the whole thing: here is the reusable stuff that everybody shares, and here is my box, which is mine.

That instinct is the whole reason apt works. And npm. And Go modules. And Homebrew. A package manager distributes artifacts that are generalizable — the package doesn’t care which machine it lands on, because the how it provides is the same everywhere. Write it once, publish it, and a thousand machines install the identical thing. That’s procedural knowledge to a T.

But here’s the part nobody trips over because it’s so obvious: you never apt install your own application’s data. Your /etc config, your database, your local state, the actual truth about your deployment — none of that comes from a repo. It can’t. It’s specific to you. You curate it, on your box, by hand, forever.

Procedures travel. Knowledge stays home.

That’s the entire thesis of this post, and it’s the same split we’ve lived with for thirty years of package managers. The agent world just rediscovered it. Again. We always do.

The Good News: Procedural Knowledge Now Has a Package Manager

This is the part that genuinely excites me, and I don’t say that lightly — I’ve been here for all the hype cycles and most “revolutions” are a feature in a trench coat.

Skills are shareable. Really shareable. I install my core skill set on a new machine with one line:

/plugin install gherlein@gherlein-marketplace

That’s it. Engineering principles, my spec-driven workflow, the autonomous build protocol, git conventions — the entire how I work layer drops onto a fresh box in seconds. If that feels familiar, it should: it’s apt install for procedural knowledge. In Nonaka’s terms the marketplace is a Combination and Diffusion engine — somebody externalizes a workflow once, packages it, and now the whole team (or the whole internet) can internalize it without each person re-discovering it on their own nights and weekends.

Remember the failure mode from my last post? A dozen engineers each maintaining their own private .claude/ directory, none of them talking, every one of them having a lonely private epiphany about the same prompt trick. The marketplace fixes that for procedures. You build a team marketplace, you publish the team’s skills, and the new hire is at your team’s Stage 4 on day one instead of month three.

If your team isn’t doing this yet, stop reading and go set up a shared skills marketplace. Seriously. It’s the single highest-leverage externalization move available right now and it’s nearly free.

Roll Your Own Marketplace

“But Greg, some of our workflows and skills are very specific to my company — they’d have no value on a public marketplace anyway.” Exactly right, and you don’t have to put them there. A marketplace is just a git repo (or even a local directory) with a .claude-plugin/marketplace.json manifest that lists your plugins. No cloud, no vendor, no account. This is the internal apt install I promised you.

The manifest is about as scary as it looks, which is to say not at all:

{
  "name": "acme-internal",
  "owner": { "name": "Acme Platform Team" },
  "plugins": [
    {
      "name": "engineering-principles",
      "source": "./plugins/engineering-principles",
      "description": "How we work here — spec-driven, build, review, git conventions"
    }
  ]
}

Each plugin’s source can be a local path, a git URL, or a GitHub ref — so you can mix your own homegrown plugins with ones you pull in from elsewhere. Point Claude Code at it:

/plugin marketplace add your-org/claude-marketplace   # a private GitHub repo
/plugin marketplace add ./acme-internal               # or just a local dir

Then anybody on the team installs it the same way:

/plugin install engineering-principles@acme-internal

That local-directory form is also how you develop a plugin — point at the working directory, iterate, /plugin marketplace update to refresh. Put the repo behind your normal git access controls and you’ve got a private, internal, team-only apt for procedural knowledge. Boring. Exactly the kind of boring that wins.

Bad News: Declarative Knowledge Can’t Be Shipped From a Repo

Here’s where people get into trouble.

There is no /plugin install our-actual-data-model. There never will be. Nobody can package the truth about your billing service and publish it for you, because the truth about your billing service exists in exactly one place in the universe — your billing service — and it’s changing under you every sprint. Same reason there’s no apt install for your production database.

Declarative knowledge has to be curated locally. Alongside the code. By the people who own the code. This is the part agents are weirdly bad at on their own — they will happily hallucinate a join key or assume a metric means the obvious thing. They cannot make the knowledge true to your situation without a human in the loop. I said that last time and it’s even more true here.

That’s the problem OKF is trying to solve, and I think the shape of it is right. It’s a specified markdown format for declarative knowledge — concepts, relationships, schemas, citations — that lives in your repo next to the thing it describes. Metadata-as-code, basically, but pinned down enough that any agent can read it. Google’s own line on it is the part that landed for me:

“Instead of using models to search the same documents for the same facts over and over, you can give your agents a shared markdown library that grows more useful over time.”

Search the same documents for the same facts over and over. Every single session. That’s the lost-context-between-sessions tax, and most of us are paying it without even noticing. The agent re-derives your schema from scratch every morning like it has amnesia, because it does.

How the Two Layers Actually Fit

People ask if OKF replaces CLAUDE.md. It does not. Don’t overthink this.

CLAUDE.md   →  behavioral config: which skills, which rules, and a pointer:
               "read /okf/sales/metrics/weekly_active_users.md before analytics work"

OKF bundle  →  the declarative knowledge CLAUDE.md points at:
               the metric definition, the schema, the joins, the citations

Skills      →  the procedural layer that runs on top:
               spec-driven says "update REQUIREMENTS.md first," and now the agent
               knows WHAT REQUIREMENTS to honor because the OKF told it

CLAUDE.md is the index and the behavior. Skills are the how. OKF is the what. Each does one job and they compose. Small, composable interfaces — the same principle we’ve been preaching about code for thirty years, finally applied to the stuff we feed our agents.


How and What, meshed. Neither turns without the other.

The Community Already Ran Ahead of Me

The thing that tells me this isn’t vaporware: OKF shipped on June 12 and there are already real Claude Code skills for working with OKF. That’s the spiral turning fast, and it’s beautiful to watch.

  • scaccogatto/okf-skills is dual-mode — a Claude Code plugin and skills.sh compatible, so it works in Cursor, Codex, and a couple dozen other agents. It’ll produce, validate (a real conformance check against the v0.1 spec, not a vibe check), and even render a bundle as an interactive HTML graph. /plugin install okf@scaccogatto.
  • catancs/okf-skill does the full CRUD lifecycle and explicitly frames OKF as the cure for lost-context-between-sessions. Knowledge that compounds across sessions instead of getting rebuilt every time.
  • supachai-j/open-knowledge-format-starter is a starter kit, and it made a design choice I love: ingestion is supervised on purpose. A human approves the extracted claims before anything gets written. Five to fifteen claims, eyeballed by a person, treated as a quality gate.

Notice the shape, though. Even consuming and authoring declarative knowledge turned out to be a procedure — so the community packaged that procedure as a Skill and shipped it through the marketplace. Procedures travel. Even the procedure for tending your local knowledge.

So What Do You Actually Do On Monday Morning?

Same as last time — enough theory, here’s the work:

1. Don’t try to ship what can’t be shipped

Stop looking for a marketplace plugin that contains the truth about your systems. It does not exist and it cannot. That curation is your team’s job, forever, and the teams that accept that early are going to look like wizards to the ones still hoping someone packages it for them.

If someone elses packaged skills work for you, install them. If not, write your own skills and package them. Leading us to…

2. Stand up a team skills marketplace

Procedural knowledge has a package manager now. Use it. Get your team’s workflows out of a dozen private .claude/ directories and into one published marketplace. This is the easy 80% of value and most teams haven’t done it. My team is just starting.

3. Start curating declarative knowledge in the repo, next to the code

Pick one painful thing — the data model everyone gets wrong, the service contract that bites every new hire — and write it down in an OKF bundle living in the repo. Point CLAUDE.md at it. You’ve just stopped paying the amnesia tax on that one thing. Then do the next one. Rinse and repeat.

4. Keep a human on the approval gate

Let the agent draft the bundles. It’s genuinely great at it. But a person who owns the system signs off before it’s canon. Supervised ingestion isn’t slower in the way that matters — it’s the difference between a knowledge base your agents can trust and a confident pile of plausible lies. Have a Senior Engineer vet the knowledge - definitely do a PR review.

Conclusions

The framing I want you to walk away with is dead simple. Skills are how. Knowledge is what. How travels — package it, publish it, install it on a fresh box in one line. What stays home — curated locally, alongside the code, by the humans who actually know the system.

We have a clean distribution mechanism for procedural knowledge, and that’s a genuine unlock for the organizational-learning problem I was banging on about a couple weeks ago. The marketplace is Diffusion-as-a-service for the how. But it doesn’t touch the what, and the sooner your team internalizes that the two are different jobs, the sooner you stop confusing them and start doing both deliberately.

Here’s the thing about package managers, by the way: they’re boring. apt is boring. Go modules are boring. And boring infrastructure is exactly what wins every hype cycle — it’s still running long after the flashy stuff is forgotten. The skills marketplace is going to be that kind of boring, and I mean that as the highest compliment. The teams that treat it like plumbing and just build it will quietly pull ahead of the ones still arguing about which model is best this week.

Build the team marketplace. Curate the knowledge locally. Keep a human on the log. Rinse and repeat.

If this helps you, drop me a note on LinkedIn. And if your team’s “knowledge base” is still a Confluence graveyard nobody reads and no agent can parse — that’s your Monday. Go fix it.

Further reading:

 Share!