OKF：把研究资料写成 Agent 也能读的知识包

知识包 = 目录树 + Markdown 文件 + 少量 frontmatter 约定

my_bundle/
├── index.md
├── datasets/
│   ├── index.md
│   └── sales.md
└── tables/
    ├── index.md
    ├── orders.md
    └── customers.md

---
type: BigQuery Table          # 必需：概念种类，用于过滤/展示
title: Customer Orders        # 推荐：展示名；缺了可从文件名推
description: One row per completed order.  # 推荐：一句话；index 会直接引用
resource: https://...         # 推荐：底层资产 URI；纯抽象概念可没有
tags: [sales, orders]         # 推荐：横切分类
timestamp: 2026-05-28T14:30:00Z  # 推荐：ISO 8601
# 其余键自由扩展；消费者应保留未知键
---

ga4/
├── index.md
├── datasets/ga4_obfuscated_sample_ecommerce.md
├── tables/events_.md
└── references/
    ├── metrics/user_count.md      # 一句话 + SQL + Citations
    └── joins/events___ads_clickstats.md

research/<topic>/
├── index.md
├── log.md
├── topic.md
├── questions/
├── claims/
├── sources/
├── concepts/
├── routes/
├── experiments/
└── gaps/

---
name: okf-generator
description: Use when the user wants to create, expand, or normalize an Open Knowledge Format (OKF) bundle for research notes, domain knowledge, data catalogs, or agent-readable context. Generates conformant markdown+YAML knowledge packages with concepts, indexes, links, and citations.
---

# OKF Generator

## Overview

Produce or refine an **Open Knowledge Format (OKF) v0.1** knowledge bundle: a directory of markdown files with YAML frontmatter, cross-links, progressive `index.md` files, and optional `log.md`.

OKF is vendor-neutral. Anyone can author it; anyone can consume it (`cat`, git, Obsidian, LLM context, static hosting). This skill is a **producer**. Prefer small, concrete concept docs over monolithic notes.

**Spec anchors (keep behavior aligned):**

- Required frontmatter key: `type`
- Recommended: `title`, `description`, `resource`, `tags`, `timestamp`
- Reserved filenames: `index.md`, `log.md` (never use as concepts)
- Concept ID = path relative to bundle root without `.md`
- Broken links are allowed; invented facts are not

## When to use

- User asks to turn research / notes / a repo / a dataset into an OKF bundle
- User wants agent-readable domain knowledge for later sessions
- User wants to restructure messy markdown into linked concepts
- User mentions OKF, knowledge bundle, knowledge catalog format, or “open knowledge format”

## Inputs to collect (ask only if missing)

1. **Topic / domain** — one sentence
2. **Output path** — default `./okf-bundle/<slug>/` if unspecified
3. **Source material** — files, URLs, repos, chat notes, or “from scratch”
4. **Audience** — personal research | team wiki | agent context | data catalog
5. **Scope non-goals** — what not to include this round

If the user only gives a topic, proceed with a minimal skeleton + a short `gaps/` list of what still needs sources.

## Core workflow

### Phase 0 — Decide bundle shape

Create a root directory. Choose a layout by audience:

**A. Personal research (default)**

```text
<bundle>/
├── index.md
├── log.md
├── topic.md
├── questions/
├── claims/
├── sources/
├── concepts/
├── routes/          # optional: schools of thought / approaches
├── experiments/     # optional: trials you actually ran
├── playbooks/       # optional: procedures
├── gaps/
└── references/      # optional: multi-cited appendices
```

**B. Software / system domain**

```text
<bundle>/
├── index.md
├── log.md
├── overview.md
├── components/
├── apis/
├── decisions/       # ADRs as concepts
├── runbooks/
├── sources/
└── gaps/
```

**C. Data catalog style**

```text
<bundle>/
├── index.md
├── datasets/
├── tables/
├── metrics/
├── joins/
└── references/
```

Do not invent a deep taxonomy on day one. Prefer 3–7 top-level groups.

### Phase 1 — Inventory concepts

From sources, list candidate concepts before writing files.

For each candidate capture:

| Field | Rule |
|-------|------|
| working title | human-readable |
| proposed `type` | short descriptive string |
| one-line description | max ~25 words; will feed `index.md` |
| source pointers | URLs / paths that justify it |
| links to | other concept IDs it should reference |

**Split rules**

- One primary idea per file
- If a section needs its own citations and inbound links from ≥2 docs, promote it to a concept
- Overviews, FAQs, changelogs, marketing pages: usually **do not** become standalone reference concepts; fold useful facts into existing docs or skip

**Skip / gap rules**

- No source → either omit or create `gaps/<slug>.md` stating what is unknown
- Never fabricate schema fields, metrics SQL, paper results, or URLs

### Phase 2 — Write concept documents

Every concept file:

```markdown
---
type: <Type>
title: <Display name>
description: <One sentence summary>
resource: <Optional canonical URI>
tags: [tag1, tag2]
timestamp: <ISO 8601 Z>
---

<prose>

# Optional conventional sections
```

