okf

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Open Knowledge Format (OKF) skill

Open Knowledge Format（OKF）技能

OKF represents knowledge as a directory of markdown files with YAML frontmatter. It is minimal by design: no schema registry, no runtime, no SDK. Your job is to produce, maintain, and consume OKF bundles conformant with the spec, not your memory of it.

Always read the canonical spec before non-trivial work: reference/SPEC.md. It is the verbatim OKF v0.2 specification and the source of truth for every rule below.

OKF将知识表示为包含YAML前置元数据的markdown文件目录。它在设计上力求极简：无需模式注册表、无需运行时、无需SDK。你的工作是创作、维护和使用符合规范的OKF知识包，而非依赖你对规范的记忆。

在开展重要工作前务必阅读官方规范： reference/SPEC.md。这是OKF v0.2规范的原文，是以下所有规则的唯一权威来源。

The one hard rule

唯一硬性规则

A bundle is conformant (§11) iff: every non-reserved

.md

file has a parseable YAML frontmatter block, and every such block has a non-empty
type
field. Everything else is soft guidance. Consumers MUST tolerate missing optional fields, unknown types, and broken links — never reject a bundle over them.

一个知识包符合规范（§11）的前提是：所有非保留的

.md

文件都包含可解析的YAML前置元数据块，且每个元数据块都有一个非空的
type
字段。其余所有要求均为软性指导。消费者必须容忍缺失的可选字段、未知类型和失效链接——绝不能因这些问题拒绝整个知识包。

Conventions to apply

需遵循的约定

One concept = one file. The file path (minus
```
.md
```
) is the concept ID.
Frontmatter:
```
type
```
is required. Add
```
title
```
,
```
description
```
,
```
tags
```
when they aid consumption; add
```
resource
```
(a canonical URI) only for concepts bound to a real asset — omit it for abstract concepts.
Body: prefer structural markdown (headings, tables, lists, fenced code). Conventional headings:
```
# Schema
```
,
```
# Examples
```
,
```
# Computation
```
.
Cross-links: standard markdown links; prefer absolute bundle-relative form (
```
/services/auth-api.md
```
). A link asserts a relationship; its kind lives in the surrounding prose, not the link.
Reserved files:
```
index.md
```
(directory listing, no frontmatter — except the bundle-root index may carry only
```
okf_version
```
) and
```
log.md
```
(ISO-dated change history, newest first). Never use these names for concepts.

一个概念对应一个文件。文件路径（去掉
```
.md
```
后缀）即为概念ID。
前置元数据：
```
type
```
为必填项。当有助于内容消费时添加
```
title
```
、
```
description
```
、
```
tags
```
；仅当概念绑定到实际资产时添加
```
resource
```
（标准URI）——抽象概念无需添加该字段。
正文：优先使用结构化markdown（标题、表格、列表、代码块）。推荐使用的常规标题：
```
# Schema
```
、
```
# Examples
```
、
```
# Computation
```
。
交叉链接：使用标准markdown链接；优先采用相对于知识包的绝对路径形式（
```
/services/auth-api.md
```
）。链接仅用于声明关联关系；关联类型需在链接周围的文本中说明，而非嵌入链接本身。
保留文件：
```
index.md
```
（目录列表，无前置元数据——仅知识包根目录的
```
index.md
```
可包含
```
okf_version
```
字段）和
```
log.md
```
（ISO日期格式的变更历史，最新记录在前）。切勿将这些名称用于概念文件。

The v0.2 families (all optional, all worth filling)

v0.2版本的可选字段组（建议全部填写）

Trust (§5.2):
```
generated: { by, at }
```
— who produced the current content and when.
```
verified: [{ by, at }]
```
— who confirmed it since (a bare mapping is one entry). Write
```
by
```
in the actor convention (§7):
```
<producer>/<version>
```
for an agent,
```
human:<id>
```
for a person,
```
process:<id>
```
for an automated job. Use
```
human:
```
whenever a person authored or signed off — consumers key trust tiers off that prefix.
Lifecycle (§5.4–5.5):
```
status: draft|stable|deprecated
```
(absent means stable) and
```
stale_after: YYYY-MM-DD
```
, an absolute date, not a TTL.
Provenance (§5.1):
```
sources: [{ id, resource, title, author, usage_count, last_modified }]
```
— the materials the concept derives from.
```
resource
```
is required per entry and may be a URL, a bundle path, or a scope descriptor. Attribute a specific claim with a markdown footnote whose label is the source's
```
id
```
:
```
…sharded daily.[^ga4-schema]
```
plus a
```
[^ga4-schema]: …
```
definition. The label is the join key — it must match a
```
sources[].id
```
.
Attestation (§10): a sanctioned computation is its own concept,
```
type: Attested Computation
```
, carrying
```
runtime
```
(required),
```
parameters
```
,
```
executor
```
,
```
attester
```
, and the computation itself under
```
# Computation
```
(or a
```
computation:
```
path). Concepts that need the value link to it. Never inline a number's SQL into the concept that narrates it.

