produce: create or extend a bundle

When to use it

• The repo has no bundle yet and carries knowledge worth keeping: services, APIs, schemas, metrics, runbooks, decisions.
• The bundle exists but a whole new area belongs in it: a new service, a data pipeline, a set of decisions that so far live only in people's heads.
• "Document this in OKF" and "capture X as a concept" both route here.

What the agent does

Produce is the modelling verb, and most of it is judgment the CLI cannot make. The playbook keeps the steps short and defers the craft (granularity, choosing type, tag vocabulary, topology, links, citations) to the skill's authoring reference, which the agent reads before any non-trivial produce.

1. Pick the sources. Code (source files, READMEs, docstrings, config), existing docs or wiki pages (distilled into concepts, with the originals cited under a # Citations heading), or manual knowledge: the decisions, playbooks, and metrics that exist only in people's heads.
2. Choose a domain-based layout. Directories say what the knowledge is about (services/, datasets/, decisions/), never group by concept type. One concept per file, where a concept is the smallest unit of knowledge someone would link to or cite on its own.
3. Write each concept from the template. A descriptive type drawn from the bundle's existing vocabulary, recommended fields filled (title, description, tags, timestamp), and cross-links written into prose: the sentence around a link is what names the relationship, because links themselves are untyped on purpose. Before minting a tag, the agent runs okf tags and reuses the existing vocabulary first. The templates page shows the shapes it starts from.
4. Index and log. An index.md per directory, added or refreshed; the bundle root gets an index.md whose frontmatter carries only okf_version: "0.1"; and a dated entry lands in log.md.
5. Close out. Before calling the work done, the agent walks the closeout gate: every index enumeration matches reality (it re-runs okf index and checks each listing), log.md has its entry, timestamps are set, okf validate shows zero errors, and the cheap okf lint findings are cleared.

What stays with the agent throughout: deciding what is one concept versus two, what type vocabulary fits the bundle, which relationships deserve a link, and what is worth writing down at all. The CLI checks the result; it cannot make those calls.

Try it

In Claude Code with the okf plugin, run /okf:gem produce, or ask the skill in plain words:

Document the billing service in OKF: the API, the retry queue, and the decision to drop the legacy payment provider.

Pitfalls

• Do not restate what the code already says. A bundle that mirrors function signatures goes stale on the next commit and adds no knowledge. Capture the why, the cross-cutting relationships, the tradeoffs; link to the code for the rest.
• A new type per file makes type meaningless. The graph is grouped and colored by type, so a small reused vocabulary is what keeps it legible. Check what the bundle already uses before inventing one.
• No placeholder resource URIs. resource marks a concept that is a real, addressable asset, and it is what lets maintain find every concept a changed asset touches. On abstract concepts (a decision, a principle), omitting it is meaningful, not lazy.
• The closeout gate is not optional. Skipping the index re-check is how enumeration drift starts, and grep cannot find the entry that should be there but is not.