# Kb Compile

> Incrementally compile tracked raw captures into reviewable draft knowledge. Use this skill whenever the user says "compile wiki", "compile kb", "sync drafts", "digest these captures", "turn my clips into drafts", "编译wiki", "更新草稿层", "同步草稿", or wants tracked material under `raw/human/**`, `raw/agents/{role}/**`, bootstrap `raw/*.md`, `raw/**/assets/*`, or `raw/**/data/*` turned into reviewable summaries, topics, concepts, entities, and draft indices. This is also the right skill when Chinese-LLM-Wiki wording such as `来源页`, `主题页`, `实体页`, `综合页草稿`, `整理成来源页`, `补主题页`, or `补实体页草稿` clearly means “build draft pages from raw evidence first.” Do not treat `raw/**/papers/*.pdf` as a normal compile trigger: those paper ingests still belong to `paper-workbench`, and `kb-compile` should only surface or defer them.

- Skill: `bahayonghang/kb-compile` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bahayonghang/kb-compile`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bahayonghang/kb-compile/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: bahayonghang (https://skillmd.com/u/bahayonghang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bahayonghang/kb-compile

---


# KB Compile

Incrementally turn immutable raw captures into reviewable draft knowledge.

In Karpathy's pattern, this is where "the LLM reads it, extracts the key information, and integrates it into the existing wiki — updating entity pages, revising topic summaries, noting where new data contradicts old claims." A single source might touch 10-15 wiki pages. In this contract, compile shapes candidates for the review gate rather than writing directly to the live brain.

## Minimal loop

1. detect new or changed captures
2. compile them into reviewable summaries, topics, concepts, entities, relationships, and indices
3. apply the default `浓缩 -> 质疑 -> 对标` compile method
4. surface conflicts, alias overlap, duplicate risk, and hub candidates
5. hand the package to `kb-review`

## When this compounds the wiki

`kb-compile` is where raw evidence first becomes reusable structure. Good compile work should reduce future rediscovery by turning captures into durable draft packages and by surfacing where the graph needs better links, syntheses, or hubs.

## When not to promote

Compile shapes candidates. It does not approve truth and it should not bypass review just because a draft looks strong.

## Read before compiling

Read these files first:

- local `AGENTS.md`
- local `CLAUDE.md` if present
- `../obsidian-notes-karpathy/scripts/skill-contract-registry.json`
- `../obsidian-notes-karpathy/references/file-model.md`
- `../obsidian-notes-karpathy/references/compile-method.md`
- `../obsidian-notes-karpathy/references/draft-schema.md`
- `../obsidian-notes-karpathy/references/summary-template.md`

Treat `skill-contract-registry.json` as the canonical source for required references, baseline command, and allowed write surfaces.

If `onkb` is available, run `onkb --json compile scan <vault-root>` first.

If `onkb` is missing, follow the install fallback in `../obsidian-notes-karpathy/references/lifecycle-matrix.md`, then rerun the same command.

## Load on demand

Load these only when the trigger applies:

- `../obsidian-notes-karpathy/references/lifecycle-matrix.md` — when `onkb` is missing (install fallback) or a stage handoff is unclear
- `../obsidian-notes-karpathy/references/schema-template.md` — when vault-wide frontmatter fields beyond this skill's core schema need checking
- `../obsidian-notes-karpathy/references/concept-template.md` — when shaping concept drafts
- `../obsidian-notes-karpathy/references/entity-template.md` — when shaping entity drafts
- `../obsidian-notes-karpathy/references/activity-log-template.md` — when appending an entry to `wiki/log.md`
- `../obsidian-notes-karpathy/references/provenance-and-alias-policy.md` — when alias overlap, duplicate candidates, or provenance drift surfaces
- `../obsidian-notes-karpathy/references/paper-ingestion-lifecycle.md` — when `raw/**/papers/*.pdf` appears in scans or plans
- `../obsidian-notes-karpathy/references/memory-lifecycle.md` — when `MEMORY.md` or episodic memory boundaries are involved
- `../obsidian-notes-karpathy/references/graph-contract.md` — when graph exports, `related` edges, or relationship candidates are involved
- `../obsidian-notes-karpathy/references/source-manifest-contract.md` — when `raw/_manifest.yaml` fields or manifest anomalies are involved
- `../obsidian-notes-karpathy/references/topic-template.md` — when shaping or promoting browse-layer topic pages
- `../obsidian-notes-karpathy/references/procedure-template.md` — when the durable delta is procedural (workflow or playbook)

## Non-negotiable rules

- do not rewrite `raw/`
- write only to `wiki/drafts/` and draft indices, plus the single writeback exception below
- the writeback lane may advance `writeback_status` (and add the `writeback_draft` pointer) in `outputs/qa/**` and `outputs/content/**` frontmatter; it must not mutate any other archive content
- never promote directly into `wiki/live/`
- keep human captures and agent captures distinguishable in provenance
- keep PDF paper handling strict: `raw/**/papers/*.pdf` still routes through `paper-workbench`
- prefer tracked sources from `raw/_manifest.yaml` when it is present

## Source discovery

Accept:

- markdown captures under `raw/human/**`
- markdown captures under `raw/agents/{role}/**`
- markdown captures directly under `raw/` in bootstrap vaults
- image assets under `raw/**/assets/*`
- data assets under `raw/**/data/*`
- legacy-layout markdown captures under older paths only during migration
- paper PDFs under any `papers/` subtree inside raw
- archived writeback candidates under `outputs/qa/**` and `outputs/content/**`, only when `writeback_status: pending` and `followup_route: draft`, through the writeback lane below

## Writeback lane

`pending -> drafted` is owned by the deterministic writeback lane:

```
onkb --json compile writeback <vault-root> [--write]
```

- dry-run first: the report classifies every archived artifact as `eligible` or `skipped` with a reason; `triaged`, `rejected`, and `followup_route: review` artifacts are never picked up
- `--write` scaffolds one draft per eligible artifact under `wiki/drafts/summaries/writeback/`, writes its review package under `wiki/drafts/indices/packages/writeback/`, advances the artifact to `writeback_status: "drafted"` with a `writeback_draft` pointer, and appends a `compile_writeback` audit event
- the archived artifact is the trigger, not a truth source: the scaffold's `compiled_from` / `capture_sources` ground in the artifact's `source_live_pages` (approved pages or raw evidence), and the artifact itself is only referenced through `writeback_source`
- after scaffolding, refine the draft with the normal `浓缩 -> 质疑 -> 对标` method — distill the durable delta, split concept/entity/topic drafts when warranted — and hand the package to `kb-review`; the scaffold never bypasses the gate

## Compile posture

Chinese-LLM-Wiki compatibility note:

- `来源页` maps to source-grounded draft summaries first
- `主题页` and `实体页` map to draft topic/entity updates first
- `综合页` only becomes approved truth after review, so compile should treat it as a draft synthesis candidate

Before shaping drafts:

- follow the shared compile method in `compile-method.md`
- normalize source metadata such as `source_hash`, `source_mtime`, `last_verified_at`, and `possibly_outdated`
- surface alias and duplicate candidates rather than silently creating competing concept/entity drafts
- treat duplicate/alias surfacing as both governance input and authoring leverage, so later query/publish work can reuse prior approved coverage instead of restating the same concept from scratch
- preserve cross-language or terminology overlap as review input, not as automatic merges
- surface repeated concept clusters, repeated question clusters, and likely hub candidates when the durable improvement is navigational rather than just another standalone page
- prefer strengthening relationships between likely draft/live neighbors when the knowledge exists but the graph is weak
- treat process-level takeaways as candidates for `wiki/drafts/procedures/**`, not as forced semantic pages
- treat cross-domain transfer value as a first-class output, not an optional flourish

## Main outputs

- `wiki/drafts/summaries/**`
- `wiki/drafts/topics/**`
- `wiki/drafts/concepts/**`
- `wiki/drafts/entities/**` when needed
- `wiki/drafts/procedures/**` when the durable delta is a workflow rather than a semantic page
- `wiki/drafts/indices/*`
- `wiki/drafts/indices/packages/**`
- advanced `writeback_status` markers (plus `writeback_draft` pointers) in `outputs/qa/**` and `outputs/content/**` when the writeback lane runs
- batch `ingest` entry in `wiki/log.md`

The compile pass exists to hand clean draft packages to `kb-review`, which then writes `outputs/reviews/**`, promotes approved pages into `wiki/live/**`, and rebuilds `wiki/briefings/**`.

## Draft requirements

Follow `../obsidian-notes-karpathy/references/draft-schema.md` for the authoritative list of required and conditional draft fields (`draft_id`, `compiled_from`, `capture_sources`, `review_state`, `review_score`, `blocking_flags`, `evidence_coverage`, `uncertainty_level`, `promotion_target`, `review_package_meta`, plus conditional alias/duplicate/boundary/assumption/transfer/candidate/topic/confidence fields). Type-specific templates layer their own fields on top of that schema.

Keep source claims and compiler inferences cleanly separated — review depends on that separation to judge accuracy without re-reading the raw capture. Drafts should be shaped for review, not for final polish.

## Checkpoint

Before writing draft packages, confirm with the user:

- how many captures will be compiled and which ones
- whether any sources look ambiguous, duplicated, or potentially conflicting with existing live pages
- whether alias or duplicate candidates should be surfaced now or deferred to review

For single-source incremental compiles with no ambiguity, proceed without pausing.

## Output to the user

Always report:

1. how many captures were new, changed, or unchanged
2. how many draft summaries were created or updated
3. how many draft concepts or entities were touched
4. whether any PDFs were skipped because `paper-workbench` was unavailable
5. whether alias or duplicate candidates were surfaced for review
6. whether boundary conditions, assumption flags, or transfer targets were surfaced
7. whether the next step is `kb-review`