Skip to content

federated-knowledge-skills (Felix Schindler)

This is a tool reference

What a tool or project is, who makes it, and what it is for, whether someone else wrote it or I did. Everything I have learned about it lives elsewhere and links back here.

federated-knowledge-skills1 is the layer that turns several independent OKF bundles into one federation an agent can use: a skill it reads, a CLI it runs, and two pre-commit hooks each bundle pins for itself. It is mine, and it is the tooling this bundle is now written through, so it appears here in the same two roles that agent-knowledge does: a tool with a page, and the thing producing the pages.
Author Felix Schindler
Licence MIT, with the vendored OKF validator under its own
Language Python 3.11+, run through uv as PEP 723 scripts with no install step
Distribution A skill directory to copy, and two pre-commit hook ids a bundle pins by revision
Source github.com/ftschindler/federated-knowledge-skills
Status The skill, the CLI and the hooks are shipped and in use here; a second tier and the retirement of the old architecture are not done

What it is

Four things, and the split between them is the whole design.

  • A bundle is an ordinary directory of Markdown concepts that does not know it belongs to a federation. It clones, publishes and lints standalone. This one does.
  • A workspace manifest, one file per machine, says which bundles exist locally and assigns each a role: whether it may be written to, which bundles may cite it, and where it publishes if it does. referenceable_by [] seals a bundle, so nothing that publishes can link into it.
  • A skill, fkb, is the prose an agent reads: how to answer from the bundles before reaching for the web, and how to file something afterwards. It runs the CLI and reads its own references. It is replaceable by hand, which is what keeps "no mandatory tool between me and the content" true.
  • A CLI, also fkb, owns the handful of questions that need a deterministic answer: list for what exists and what each allows, resolve for one bundle as JSON, lint for whether it holds up, url for a link into another bundle, and init and add for setting one up.

Underneath, okf-concepts and okf-bundle are the same checker under two blocking policies, shipped as pre-commit hooks a bundle pins by revision. They enforce the format's hard rules and the fields the bundle's own fkb.yaml declares, and nothing else: a field the floor does not name is reported and left alone. okf-concepts checks the whole bundle and fails only on the files being committed, so an unfinished concept elsewhere never blocks an unrelated commit, and --all-files makes the same hook strict in CI. This is what Guard invariants at commit-time, not review-time looks like when the thing being guarded is prose.

The three decisions everything follows from

The Markdown file is the source.2 No ingest step, no rendered copy, no render_hash reconciling two versions of one note. An agent writes the file a person then edits, which is the property agent-wiki traded away for a CLI that could hold the vault's invariants.

A skill may run a command; a skill never invokes another skill. Prose calling prose through an LLM is not control flow. That rule is what the first attempt cost, and the account of it is Wrapping the kb skills in a federation layer.

The manifest is a guardrail, not a security boundary. Access control is git remote permissions and each bundle's own publish gate. The manifest can be edited by anything running on the machine, so nothing load-bearing may rest on it, and a bundle stays safe when an agent bypasses the federation layer entirely. The reasoning is Separate audiences with separate bundles, not with folders or tags, taken to its conclusion: if the audience boundary is the repository, then the repository is where it has to be enforced.

Where it came from

Federating my knowledge base as privacy-tiered OKF bundles is the decision, and Federated OKF knowledge bases: a workspace-manifest architecture is the architecture it settled on. The first implementation wrapped the kb-* skills from agent-knowledge and was retired at twenty commits and a green test suite; the format discipline and that project's own bundle survived, and are still read here as an upstream source.

What it deliberately does not do yet

There is no search command. The skill tells an agent to read the bundles with rg and its own file tools, and the project keeps a journal line every time that is not good enough, so what gets built next answers a recorded incident rather than a guess.

Composition is also ambient rather than pinned: the manifest points at whatever each bundle currently is, and there is no reproducible "the whole knowledge base at commit X". That is recorded as a choice in the decision above rather than discovered later as an oversight.

The following pages link to this page:

  1. ftschindler/federated-knowledge-skills: README, by felix_schindler, last modified 2026-09-16 ↩

  2. federated-knowledge-skills: DESIGN.md, by felix_schindler, last modified 2026-09-16 ↩