Reading a v0.1 bundle? Two constructs were superseded (§13.1):

timestamp

is now

generated.at

, and a body

# Citations

list is now

sources

. Read both, write v0.2 — and when you touch a legacy concept in maintain mode, migrate its frontmatter as part of the edit. The validator warns on both.

Templates to copy: concept, index, log.

可信度（§5.2）：
```
generated: { by, at }
```
——当前内容的创作者及创作时间。
```
verified: [{ by, at }]
```
——此后确认该内容的人员及时间（单个映射表示一条记录）。
```
by
```
需遵循参与者约定（§7）：Agent填写
```
<producer>/<version>
```
，个人填写
```
human:<id>
```
，自动化任务填写
```
process:<id>
```
。只要是由人员创作或签署确认的内容，均需使用
```
human:
```
前缀——消费者会以此区分不同的信任等级。
生命周期（§5.4–5.5）：
```
status: draft|stable|deprecated
```
（未填写则默认表示stable）和
```
stale_after: YYYY-MM-DD
```
，为绝对日期，而非相对时长。
来源（§5.1）：
```
sources: [{ id, resource, title, author, usage_count, last_modified }]
```
——概念所依据的素材。每个条目必须包含
```
resource
```
，其值可以是URL、知识包路径或范围描述符。使用markdown脚注标注特定声明的来源，脚注标签需与来源的
```
id
```
匹配：
```
…每日分片。[^ga4-schema]
```
，并添加
```
[^ga4-schema]: …
```
的定义。标签作为关联键，必须与
```
sources[].id
```
完全一致。
认证（§10）：经批准的计算过程本身作为一个概念，
```
type: Attested Computation
```
，需包含
```
runtime
```
（必填）、
```
parameters
```
、
```
executor
```
、
```
attester
```
字段，计算过程本身放在
```
# Computation
```
章节下（或通过
```
computation:
```
路径指定）。需要使用该计算结果的概念需链接到这个概念。切勿将数值对应的SQL语句直接嵌入描述该数值的概念中。

正在读取v0.1版本的知识包？ 有两个结构已被替代（§13.1）：

timestamp

现已改为

generated.at

，正文的

# Citations

列表现已改为

sources

字段。读取时兼容这两种格式，但编写时需使用v0.2版本——当在维护模式下处理遗留概念时，需将其前置元数据迁移至v0.2版本作为编辑工作的一部分。验证器会对这两种情况发出警告。

可复制的模板：concept、index、log。

Default bundle location

默认知识包位置

Use

.okf/

at the repository root unless the project already uses another location. Commit it alongside the code it describes — knowledge as code.

除非项目已使用其他位置，否则请将知识包放在仓库根目录的

.okf/

文件夹中。将其与所描述的代码一同提交——实现知识即代码。

Modes

操作模式

produce — create or extend a bundle

produce — 创建或扩展知识包

Starting a brand-new bundle? Use the init fast-path instead of hand-writing the first files — it scaffolds a conformant

index.md

log.md

, and a

getting-started.md

concept with full recommended frontmatter in one shot:

bash

uv run "${CLAUDE_SKILL_DIR}/scripts/okf_init.py" <target-dir> [--title "..."]

It refuses to touch a directory that already has

.md

files unless

--force

is given. Then extend it:

Read reference/SPEC.md.
Pick the source(s): code (derive concepts from source, READMEs, docstrings, config), docs/wiki (distill pages into concepts, record the originals in
```
sources
```
), manual (decisions, playbooks, metrics).
Choose a directory layout by domain (e.g.
```
services/
```
,
```
datasets/
```
,
```
decisions/
```
). One concept per file.
Write each concept from templates/concept.md: set a descriptive
```
type
```
, fill recommended fields, record
```
generated
```
and the
```
sources
```
you actually read, cross-link related concepts.
Add/refresh
```
index.md
```
per directory (and
```
okf_version: "0.2"
```
in the root index). Append a dated entry to
```
log.md
```
.
Validate (see below). Fix every error before finishing.

从零开始创建新的知识包？ 使用初始化快捷方式而非手动编写初始文件——它会一次性生成符合规范的

index.md

、

log.md

，以及包含完整推荐前置元数据的

getting-started.md

概念文件：

bash

uv run "${CLAUDE_SKILL_DIR}/scripts/okf_init.py" <target-dir> [--title "..."]

