{
  "markdown": "# okf-builder\n\nAn [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.\n\nThe 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.\n\n> **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.\n\n## For consumers of the skill\n\nYou probably want the published archive, not this repo:\n\n```bash\ngh release download v0.2.0-alpha --repo eli-l/okf-builder \\\n  --pattern 'okf-builder_*_linux_amd64.tar.gz'\n```\n\nThe 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/`):\n\n```bash\ntar -xzf okf-builder_0.2.0-alpha_linux_amd64.tar.gz \\\n  -C ~/.openclaw/workspace/skills/okf-builder\n```\n\nSee the [release page](https://github.com/eli-l/okf-builder/releases) for the latest tag and download links.\n\n## For contributors\n\nThis repo is the home of the Go source, the CI/release pipelines, the example bundle, and contributor documentation.\n\n| If you want to… | Read |\n|---|---|\n| Understand how the code is organized | [`docs/architecture.md`](./docs/architecture.md) |\n| Build and test locally | [`docs/building.md`](./docs/building.md) |\n| Add a test, understand the test patterns | [`docs/testing.md`](./docs/testing.md) |\n| Ship a release, tag a version | [`docs/release.md`](./docs/release.md) |\n| Open a PR, follow the contribution conventions | [`docs/contributing.md`](./docs/contributing.md) |\n| Hit a wall, debug a weird issue | [`docs/gotchas.md`](./docs/gotchas.md) |\n\n`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.\n\nThe quick version:\n\n```bash\nmake                    # build all four binaries into dist/scripts/\nmake test               # go test ./... from src/\n./dist/scripts/okf-validate examples/example-bundle   # sanity-check the sample bundle\n```\n\n## Repository layout (top-level)\n\n```\nokf-builder/\n├── SKILL.md            # Skill consumer doc (shipped in the release archive)\n├── README.md           # This file\n├── LICENSE             # MIT\n├── Makefile            # Local dev: build, test, vet, fmt, clean\n├── docs/               # Contributor docs (an OKF bundle — see docs/index.md)\n├── examples/example-bundle/   # v0.2-conformant sample for manual testing\n├── src/                # Go module (cmd/ + internal/; scripts/ holds build-archive.sh)\n│   ├── cmd/            #   four CLI entry points, one per binary\n│   ├── internal/       #   shared library code (bundle, frontmatter, okf)\n│   └── scripts/        #   local mirror of the release pipeline (build-archive.sh)\n├── dist/               # Build artifact + archive staging dir\n│   ├── SKILL.md        #   copied here at archive time (gitignored)\n│   └── scripts/\n│       ├── okf-*       #   built binaries — per-platform, gitignored\n│       └── legacy/     #   deprecated bash validators — committed (they ship with the binaries)\n└── .github/workflows/  # ci.yml + release.yml\n```\n\n**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).\n\n## License\n\nMIT — see [`LICENSE`](./LICENSE).\n",
  "bytes": 4900,
  "sha": "71a89a087ff3d747093ff0d367bbefbe64ee861cd6a5c85f9ca168b58cc693c2",
  "repo_slug": "eli-l/okf-builder",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_eli_l_okf_builder_docs_index_md_85a3fd00/readme"
}