#### Frontmatter rules

| Key | Required | Guidance |
|-----|----------|----------|
| `type` | yes | Stable within the bundle. Examples below |
| `title` | strongly recommended | Display name; if omitted consumers may use filename |
| `description` | strongly recommended | **Exactly one sentence.** Used verbatim in indexes |
| `resource` | when bound to an asset | Dataset URI, paper DOI/URL, repo URL, API path. Abstract ideas may omit |
| `tags` | recommended | Short, searchable; merge on updates, don’t silently drop |
| `timestamp` | recommended | ISO 8601; update on meaningful change |
| extensions | allowed | Preserve unknown keys on round-trip |

**Suggested `type` values**

Personal research: `Topic`, `Question`, `Claim`, `Source`, `Concept`, `Route`, `Experiment`, `OpenGap`, `Playbook`, `Reference`

Systems: `Component`, `API`, `Decision`, `Runbook`, `Service`, `Reference`

Data: `BigQuery Dataset`, `BigQuery Table`, `Metric`, `Join`, `Reference`

Consumers must tolerate unknown types — pick descriptive names over empty generics when possible.

#### Body rules

Order for most docs:

1. Short prose (1–3 paragraphs): what it is, grain/scope, caveats
2. Structured sections as needed (`# Schema`, `# Evidence`, `# Counterevidence`, `# Examples`, `# Steps`, …)
3. `# Citations` last when claims need backing

Style:

- Concrete names > vague praise
- Prefer headings, lists, tables, fenced code
- No preamble, apologies, or chain-of-thought in the body
- Body must be directly consumable by a human or downstream agent

#### Type-specific body patterns

**Topic**

- Boundary, non-goals, core questions, success criteria for the research

**Question**

- Why it matters, current answer status (`open` / `partial` / `answered`), links to claims & sources

**Claim**

- Statement in one sentence (prefer conditional judgments: “under X, Y”)
- Evidence bullets with links to `sources/` or external citations
- Counterevidence / limits
- Confidence note only if grounded (e.g. “single secondary source”)

**Source**

- What it is, author/org, date, why it matters for this bundle
- Key takeaways (bullets)
- Limitations (bias, age, scope)
- `resource` = canonical URL

**Concept**

- Definition, mechanism, comparison to neighbors
- Optional glossary table

**Route**

- Problem framing, key mechanism, trade-offs, representative examples

**Experiment**

- Setup, steps, observed result, artifacts paths, what it does/doesn’t prove

**OpenGap**

- What is unknown, why it blocks, how one might close it

**Playbook**

- Trigger, steps, verification, rollback/failure notes

**Reference** (multi-cited appendix)

- Only mint if **all** hold:
  1. Referenceable by name from primary docs
  2. Not bundle-level meta (overview / quickstart / FAQ / changelog)
  3. You can write: “See the [X reference](…) for …” with X a concrete noun
  4. ≥2 concepts benefit, OR one concept needs load-bearing background that doesn’t fit inline
- When in doubt, **skip** or fold into an existing doc

**Table / schema-like**

- `# Schema` must reflect real metadata only
- Optional `# Common query patterns` with real examples
- Do not invent columns

### Phase 3 — Cross-linking

- Link when prose naturally names another concept
- Prefer **file-relative** links so GitHub and local browsing work:
  - sibling: `[orders](orders.md)`
  - parent: `[sales dataset](../datasets/sales.md)`
  - reference: `[user count](../references/metrics/user_count.md)`
- Absolute bundle-root links (`/tables/orders.md`) are OKF-legal; use only if the target environment resolves them
- One link per concept mention per section is enough
- Do not link from headings, code blocks, or raw schema field lists
- Do not self-link
- Only link to concepts that exist (or will exist in this same write pass)
- Broken links to future work are acceptable if intentional; prefer a `gaps/` doc for known holes

### Phase 4 — Indexes and log

#### `index.md` (any directory)

- **No frontmatter** at non-root levels
- Root `index.md` MAY include frontmatter only for `okf_version: "0.1"`
- Structure:

```markdown
# Section name

* [Title](path.md) - description from frontmatter
* [Subdir](subdir/) - one-sentence summary of the group
```

- Descriptions SHOULD come from each concept’s `description`
- Generate indexes bottom-up after concepts exist
- If a directory has a single child, still add index for stable navigation

#### `log.md` (optional but recommended for multi-session research)

```markdown
# Update Log

## YYYY-MM-DD
* **Creation**: …
* **Update**: …
* **Deprecation**: …
```

Newest date first. Bold lead word is convention, not required.

### Phase 5 — Conformance check

Before finishing, verify:

- [ ] Every non-reserved `.md` has parseable YAML frontmatter
- [ ] Every frontmatter has non-empty `type`
- [ ] Every concept has a tight one-sentence `description` when practical
- [ ] No concept uses filename `index.md` or `log.md`
- [ ] Relative links resolve for files written in this pass
- [ ] No invented URLs, fields, metrics, or paper results
- [ ] `index.md` files list real children with useful descriptions
- [ ] Claims that assert facts have `# Citations` or links to `sources/`
- [ ] Gaps are explicit documents or clearly marked — not silent omission presented as certainty