如果目标目录已包含

.md

文件，该脚本会拒绝执行，除非添加

--force

参数。之后按以下步骤扩展知识包：

阅读reference/SPEC.md。
选择来源：代码（从源代码、README、文档字符串、配置中提炼概念）、文档/维基（将页面浓缩为概念，并在
```
sources
```
中记录原始来源）、手动输入（决策记录、操作手册、指标）。
按领域选择目录结构（例如
```
services/
```
、
```
datasets/
```
、
```
decisions/
```
）。一个概念对应一个文件。
基于templates/concept.md编写每个概念：设置描述性的
```
type
```
字段，填写推荐字段，记录
```
generated
```
信息及实际参考的
```
sources
```
，添加相关概念的交叉链接。
更新每个目录下的
```
index.md
```
（根目录的
```
index.md
```
需包含
```
okf_version: "0.2"
```
）。在
```
log.md
```
中添加一条带日期的记录。
进行验证（见下文）。完成前需修复所有错误。

maintain — keep a bundle in sync with reality

maintain — 保持知识包与实际情况同步

Identify which concepts the change affects (search by
```
resource
```
, path, or topic). This bookkeeping is exactly what agents are good at — touch every affected file in one pass.
Update the body and
```
generated.at
```
(with your own actor in
```
generated.by
```
); fix or add cross-links; create new concepts for new assets; mark removed assets
```
status: deprecated
```
and note the deprecation in
```
log.md
```
rather than silently deleting context. Facing a whole v0.1 bundle rather than a stray field? Do not hand-edit it — run the validator's
```
--migrate
```
once.
Update the relevant
```
index.md
```
files and append a dated
```
log.md
```
entry describing what changed.
Validate.

确定变更影响的概念（按
```
resource
```
、路径或主题搜索）。这类记录工作正是Agent擅长的——一次性处理所有受影响的文件。
更新正文内容和
```
generated.at
```
（将自己的参与者标识填写到
```
generated.by
```
中）；修复或添加交叉链接；为新资产创建新的概念；将已移除的资产标记为
```
status: deprecated
```
，并在
```
log.md
```
中记录 deprecation 信息，而非直接删除相关上下文。如果面对的是整个v0.1版本的知识包而非单个零散字段？请勿手动编辑——只需运行验证器的
```
--migrate
```
命令一次即可完成迁移。
更新相关的
```
index.md
```
文件，并在
```
log.md
```
中添加一条带日期的记录，描述变更内容。
进行验证。

consume — use a bundle as context

consume — 将知识包作为上下文使用

Read the bundle-root
```
index.md
```
first for progressive disclosure, then follow links only into the concepts relevant to the task.
Weigh what you read:
```
status: draft
```
/
```
deprecated
```
, a
```
stale_after
```
already past, or no
```
verified
```
entry all mean "check before relying on this". Treat broken links as not-yet-written knowledge, not errors.
Need a number an
```
Attested Computation
```
covers? Run its computation with values bound to the declared
```
parameters
```
— never write your own query.
If you learn something durable while working, switch to maintain and write it back.

首先阅读知识包根目录的
```
index.md
```
以逐步了解内容，然后仅访问与任务相关的概念链接。
评估所读取内容的可靠性：
```
status: draft
```
/
```
deprecated
```
、
```
stale_after
```
日期已过，或无
```
verified
```
记录均意味着“依赖前需核实”。将失效链接视为尚未编写的知识，而非错误。
需要
```
Attested Computation
```
中包含的数值？使用声明的
```
parameters
```
绑定的值运行该计算过程——切勿自行编写查询语句。
如果在工作过程中获得了可复用的知识，请切换到maintain模式并将其写回知识包。

Validation (do this before declaring done)

验证（完成前务必执行）

Never eyeball conformance — run the deterministic checker. Invoke the companion validate
skill (

/okf:validate <bundle-dir> --strict

), which ships the checker. If that skill is not installed, run it directly:

bash

uv run "${CLAUDE_SKILL_DIR}/../validate/scripts/okf_validate.py" <bundle-dir> --strict

Resolve every

ERROR

(hard §11 failures). Warnings are soft; fix them when cheap, but they never block.

切勿仅凭肉眼判断是否符合规范——请运行确定性检查工具。调用配套的**

validate

**技能（

/okf:validate <bundle-dir> --strict

），该技能内置了检查工具。如果未安装该技能，可直接运行以下命令：

bash

uv run "${CLAUDE_SKILL_DIR}/../validate/scripts/okf_validate.py" <bundle-dir> --strict

解决所有

ERROR

（违反§11的硬性规则）。警告为软性提示；如果修复成本低则进行修复，但警告不会阻碍工作完成。