okf-creator

OKF Creator

Organize any input intoconforming to OKF v0.2 with body quality that passes musterknowledge bundle. OKF's hard requirements are extremely low (any Markdown with type is compliant), so the real value of this Skill is not in "producing compliant files" but in "producingunderstandable on reading, retrievable by agentsknowledge".

When to use

• Creating an OKF knowledge base from scratch;
• Generating knowledge documentation for a codebase / documentation site / data table;
• Organizing scattered notes, Wikis, PDF-extracted text into a concept library;
• Validating and repairing a bundle's OKF compliance.

Core principles (order matters)

1. Define boundaries first, then start. Ask clearly: what is the source of knowledge? Is the consumer a human or an agent? Which concepts need to be covered? Don't lay out directories right away.
2. One concept per file. The file path is the concept identity (concept ID). Organize by domain, not by file type.
3. Use structure in the body, not a running log. Prefer headings / lists / tables / code blocks. The spec only stipulates # Schema、# Examples、# Citations three headings—use them when applicable.
4. Link into a graph. Interconnect concepts with ordinary Markdown links; recommend in-bundle absolute paths /path/to/x.md。
5. Quality self-check. For each concept, ask yourself: can a person/agent with no context, reading only this one piece, put it to use? If not, supplement it.

Workflow

1. Sort out sources, list the concepts to capture (list first, then write).
2. Use scripts/scaffold_okf.py to generate the skeleton (root index.md + log.md + directories).
3. Write concept documents one by one: header info (type required) + structured body + cross-links + necessary # Citations。
4. Write / update the index.mdat each level (progressive disclosure) and the root log.md。
5. Use scripts/validate_okf.py <bundle> to validate, fix until 0 errors.

Header info specification

---
type: <必填,概念种类>      # 唯一硬要求
title: <显示名>
description: <一句话摘要>   # 强烈建议:索引/搜索靠它
resource: <底层资产 URI>   # 抽象概念可省略
tags: [<标签>, ...]
timestamp: <ISO 8601>
lang: zh                   # 本仓库 i18n 约定(可选扩展)
---

For detailed fields, reserved file names, and link rules, see references/okf-spec-cheatsheet.md。

Handling code / PDF / images (OKF native support is weak; supplement per this convention)

For background see docs/code-support-research-zh.md。

• Code:type use Repository|Package|Module|Class|Function|Interface|Config|Script|Notebook; add extension fields language、symbol、signature;resource use a GitHub permalink with a line-number anchor #L10-L40; for relation links use the calls: / depends-on: / deprecated-by: prefix. The body must include # Signature and behavior description, don't just paste code.
• PDF: place the original in assets/, the body carriesextracted text/tables,# Source note the page numbers.
• Images: place the original in assets/, write in the bodycaptions / OCR text(generated with a multimodal model), otherwise the knowledge in the image cannot be read by an agent.

Anti-patterns (don't do this)

• ❌ Cramming an entire document into one giant concept file;
• ❌ The body is all prose with no structure, so agents cannot retrieve the key points;
• ❌ Only pasting code without explaining behavior;
• ❌ Images directly ![](...) embedded and done, no captions written;
• ❌ Skip validate_okf.py。

companion scripts

• scripts/scaffold_okf.py — generate an empty bundle skeleton.
• scripts/validate_okf.py — OKF v0.2 compliance validation (can be used independently).

Related Skills

• awesome-to-okf — specifically converts GitHub awesome lists into OKF.
• book-to-okf — splits long articles / book manuscripts into an OKF concept library.
• okf-to-book — publishes an OKF bundle as a visualized documentation site.