okf-wiki

okf-wiki: scaffold an Open Knowledge Format knowledge base

OKF (Open Knowledge Format) stores knowledge as small markdown files: one concept per file, each carrying its own provenance in YAML frontmatter, with directory index.md files for navigation and a validator that enforces the contract. It is built for knowledge bases that both people and agents read and edit, newsroom institutional memory, a research atlas, a team's decision log, an infrastructure map.

This skill scaffolds a conforming OKF project and validates it. The format contract is in spec/SPEC.md (in this skill's directory), read it before changing structure.

When to use

• The user wants to start an OKF knowledge base, atlas, or wiki.
• They want docs structured as one-concept-per-file with provenance, not prose pages.
• They want to "initialize OKF" in a repo, optionally publishing into its GitHub wiki.

Start here: scope the wiki with the user

Before you scaffold anything, settle four things with the user. They shape what gets created and how it is published, and they are awkward to retrofit once concepts exist. Ask with AskUserQuestion rather than in prose, in two steps: the first three questions in one call, then the publish question as a follow-up call only if the audience came back public or both (it does not apply to an internal-only wiki, and its relevant options depend on that answer, so it cannot share the first batch). Infer the title from the repo or project and confirm it. Skip any question the user already answered in their request, do not re-ask what they have told you.

1. Audience, who reads this wiki? This answer sets the others:
   • Internal (agents and teammates): the orientation hooks earn their keep, so keep them on. The bundle may hold infrastructure detail, so it usually lives in a private repo. The in-repo bundle/ is the source of truth.
   • Public (people browsing): readability and secret-scrubbing come first; the hooks matter less, since people read it and agents do not. Plan a published view (see Publish below).
   • Both: the in-repo bundle/ is the source of truth with hooks on for agents, plus a published view for people. Default here when the user is unsure.
2. Title and sections, the knowledge-base title (infer it, then confirm) and the starting sections. Offer sections as a use-case preset, not a blank prompt:
   • Newsroom institutional memory: people, orgs, sources, decisions, beats
   • Research atlas: concepts, sources, methods, findings
   • Infrastructure or fleet map: machines, services, networks, credentials, processes
   • Decision log: decisions, context, events The chosen title and list feed --title and --sections below; the user can edit the list.
3. Populate now or later, author concepts now from existing material (a repo, docs, notes, or a URL: gather it and enter the authoring loop after scaffolding), or scaffold an empty tree the user fills in later.
4. Publish target, a follow-up AskUserQuestion call, made only after the audience comes back public or both (skip it entirely for an internal-only wiki):
   • In-repo bundle only (default): the validator and relative links work directly, with no extra surface to maintain. Right for most wikis.
   • GitHub wiki: an optional reading surface. Advanced and manual, see "Optional: publish into a GitHub wiki" below, bootstrapped with scripts/gh-wiki-bootstrap.py.
   • GitHub Pages: a browsable site rendered from the bundle. Not built yet, treat it as a goal and keep the in-repo bundle as the source of truth.