okf-skill — Derived Knowledge Bundle
Bundle OKF 0.1 · 4 conceitos · seanrobertwright/okf-skill
Open source Repository Open in the app JSON README (API)
About
# okf-skill — Derived Knowledge Bundle
A knowledge bundle **derived** from the
[okf-skill repository](https://github.com/seanrobertwright/okf-skill) by the
`okf-ingest` skill. It captures knowledge *about* the repository — its
architecture, components, example bundles, and vocabulary — rather than copying
source files. Each concept's `resource` points back to its origin in the repo.
Provenance: generated 2026-06-24 from commit history through `3e7f92e` via
derived extraction (sidecar mode).
# Subdirectories
* [architecture](architecture/index.md) - How the repository fits together at a high level.
* [components](components/index.md) - The two skills and the supporting scripts.
* [bundles](bundles/index.md) - The example OKF bundles shipped in the repo.
* [references](references/index.md) - Glossary of OKF terms used throughout.
Details
- Kind
- OKF bundles
- Topic
- Version control
- Publisher
- seanrobertwright
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Stars
- 1
- Last push
- 2026-06-24T16:08:16Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-09-08 16:04:09
- Updated
- 2026-09-08 16:04:09
- Origin id
seanrobertwright/okf-skill:okf-skill-knowledge/index.md
README
# okf-skill
Two [Claude Code](https://docs.claude.com/en/docs/claude-code) **skills** for working
with the [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
— a universal, vendor-neutral format for representing knowledge as plain markdown
files with YAML frontmatter, organized into directory "bundles".
- **`okf`** — produce, maintain, validate, and consume OKF bundles: turn what a
project knows (datasets, schemas, APIs, architecture, domain concepts, playbooks)
into a durable, git-versioned knowledge layer that humans and agents can read.
- **`okf-ingest`** — bring *existing* material into OKF compliance: point it at a
repo, docs set, or second brain (Obsidian/Logseq/Notion) and it analyzes the
source, recommends whether to convert fully / partially / not at all, asks how
you want to proceed, then implements your choice non-destructively.
No SDK, database, or query language required.
## What's in here
```
okf/ # SKILL 1 — the format authority
├── SKILL.md # trigger + operating guide (mental model, rules, workflows)
├── reference/spec.md # condensed normative OKF v0.1 spec (progressive disclosure)
├── templates/ # ready-made concept.md / index.md / log.md scaffolds
└── scripts/validate_okf.py # stdlib-only OKF v0.1 conformance checker
okf-ingest/ # SKILL 2 — convert existing sources into OKF
├── SKILL.md # analyze → summarize → recommend → ask → implement
├── reference/decision-framework.md # the full / partial / none rubric
├── reference/source-adapters.md # detection + conversion recipes per source type
└── scripts/analyze_source.py # stdlib source inventory / type detector
example-bundle/ # a tiny, conformant demo bundle (e-commerce shop)
osha-standards/ # a larger real-world bundle: a catalog of all OSHA 29 CFR standards Parts
okf-skill-knowledge/ # a derived bundle: okf-ingest run on THIS repo (knowledge about itself)
```
## Install
Copy whichever skill directories you want into your Claude Code skills folder:
- **Personal (all projects):** `~/.claude/skills/<skill>/`
- Windows: `C:\Users\<you>\.claude\skills\<skill>\`
- **Project-local (this repo only):** `<repo>/.claude/skills/<skill>/`
```bash
# personal install of both skills
git clone https://github.com/<you>/okf-skill
cp -r okf-skill/okf ~/.claude/skills/okf
cp -r okf-skill/okf-ingest ~/.claude/skills/okf-ingest
```
`okf-ingest` defers to `okf` for the spec, templates, and validator, so install
both for the full ingest experience. Then run `/reload-skills` (or restart). The
skills trigger on phrases like "OKF", "knowledge bundle", or "convert this to OKF".
## Usage
In any project, ask Claude Code things like:
- *"Use the okf skill to start a knowledge bundle for this repo."*
- *"Document this dataset as OKF."*
- *"Add an OKF concept doc for the orders table and refresh the index."*
- *"Validate this OKF bundle."*
- *"Use the okf-ingest skill on this: `<path or URL>`"* — analyze an existing
repo / docs / vault and convert it to OKF on your terms.
## The okf-ingest skill
`okf-ingest` brings *existing* material into OKF compliance. Point it at a local
path **or a URL** (it shallow-clones repos, fetches pages, or expands archives
into a scratch area first):
```
Use the okf-ingest skill on this: <path or URL>
```
It runs a fixed five-step flow — **step 4 is mandatory**, so nothing is converted
until you choose:
1. **Analyze** — `analyze_source.py` inventories the source (file/extension mix,
markdown frontmatter & `[[wikilink]]` stats, source-type signals, likely
excludes), supplemented by reading high-signal files.
2. **Summarize** — source type, volume, what's knowledge-bearing vs. noise,
reusable metadata, and what to exclude.
3. **Recommend** — a **per-segment** verdict, not one global call:
- **Full** — already knowledge-as-markdown (existing bundle, Obsidian/Logseq/
Notion, a docs site) → map ~1:1.
- **Partial / derived** — a code repo → *extract* knowledge (architecture,
module catalog, API & schema docs, glossary) into a sidecar bundle; don't
convert source files.
- **None** — generated output, vendored deps, binaries, secrets → skip.
4. **Query** — it asks you to choose **scope**, **mode** (sidecar vs. in-place),
**depth**, and output path, with the recommended option first.
5. **Implement** — converts only what you selected, **non-destructively by
default**, rewrites links to bundle-relative form, generates `index.md`/`log.md`,
then validates with `okf`'s checker and reports a conversion log.
Example recommendation table for a typical code repo:
| Segment | Verdict | Why |
|---------|---------|-----|
| `docs/`, `README` | Full | Curated markdown, high consumption value |
| `src/` | Derived | Knowledge is latent — extract architecture + API docs |
| `adr/` | Full | Decisions are durable knowledge |
| `dist/`, `node_modules/` | None | Generated / vendored |
| `.env`, `secrets/` | None (exclude) | Sensitive — never ingested |
The verdict rubric lives in
[`okf-ingest/reference/decision-framework.md`](okf-ingest/reference/decision-framework.md)
and the per-source recipes in
[`okf-ingest/reference/source-adapters.md`](okf-ingest/reference/source-adapters.md).
`okf-ingest` delegates to the `okf` skill for the spec, templates, and validation,
so install both.
## Validate a bundle
```bash
python okf/scripts/validate_okf.py <bundle_root> # or: py / python3
```
Reports **errors** for real conformance failures (missing/empty `type`,
misplaced frontmatter) and **warnings** for advisories (broken links, missing
`index.md`). Add `--strict` to fail on warnings too. Broken links are warnings,
never errors — that is intentional per the spec.
## The format in one breath
- Each concept is one `.md` file: queryable YAML frontmatter (`type` required) +
free-form markdown body (`# Schema`, `# Examples`, `# Citations`).
- Concepts link to each other with ordinary markdown links; the relationship's
*meaning* lives in the surrounding prose, not the link. Broken links are OK.
- `index.md` (navigation) and `log.md` (changelog) are reserved filenames and
carry no frontmatter — except a bundle-root `index.md`, which may declare
`okf_version`.
See [`okf/reference/spec.md`](okf/reference/spec.md) for the full condensed spec.
## Credit
OKF is a specification from Google Cloud's
[knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)
project. This repository only packages a Claude Code skill around that format; it
is not affiliated with or endorsed by Google.