### Phase 6 — Handoff

Return to the user:

1. Bundle root path
2. Concept count by `type`
3. How to browse: open root `index.md`, or drag into Obsidian, or feed selective files to an agent
4. Suggested next enrichment steps (which `gaps/` to close first)
5. Optional: command ideas for visualization / packaging (zip, git init) — do not require Google tooling

## Update / enrich existing bundles

When a bundle already exists:

1. Read target concept with full frontmatter + body
2. Treat existing structure as source of truth
3. **Augment, don’t rewrite**:
   - Preserve all existing frontmatter keys/values unless improving `description` or merging `tags`
   - Keep every existing top-level `#` heading and order; you may extend under them or append new headings after
   - For schema-like sections populated from real metadata: never drop fields
   - Put new external URLs in `# Citations`, not overwriting `resource` unless the asset identity truly changed
4. Refresh `timestamp` on meaningful edits
5. Append `log.md` entry
6. Regenerate affected `index.md` descriptions if titles/descriptions changed

## Progressive disclosure for agents consuming the bundle

When **using** a bundle (not only writing one):

1. Start at root `index.md`
2. Open only directories relevant to the current question
3. Read leaf concepts last
4. Prefer citing concept IDs in answers so humans can open the same files
5. Do not dump the entire bundle into context if indexes exist

## Quality bar (what “good OKF” means)

| Good | Bad |
|------|-----|
| Small concepts with stable IDs | One 8k-line `notes.md` |
| Conditional claims + citations | Orphan opinions with no source |
| Indexes that enable skimming | Directory full of files, no map |
| Explicit `gaps/` | Confident prose hiding unknowns |
| Relative links that browse on GitHub | Links that only work in one proprietary app |
| Types stable within the bundle | Random type strings each file |

## Common mistakes

| Mistake | Fix |
|---------|-----|
| Putting overview/tutorial pages into `references/` | Skip or extract only named metrics/enums/defs |
| Rewriting entire docs on each enrichment | Augment in place; preserve headings & schema |
| Multi-sentence `description` | Compress to one sentence for indexes |
| Using `index.md` as a concept | Move content to `overview.md` or `topic.md` |
| Inventing SQL/metrics from memory | Quote only from provided sources; else `gaps/` |
| Absolute `/...` links on GitHub-first bundles | Prefer file-relative links |
| Tags replaced wholesale | Union old ∪ new |
| No citations on strong claims | Add `# Citations` or demote to `OpenGap` |

## Minimal examples

### Claim

```markdown
---
type: Claim
title: File-based knowledge beats chat memory for multi-week research
description: Multi-week research stays reviewable when claims live as versioned files with citations.
tags: [research-method, okf]
timestamp: 2026-07-20T00:00:00Z
---

Under multi-week personal research, storing claims as individual markdown concepts with citations is more recoverable than leaving judgments in chat transcripts.

# Evidence

- Chat transcripts lack stable IDs and line-level review.
- Git diffs make claim edits explicit over time.
- See [Open Knowledge Format](../sources/okf-spec.md).

# Limits

- High authoring cost for throwaway questions.
- Requires discipline to split concepts.

# Citations

[1] [OKF SPEC inspiration](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
```

### Source

```markdown
---
type: Source
title: GoogleCloudPlatform/knowledge-catalog OKF
description: Upstream OKF v0.1 draft and reference agent for markdown knowledge bundles.
resource: https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf
tags: [okf, primary-source]
timestamp: 2026-07-20T00:00:00Z
---

Upstream repository defining Open Knowledge Format and shipping a BigQuery + web enrichment reference agent.

# Key takeaways

- Bundle = directory of md + YAML frontmatter
- Only `type` is strictly required
- Designed for both humans and agents without SDKs

# Limitations

- Official samples focus on BigQuery-shaped catalogs
- Format is still v0.1 draft
```

### Root index

```markdown
---
okf_version: "0.1"
---

# Overview

* [Topic](topic.md) - Research boundary and core questions for OKF personal use.

# Groups

* [claims](claims/) - Conditional judgments with evidence.
* [sources](sources/) - Primary and secondary materials.
* [gaps](gaps/) - Known unknowns still blocking confidence.
```

## Execution checklist

Copy and track:

```text
OKF generation
- [ ] Scope + non-goals confirmed
- [ ] Bundle root created
- [ ] Concept inventory listed (title/type/description/sources)
- [ ] Concept files written (frontmatter + body)
- [ ] Cross-links added
- [ ] index.md generated per directory
- [ ] log.md started/updated
- [ ] Conformance check passed
- [ ] Handoff summary returned
```

## Non-goals

- Replacing enterprise catalog services (governance, ACL, lineage queries)
- Mandating a global taxonomy of types
- Requiring Gemini / BigQuery / GCP credentials
- Building a visualizer (optional; out of scope unless user asks)