Architecture
Bundle OKF 0.2 · 6 conceitos · eli-l/okf-builder
Open source Repository Open in the app JSON README (API)
About
# Architecture
* [Repository architecture](architecture.md) - How the okf-builder Go source is organized — package layout, layering, and the cmd/internal split.
# Process
* [Building and testing locally](building.md) - How to compile the four Go binaries, run the test suite, and vet the code from a working checkout of okf-builder.
* [Contributing and review process](contributing.md) - How to make a change to okf-builder — branch naming, commit messages, PR review, and merge policy.
* [Release pipeline and tagging](release.md) - How a tag becomes a published archive — the release workflow, archive layout, GitHub Release quirks, and how to republish.
* [Testing patterns and conventions](testing.md) - How tests are organized in okf-builder, what patterns to follow, and how to test the error path on a CLI binary.
# Reference
* [Common gotchas](gotchas.md) - Cross-cutting traps when working on okf-builder — Go bootstrap, bwrap sandbox, YAML empty-mapping semantics, release workflow foo
Details
- Kind
- OKF bundles
- Topic
- Developer tools
- Publisher
- eli-l
- Origin
- okf_github
- Category
- dados
- Version
- 0.2
- Stars
- 5
- Forks
- 1
- Last push
- 2026-08-24T12:09:17Z
- Repository state
- ativo
- Language
- Go
- License
- MIT
- Added
- 2026-09-08 16:02:35
- Updated
- 2026-09-08 16:02:35
- Origin id
eli-l/okf-builder:docs/index.md
README
# okf-builder An [Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) toolchain for [**OKF (Open Knowledge Format)**](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) knowledge catalogs. OKF is a convention for directories of markdown files with YAML frontmatter that capture context, decisions, and curated insight around data and systems in a form both humans and agents can read. This repository hosts the skill that agents use to **author, validate, migrate, and read** those catalogs — turning free-form notes into a structured, queryable knowledge base that survives across sessions. The skill ships as four pre-compiled Go binaries — `okf-validate`, `okf-regenerate-index`, `okf-check-links`, `okf-migrate-v01-to-v02` — packaged with a `SKILL.md` procedure in the [Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) format. Drop the archive into any Agent Skills runtime (Claude Code, OpenClaw, ...) and the agents running there can pick it up directly. > **Spec compatibility:** OKF v0.2. See [OKF v0.2 SPEC](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) for the bundle structure, frontmatter vocabulary, and validation rules this skill enforces. ## For consumers of the skill You probably want the published archive, not this repo: ```bash gh release download v0.2.0-alpha --repo eli-l/okf-builder \ --pattern 'okf-builder_*_linux_amd64.tar.gz' ``` The archive is **flat** — after extraction you get `SKILL.md` and a `scripts/` directory at the top level. Move them straight into your runtime's skills directory (for OpenClaw: `~/.openclaw/workspace/skills/okf-builder/`): ```bash tar -xzf okf-builder_0.2.0-alpha_linux_amd64.tar.gz \ -C ~/.openclaw/workspace/skills/okf-builder ``` See the [release page](https://github.com/eli-l/okf-builder/releases) for the latest tag and download links. ## For contributors This repo is the home of the Go source, the CI/release pipelines, the example bundle, and contributor documentation. | If you want to… | Read | |---|---| | Understand how the code is organized | [`docs/architecture.md`](./docs/architecture.md) | | Build and test locally | [`docs/building.md`](./docs/building.md) | | Add a test, understand the test patterns | [`docs/testing.md`](./docs/testing.md) | | Ship a release, tag a version | [`docs/release.md`](./docs/release.md) | | Open a PR, follow the contribution conventions | [`docs/contributing.md`](./docs/contributing.md) | | Hit a wall, debug a weird issue | [`docs/gotchas.md`](./docs/gotchas.md) | `docs/` is itself an [OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) bundle — it's validated by the same `okf-validate` binary the toolchain ships. Each doc is a typed concept with `generated`/`verified` frontmatter. The quick version: ```bash make # build all four binaries into dist/scripts/ make test # go test ./... from src/ ./dist/scripts/okf-validate examples/example-bundle # sanity-check the sample bundle ``` ## Repository layout (top-level) ``` okf-builder/ ├── SKILL.md # Skill consumer doc (shipped in the release archive) ├── README.md # This file ├── LICENSE # MIT ├── Makefile # Local dev: build, test, vet, fmt, clean ├── docs/ # Contributor docs (an OKF bundle — see docs/index.md) ├── examples/example-bundle/ # v0.2-conformant sample for manual testing ├── src/ # Go module (cmd/ + internal/; scripts/ holds build-archive.sh) │ ├── cmd/ # four CLI entry points, one per binary │ ├── internal/ # shared library code (bundle, frontmatter, okf) │ └── scripts/ # local mirror of the release pipeline (build-archive.sh) ├── dist/ # Build artifact + archive staging dir │ ├── SKILL.md # copied here at archive time (gitignored) │ └── scripts/ │ ├── okf-* # built binaries — per-platform, gitignored │ └── legacy/ # deprecated bash validators — committed (they ship with the binaries) └── .github/workflows/ # ci.yml + release.yml ``` **Why is `dist/` partly tracked?** The release archive is assembled from `dist/` (a flat `tar -C dist -czf ... .` of its contents). The Go binaries under `dist/scripts/` are gitignored because they're per-platform artifacts built locally by `make` or by the release workflow. But the deprecated bash validators under `dist/scripts/legacy/` *are* committed — they're source files (just bash, not Go), they ship alongside the binaries in the archive, and storing them anywhere else would mean an extra copy step in both `build-archive.sh` and `release.yml`. The full rationale is in [`docs/release.md`](./docs/release.md). ## License MIT — see [`LICENSE`](./LICENSE).