okf git:20260721.84ab3d0A

Immutable. This exact content is served forever at /api/v1/blob/78972ac52ad7264f.

---
name: okf
description: Maintain a project knowledge wiki in Open Knowledge Format with /okf init, open, author, convert, sync, study, retro, extract, validate, lint, and embed.
triggers:
  - /okf
  - okf
  - Open Knowledge Format
  - knowledge wiki
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Grep
  - Glob
---

# OKF Knowledge Wiki

Use this skill when the user asks to create, maintain, validate, search, or update a project knowledge bundle in Open Knowledge Format (OKF).

The bundle is the source of truth. Keep changes small, cited, and PR-gated. Deterministic scripts validate conformance; LLM passes may suggest or draft knowledge, but they never replace the gate.

## Command Table

| Command | Purpose | Primary references |
| --- | --- | --- |
| `/okf init` | Create or connect a project knowledge bundle. | `references/workflow.md`, `references/spec.md` |
| `/okf open [--no-install] [--no-browser]` | Open the configured bundle in the local visual knowledge viewer. | `references/overdeck.md` |
| `/okf author "<topic>"` | Write or refresh one focused concept. | `templates/concept.md`, `references/taxonomy.md`, `references/model-bridges.md` |
| `/okf convert <path>` | Convert existing docs into OKF concepts without deleting originals. | `references/conversion.md` |
| `/okf sync [--topic "<focus>"]` | Update concepts from code or documentation changes. | `references/workflow.md`, `references/model-bridges.md` |
| `/okf study "<focus>"` | Pre-feature pass that documents current behavior for a topic. | `references/workflow.md`, `references/taxonomy.md`, `references/model-bridges.md` |
| `/okf retro` | Post-implementation pass that captures what would have helped. | `references/workflow.md`, `references/model-bridges.md` |
| `/okf extract "<query>" [--budget <tokens>]` | Return ranked, token-budgeted, cited concepts for prompt use. | `references/spec.md` |
| `/okf validate [--strict]` | Run the deterministic conformance gate. | `references/conformance.md` |
| `/okf lint` | Run advisory semantic patrol for stale or weak knowledge. | `references/lint-prompt.md`, `references/conformance.md` |
| `/okf embed [--profile <name>]` | Update shareable embedding shards and rebuild the local index. | `references/workflow.md` |

## Guardrails

- Resolve the bundle first. Prefer `.okf.yml` in the code repository; if absent, ask the user to run `/okf init`.
- Keep the skill portable: require only git, gh, Python 3, PyYAML, and optional embedding providers. Do not require Overdeck.
- Never import or call Overdeck code from scripts under this skill. Documentation may describe Overdeck integration, but the portable core has no Overdeck dependency.
- Treat `index.md` and `log.md` as reserved files, not concepts.
- Preserve unknown frontmatter keys when editing concepts.
- Use deterministic validation for pass/fail decisions. `/okf lint` is advisory only.
- Never put vectors in Markdown frontmatter. The only embedding frontmatter key is optional `x_embed: exclude`.

## Reading Rules

When answering from a bundle or preparing prompt context:

1. read `index.md` first.
2. load only relevant concepts.
3. answer only from loaded concepts.
4. cite concept IDs for every project-specific claim.
5. never invent missing knowledge. If the bundle does not contain the answer, say what is missing and suggest `/okf study "<focus>"` or `/okf author "<topic>"`.

## Model Selection

For `/okf study`, `/okf retro`, `/okf sync`, and `/okf author`, honor `--model <model>` using this ladder:

1. Use the current harness natively when it can serve the requested model.
2. Use a vendor CLI already on `PATH`: after `codex login status`, invoke `codex exec -m <model> --sandbox workspace-write --output-last-message <output-file> "<prompt>"`; after ADC or `GOOGLE_API_KEY` verification, invoke `gemini -p "<prompt>" -m <model>`.
3. Use an installed bridge plugin command when available, such as `/codex:rescue` or `/gemini:task`.
4. Use an available MCP bridge tool when available, such as `mcp__codex__*`, `mcp__gemini__*`, or `ai-cli-mcp` when it explicitly supports the requested model.
5. If none can serve the model, stop with the hard error template in `references/model-bridges.md`, naming the requested model, bridge, install command, and auth step. Never silently substitute another model.

Under Overdeck, `pan knowledge --model <model>` bypasses this portable ladder and uses Overdeck model routing.

## `/okf init`

Create a knowledge bundle and pointer file.

- Default target: a peer directory named `../<project>-knowledge`; initialize it as a git repo and create the remote with `gh repo create` when requested.
- Overrides: `--dir <path>` for any external directory, or `--local <subdir>` for an in-repo bundle with no companion repo.
- Copy `templates/repo/` into the bundle, including README, CONTRIBUTING, CODEOWNERS, `.github/workflows/conformance.yml`, `index.md`, `log.md`, `.gitignore`, Overview, and the first Decision concept.
- Copy `templates/okf-embeddings.yaml` to the bundle root. The default profile is keyless Ollama: `ollama` / `nomic-embed-text` / `768` / `share: true`.
- Write `.okf.yml` at the code repo root with `bundle: ../<project>-knowledge` and `remote: <created remote>`; for `--local`, point `bundle:` at the local subdirectory and omit companion repo creation.
- Add exactly one discovery line to `CLAUDE.md` or `AGENTS.md`, preserving it without duplication on repeated init.
- Future resolution order is host project config `knowledge_repo`, then `.okf.yml`, then a clear error telling the user to run `/okf init`.

