{
  "markdown": "# okf-skill\n\n![OKF: Open Knowledge Format — LLM-wiki standard & agent skill tool](assets/okf-overview.jpeg)\n\nTwo [Claude Code](https://docs.claude.com/en/docs/claude-code) **skills** for working\nwith the [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)\n— a universal, vendor-neutral format for representing knowledge as plain markdown\nfiles with YAML frontmatter, organized into directory \"bundles\".\n\n- **`okf`** — produce, maintain, validate, and consume OKF bundles: turn what a\n  project knows (datasets, schemas, APIs, architecture, domain concepts, playbooks)\n  into a durable, git-versioned knowledge layer that humans and agents can read.\n- **`okf-ingest`** — bring *existing* material into OKF compliance: point it at a\n  repo, docs set, or second brain (Obsidian/Logseq/Notion) and it analyzes the\n  source, recommends whether to convert fully / partially / not at all, asks how\n  you want to proceed, then implements your choice non-destructively.\n\nNo SDK, database, or query language required.\n\n## What's in here\n\n```\nokf/                       # SKILL 1 — the format authority\n├── SKILL.md               # trigger + operating guide (mental model, rules, workflows)\n├── reference/spec.md      # condensed normative OKF v0.1 spec (progressive disclosure)\n├── templates/             # ready-made concept.md / index.md / log.md scaffolds\n└── scripts/validate_okf.py # stdlib-only OKF v0.1 conformance checker\n\nokf-ingest/                # SKILL 2 — convert existing sources into OKF\n├── SKILL.md               # analyze → summarize → recommend → ask → implement\n├── reference/decision-framework.md  # the full / partial / none rubric\n├── reference/source-adapters.md     # detection + conversion recipes per source type\n└── scripts/analyze_source.py        # stdlib source inventory / type detector\n\nexample-bundle/            # a tiny, conformant demo bundle (e-commerce shop)\nosha-standards/            # a larger real-world bundle: a catalog of all OSHA 29 CFR standards Parts\nokf-skill-knowledge/       # a derived bundle: okf-ingest run on THIS repo (knowledge about itself)\n```\n\n## Install\n\nCopy whichever skill directories you want into your Claude Code skills folder:\n\n- **Personal (all projects):** `~/.claude/skills/<skill>/`\n  - Windows: `C:\\Users\\<you>\\.claude\\skills\\<skill>\\`\n- **Project-local (this repo only):** `<repo>/.claude/skills/<skill>/`\n\n```bash\n# personal install of both skills\ngit clone https://github.com/<you>/okf-skill\ncp -r okf-skill/okf         ~/.claude/skills/okf\ncp -r okf-skill/okf-ingest  ~/.claude/skills/okf-ingest\n```\n\n`okf-ingest` defers to `okf` for the spec, templates, and validator, so install\nboth for the full ingest experience. Then run `/reload-skills` (or restart). The\nskills trigger on phrases like \"OKF\", \"knowledge bundle\", or \"convert this to OKF\".\n\n## Usage\n\nIn any project, ask Claude Code things like:\n\n- *\"Use the okf skill to start a knowledge bundle for this repo.\"*\n- *\"Document this dataset as OKF.\"*\n- *\"Add an OKF concept doc for the orders table and refresh the index.\"*\n- *\"Validate this OKF bundle.\"*\n- *\"Use the okf-ingest skill on this: `<path or URL>`\"* — analyze an existing\n  repo / docs / vault and convert it to OKF on your terms.\n\n## The okf-ingest skill\n\n`okf-ingest` brings *existing* material into OKF compliance. Point it at a local\npath **or a URL** (it shallow-clones repos, fetches pages, or expands archives\ninto a scratch area first):\n\n```\nUse the okf-ingest skill on this: <path or URL>\n```\n\nIt runs a fixed five-step flow — **step 4 is mandatory**, so nothing is converted\nuntil you choose:\n\n1. **Analyze** — `analyze_source.py` inventories the source (file/extension mix,\n   markdown frontmatter & `[[wikilink]]` stats, source-type signals, likely\n   excludes), supplemented by reading high-signal files.\n2. **Summarize** — source type, volume, what's knowledge-bearing vs. noise,\n   reusable metadata, and what to exclude.\n3. **Recommend** — a **per-segment** verdict, not one global call:\n   - **Full** — already knowledge-as-markdown (existing bundle, Obsidian/Logseq/\n     Notion, a docs site) → map ~1:1.\n   - **Partial / derived** — a code repo → *extract* knowledge (architecture,\n     module catalog, API & schema docs, glossary) into a sidecar bundle; don't\n     convert source files.\n   - **None** — generated output, vendored deps, binaries, secrets → skip.\n4. **Query** — it asks you to choose **scope**, **mode** (sidecar vs. in-place),\n   **depth**, and output path, with the recommended option first.\n5. **Implement** — converts only what you selected, **non-destructively by\n   default**, rewrites links to bundle-relative form, generates `index.md`/`log.md`,\n   then validates with `okf`'s checker and reports a conversion log.\n\nExample recommendation table for a typical code repo:\n\n| Segment | Verdict | Why |\n|---------|---------|-----|\n| `docs/`, `README` | Full | Curated markdown, high consumption value |\n| `src/` | Derived | Knowledge is latent — extract architecture + API docs |\n| `adr/` | Full | Decisions are durable knowledge |\n| `dist/`, `node_modules/` | None | Generated / vendored |\n| `.env`, `secrets/` | None (exclude) | Sensitive — never ingested |\n\nThe verdict rubric lives in\n[`okf-ingest/reference/decision-framework.md`](okf-ingest/reference/decision-framework.md)\nand the per-source recipes in\n[`okf-ingest/reference/source-adapters.md`](okf-ingest/reference/source-adapters.md).\n`okf-ingest` delegates to the `okf` skill for the spec, templates, and validation,\nso install both.\n\n## Validate a bundle\n\n```bash\npython okf/scripts/validate_okf.py <bundle_root>   # or: py / python3\n```\n\nReports **errors** for real conformance failures (missing/empty `type`,\nmisplaced frontmatter) and **warnings** for advisories (broken links, missing\n`index.md`). Add `--strict` to fail on warnings too. Broken links are warnings,\nnever errors — that is intentional per the spec.\n\n## The format in one breath\n\n- Each concept is one `.md` file: queryable YAML frontmatter (`type` required) +\n  free-form markdown body (`# Schema`, `# Examples`, `# Citations`).\n- Concepts link to each other with ordinary markdown links; the relationship's\n  *meaning* lives in the surrounding prose, not the link. Broken links are OK.\n- `index.md` (navigation) and `log.md` (changelog) are reserved filenames and\n  carry no frontmatter — except a bundle-root `index.md`, which may declare\n  `okf_version`.\n\nSee [`okf/reference/spec.md`](okf/reference/spec.md) for the full condensed spec.\n\n## Credit\n\nOKF is a specification from Google Cloud's\n[knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)\nproject. This repository only packages a Claude Code skill around that format; it\nis not affiliated with or endorsed by Google.\n",
  "bytes": 6809,
  "sha": "8db39f34af7507e2c986cb1852d4a5de639cf94160127191a32ef44a05106f5c",
  "repo_slug": "seanrobertwright/okf-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_seanrobertwright_okf_skill_okf_skill_kno_14bfb521/readme"
}