## `/okf open [--no-install] [--no-browser]`

Open the configured bundle in the local visual knowledge viewer.

- Resolve the bundle from `.okf.yml`; under Overdeck, the canonical resolver also honors the project's `knowledge_repo` setting.
- When `pan` is available, delegate to `pan knowledge open` and pass through `--no-install` and `--no-browser`.
- By default, an explicit open request progressively installs the separately licensed GPL-3.0 `@inkeep/open-knowledge` program. `--no-install` requires an existing `ok` binary instead.
- The viewer is an arm's-length subprocess served over HTTP. Overdeck launches it against a disposable snapshot, reuses healthy lock-reported processes, and never lets viewer edits touch the canonical PR-gated bundle.
- Never import, require, or bundle `@inkeep/open-knowledge` into the portable OKF scripts or Overdeck packages.

## `/okf author "<topic>"`

Write or update one concept for one idea.

- Infer exactly one concept ID and one concept type from `references/taxonomy.md`; confirm when the type or path is ambiguous.
- Use `templates/concept.md` and let the skill manage frontmatter. Include `type`, `title`, `description`, `tags`, and `timestamp` when available.
- Preserve unknown frontmatter keys on updates.
- Add relative or bundle-root links only when they point to real concepts or clearly planned knowledge.
- Run `reindex.py`, append a dated `log.md` entry, then run `validate.py --strict` before offering the change.

## `/okf convert <path>`

Convert existing docs into OKF without destructive edits.

- Start with a dry-run conversion plan that lists source path, target concept ID, inferred type, and whether a rename is proposed.
- Add frontmatter before renaming files.
- Apply renames only after explicit confirmation.
- Never delete or rename a README or source document.
- Preserve citations and convert wiki-style links where possible.
- After confirmed edits, run `reindex.py` and `validate.py --strict`.

## `/okf sync [--topic "<focus>"]`

Update the bundle from code or documentation diffs.

- Derive the change range from the last `log.md` entry, PR base, or user-specified diff.
- Create a knowledge-repo branch first; never write directly to the default branch.
- Map changed files and symbols to affected concepts by tags, concept IDs, links, and `search.py` results.
- Use `--topic "<focus>"` to restrict the candidate set by matching tags and search results; preserve non-matching concepts byte-identically.
- Update affected concepts, append exactly one dated `log.md` entry for the pass, regenerate indexes with `reindex.py`, and run `validate.py --strict`.
- Open the knowledge PR with `gh pr create`; do not push a direct default-branch update.
- If validation fails, fix the bundle before opening the PR.

## `/okf study "<focus>"`

Document what the current codebase does before a feature starts.

- Kebab-case the focus and tag produced concepts with it, for example `overtime-calculations`.
- Enumerate relevant code, tests, and docs before writing.
- Create or refresh one concept per idea that describes current behavior, invariants, and important decisions.
- Re-running study on unchanged evidence updates existing matching concepts in place; do not create duplicate concept files.
- Cite files, tests, docs, or commands used as evidence.
- Run `reindex.py`, append one dated `log.md` entry, run `validate.py --strict`, and open a knowledge-repo PR rather than mutating protected branches directly.

## `/okf retro`

Capture knowledge after implementation.

- Review the diff and available session context.
- Ask: what would have made this work easier if documented before the session?
- File those answers as focused concepts with citations to decisions, diffs, transcripts, or observations.
- Detect Overdeck only by checking whether `pan` is on `PATH` and responds; never import Overdeck code.
- With Overdeck present, mine issue observations with `pan memory search --issue <id> ... --json`.
- Without Overdeck, use `git diff` plus current transcript/session context as feedstock.
- Create or update concepts on a knowledge-repo branch, run `reindex.py` and `validate.py --strict`, then open a PR.

## `/okf extract "<query>" [--budget <tokens>]`

Return compact prompt context.

- Resolve this skill's installation directory from the loaded `SKILL.md`, then run `python3 <okf-skill-dir>/scripts/search.py "<query>" --bundle <bundle> --format prompt --budget <tokens>`. Never assume the caller's repository contains `skills/okf`.
- Rank by hybrid BM25 + vector search when indexes and shards exist.
- Fall back to BM25-only, then index-guided reading.
- Respect the token budget.
- Surface the retrieval tier (`hybrid`, `bm25-only`, `index-guided`, or `mnemos`).
- Include concept IDs as the citation anchors, and verify each cited ID exists in the bundle before using it as prompt context.
- If no cited concept answers the query, say what is missing instead of inventing an answer.

## `/okf validate [--strict]`

Run deterministic checks.

- Exit 0 when the bundle is conformant.
- Exit 1 for lint-only findings when not strict.
- Exit 2 for conformance errors.
- See `references/conformance.md` for the code vocabulary.

## `/okf lint`

Run advisory semantic patrol.

- Use `references/lint-prompt.md` as the prompt fixture.
- Surface contradictions, staleness, orphans, and oversized-concept split candidates from embedding `max_tokens`.
- Report advisory findings only; lint never gates merges and writes nothing without explicit confirmation.

## `/okf embed [--profile <name>]`

Refresh embeddings.

- Read `okf-embeddings.yaml` from the bundle root.
- Re-embed only concepts whose normalized content hash changed.
- Write sorted JSONL shards under `embeddings/`.
- Rebuild the local `.okf-index/` cache, which is derived and gitignored.