---
name: init-llm-wiki
description: 根据指定领域，初始化并维护一个 Obsidian 优先、兼容 Google Cloud OKF 0.1 的 Karpathy 式 LLM Wiki。Use when the user wants to build or maintain a Karpathy-style LLM wiki for a new domain.
metadata:
  author: xiehuacheng
  version: "1.0.0"
---

# 构建 LLM Wiki

帮助用户构建一个 Karpathy 风格的 LLM wiki，并遵循 Google Cloud Open Knowledge Format（OKF）v0.1 规范。

## 简介

这是一个通用 agent skill，用于为一个新领域（如一个技术栈、研究方向、产品领域）快速启动由 LLM 维护、人类策展的 wiki。

它会帮你：

- 自动生成目录结构
- 生成 `CLAUDE.md` / `AGENTS.md` schema 文档
- 创建 `index.md`、`log.md`
- 统一 frontmatter 和链接规范

## 用途

安装完成后，在支持的 agent 环境中输入（例如 Claude Code）：

```text
/init-llm-wiki
```

Agent 会询问你想构建哪个领域的 wiki，然后自动完成初始化。

## 生成的 Wiki 目录结构

```text
wiki/
├── 00-Raw/                 # 原始资料（Markdown + type: source）
├── 01-Wiki/                # 知识点卡片
├── 02-Areas/ 或 02-Module/ # 第二级分类
│   └── <领域>/
│       ├── index.md        # 领域落地页
│       └── 子话题.md        # 成熟期拆分的子话题
├── index.md                # 根目录，frontmatter 声明 okf_version: "0.1"
└── log.md                  # 追加式更新日志
```

## 核心约定

1. **Obsidian 优先**：内部链接统一使用 `[[知识点名称]]`，编辑已有页面时禁止改成标准 Markdown 链接。
2. **OKF 兼容**：每个概念 `.md` 文件都包含 YAML frontmatter，且至少包含 `type` 字段；根 `index.md` 声明 `okf_version`。
3. **保留 frontmatter**：不要删除或修改 `type`、`title`、`description`、`tags`、`aliases` 等字段，除非用户明确要求。
4. **仅在对外导出 OKF 时**，才批量把 `[[...]]` 转换为 `[文本](路径.md)`，且需先征得用户同意。

## 依赖（可选）

- [obsidian-skills](https://github.com/kepano/obsidian-skills)：Kepano 的 Obsidian 编辑 skill，安装后编辑体验更好，不安装也能正常使用。

## 相关资源

- Karpathy LLM Wiki 原文：https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
- OKF 规范：https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md

## 执行流程

执行过程中，可将耗时的独立执行任务（如批量创建/更新卡片）交给 sub agent 并行处理；但 **Ingest 中的 takeaways 讨论和页面方案确认必须由主会话完成**，主会话负责任务拆分、结果整合与质量兜底。若 sub agent 失败或超时，主会话应及时接管，避免阻塞整体流程。

1. 如果用户还没有说明领域或主题，先问：**“你想构建关于哪个领域的 wiki？”**
2. 参考 Karpathy 的 LLM Wiki 模式（https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f）和 OKF 规范（https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md）。
3. **不要预填初始知识**，等待用户提供来源或明确指令。
4. 如果项目还没有 git 仓库，请先初始化。
5. 初始化时创建以下三个基础目录：
   - `00-Raw/` —— 原始资料存放处，必须包含 `classified/` 与 `uncategorized/` 两个空子目录。**原始资料只读不改**，Agent 读取后不要在原文件上做任何修改。这两个子目录不需要放 `index.md`。
   - `01-Wiki/` —— 主题卡片。
   - `02-Areas/` 或 `02-Module/` —— 第二级分类目录，只创建这一层空目录；不要在其下再创建具体领域子文件夹。
   
   `02-*/` 下的具体子目录（如 `02-Module/数据结构/`、`02-Areas/AI工具/`）不要在初始化时创建。等用户提供资料并明确分类需求后，再询问用户是否需要创建、采用什么命名，然后根据用户确认创建。
   
   **注意**：本 skill 当前不定义 `03-Projects/` 或类似顶层应用目录。项目、实验、真题、案例等应用性内容如何组织，目前 intentionally 留白，待后续版本根据实际使用场景定义。

## 目录结构演化

本 skill 的目录层级不是一次性设计出来的，而是随 wiki 规模逐步生长的。管理 wiki 的 agent 必须理解 `02-Areas/`（或 `02-Module/`）在不同阶段的目标形态，避免过早分类（创建空文件夹）或过度扁平（把不该放在一起的页面硬塞进一个文件）。

判断的核心标准不是卡片数量，而是**内容是否已经自然分化出独立的组织单元**：如果一个领域的卡片可以用一段话 + 一个链接列表讲清楚，就不应该拆分子文件夹；如果一个领域的卡片已经需要分层导读、学习路径或子话题才能被理解，就应该升级结构。

### 02-Areas / 02-Module 的三阶段演化

`02-Areas/`（或 `02-Module/`）是**面向浏览与学习的视图层**，负责把 `01-Wiki/` 中零散的概念卡片聚合成可理解的领域地图。

#### 阶段一：扁平索引（早期）

当 wiki 规模较小，且每个领域的导语和链接都能在一个页面里清晰表达时，`02-Areas/` 应保持扁平：

```
02-Areas/
└── index.md
```

`02-Areas/index.md` 的内容是按领域分组的导航与导读，每个领域写一段 100–300 字的导语 + 相关卡片链接即可。此时**不要为每个领域创建子文件夹**。

阶段一的典型特征：
- 一个 `index.md` 就能概览所有领域
- 每个领域的导语和链接列表在视觉上不拥挤
- 领域之间的边界清晰，没有需要单独展开说明的子话题

#### 阶段二：领域落地页（成长期）

当某个领域已经大到在 `02-Areas/index.md` 里用一段导语讲不清楚，或者需要独立的学习路径、模式梳理、决策表来辅助理解时，才为该领域创建子文件夹：

```
02-Areas/
├── index.md
└── Agent 与 Claude Code/
    └── index.md
```

此时 `02-Areas/Agent 与 Claude Code/index.md` 不再只是链接列表，而应升级为**领域落地页**：
- 这个领域解决什么问题
- 推荐的学习/阅读路径
- 核心模式或决策表
- 与周边领域的关系
- 最后附上相关卡片链接

进入阶段二的信号（满足任意一条即可考虑）：
- 该领域的相关卡片在 `02-Areas/index.md` 中占据了过大篇幅，影响整体可读性
- 该领域内部已经自然形成 2–3 个可命名的子话题
- 该领域需要一段“入门路径”来帮助读者决定阅读顺序
- 该领域与多个其他领域有交叉，需要一个独立页面来解释边界

注意：**不要仅为一个 index.md 创建子文件夹**。如果创建了一个子文件夹，就意味着预期该领域会继续生长到阶段三，或者当前已经需要独立落地页带来的额外结构。

#### 阶段三：子领域聚合（成熟期）

当某个领域的知识继续增长，单个领域落地页已经装不下，需要拆分成子话题页面时，子文件夹内部应进一步拆分：

```
02-Areas/
├── index.md
└── Agent 与 Claude Code/
    ├── index.md              # 领域导读
    ├── 模式与架构.md          # 子话题
    └── 工具与生态.md          # 子话题
```

进入阶段三的信号（满足任意一条即可考虑）：
- 领域落地页过长，需要滚动很久才能看完
- 领域内部已经形成清晰、稳定的子话题，且每个子话题都值得独立成页

### 不应出现的结构

以下结构属于过度设计或过早分类，agent 应避免，并在 lint 时建议整改：

- `02-Areas/` 下每个子文件夹里只有一个 `index.md`，且该 index.md 只是链接列表
- 为仅有几张卡片、一段导语就能讲清楚的领域创建独立子文件夹
- 创建空文件夹“预留未来使用”

### 决策自检问题

创建 `02-Areas/<领域>/` 子文件夹前，agent 应先回答：

1. 这个领域在 `02-Areas/index.md` 里是否已经占用了过多篇幅，或和其他领域混在一起难以阅读？
2. 这个领域是否需要除“导语 + 链接列表”之外的结构（如学习路径、模式对比、决策表）才能被理解？
3. 创建子文件夹后，这个领域是否有明确的下一步生长方向（子话题），而不是只是为了把链接列表单独放一个地方？

如果三个问题都为“是”，则创建子文件夹；否则继续在 `02-Areas/index.md` 中用段落表达。

### 关于应用性内容

项目、实验、真题、案例等应用性内容目前不在本 skill 的定义范围内。后续版本将根据实际使用场景决定是否引入 `03-Projects/` 或把应用内容下沉到 `02-Areas/<领域>/` 下。当前 agent 不应主动创建任何应用目录。

6. 创建第一版 agent schema 文档（例如 Claude Code 用 `CLAUDE.md`，Codex / OpenCode 等用 `AGENTS.md`），并同时创建 `WORKFLOWS.md` 作为工作流程手册。可参考本 skill 目录下的 `templates/WORKFLOWS.md` 模板。其中需包含：
   - Karpathy 原文中提到的 Wiki 内容类型
   - OKF 要求的 `type` 字段及取值规范
   - 根目录 `index.md` 和 `log.md` 的角色与格式
   - 文件命名、链接、frontmatter 的使用规则
   - 核心工作流程：Ingest、Query、Lint 的**明确职责分界**、触发条件与执行步骤
   - 扫描版/非文本资料的处理方式（如有）
7. 创建**根目录** `index.md`，frontmatter 中写入 `okf_version: "0.1"`，正文列出 wiki 目录入口。注意：`00-Raw/` 不要作为 `[[00-Raw]]` 的 wikilink 目标，因为 raw 目录不需要 `index.md`；写成纯文本说明即可。其他目录链接使用 Obsidian 风格 `[[标题]]` 或 OKF 风格 `[标题](相对路径)`。
8. 创建 `log.md`，日期标题使用 ISO 8601 格式 `YYYY-MM-DD`，并写入初始化记录。
9. 可选项：如果用户需要，再询问是否为其创建一个 HTML 看板来展示 wiki 状态。

## Ingest 强制流程（必须先讨论，后写入）

为了贴近 Karpathy 原版的 LLM Wiki 思想，Ingest 不是“把资料丢进去就自动生成卡片”的批处理任务，而是一个**人机协作的策展过程**。执行 Ingest 时，主会话必须先完成以下两个阶段，再决定是否使用 sub agent 并行创建卡片：

### 阶段一：讨论关键收获（Key Takeaways）

这一步必须先做，不能跳过。重点是**内容层面的对话**，而不是直接规划写哪些页面。

1. **读取所有待处理的原始资料**。
2. **按来源提炼关键收获**：为每个资料用 1–2 句话概括其主旨，然后列出核心论点、关键概念、重要数据、与已有 wiki 的冲突或补充、作者的限制/假设等。不预设数量，按实际内容列出。
3. **把关键收获展示给用户，并展开讨论**：
   - 这些资料主要说了什么？
   - 哪些观点最有价值？
   - 哪些和已有知识矛盾或需要更新？
   - 用户有没有想补充、质疑或特别强调的地方？
4. **根据用户反馈调整收获重点**。

### 阶段二：基于收获规划页面方案

在确认关键收获之后，才把讨论结果转化为具体的 wiki 写入方案。

1. **基于已确认的关键收获，提出“本次处理清单”**：
   - 新增的概念/实体卡
   - 需要更新的已有页面
   - 可能值得创建的对比/算法页面
   - 建议合并或明确边界的重叠主题
   - 暂时不值得单独成卡、但可以在已有页面中提及的内容
2. **向用户展示处理清单并等待确认**：让用户看到将要写什么、改什么、合并什么，询问是否有要调整、补充、跳过或合并的项。
3. **用户确认后，才使用 sub agent 并行创建/更新具体卡片**。
4. **sub agent 完成后，主会话执行去重与边界澄清**，更新 `index.md`、相关概览和 `log.md`。

如果 sub agent 失败或超时，主会话应接管并手动完成对应卡片，避免阻塞流程。详见 `WORKFLOWS.md` 的 Ingest 流程。

## 升级与迁移

当 `init-llm-wiki` skill 本身有重大更新（如 Ingest 流程调整、目录约定变化）时，已经用旧版 skill 初始化的 wiki 项目不会自动更新。主会话应：

1. **同步 `WORKFLOWS.md`**：将项目根目录的 `WORKFLOWS.md` 与当前 skill 模板对齐。这是项目级文件，skill 更新不会自动覆盖。
2. **同步 `CLAUDE.md` / `AGENTS.md`**：把 schema 文档中的过时约定（如目录结构、frontmatter 规则、工作流程）更新到最新版本。
3. **清理过时结构**：例如旧版可能创建了 `00-Raw/index.md`、`00-Raw/classified/index.md`、`00-Raw/uncategorized/index.md` 等，新版已明确这些目录不需要 `index.md`，应删除。
4. **更新根 `index.md`**：如果旧版链接了不应再存在的页面或目录（如 `[[00-Raw]]`），应移除或改为纯文本说明。
5. **在 `log.md` 中记录迁移**：说明本次迁移的原因和变更内容。

完成迁移后，再按新版流程继续 Ingest / Query / Lint。

## 必须遵守的 OKF 约定

- 每个概念 `.md` 文件都必须包含可解析的 YAML frontmatter，且至少有一个非空的 `type` 字段。
- 建议的 frontmatter 字段包括：`title`、`description`、`resource`、`tags`、`timestamp`（ISO 8601）。
- 允许自定义扩展字段；消费工具应保留不认识的键，不能因此拒绝文档。
- **只有根目录的 `index.md`** 可以包含 frontmatter，且仅用于声明 `okf_version`；子目录中的 `index.md` 和任何 `log.md` 都不得包含 frontmatter。
- **子目录 `index.md` 的角色**：允许作为该目录的导航/概览页存在，但不是必须的；如果存在，只能包含目录说明和页面链接，不能包含 frontmatter，也不应被当作概念页面。
- 知识图谱优先使用 Obsidian 双向链接（`[[文本]]`）。如需与严格 OKF 工具交换，可在 lint/export 阶段转换为标准 Markdown 链接（`[文本](路径)`）。
- 概念身份等于文件在包内的路径去掉 `.md` 后缀。
- 断链是允许的，不能视为格式错误。

## Obsidian 格式保留规则

- **优先且保留 `[[wikilink]]`**：新建内部链接时用 `[[知识点名称]]`；编辑已有页面时，禁止把现有的 `[[...]]` 转成 `[...](...)`。
- **外部链接用标准 Markdown**：如 `[来源](https://example.com)`。
- **保留 YAML frontmatter**：不要删除或修改 `type`、`title`、`description`、`tags`、`aliases`、`cssclasses` 等字段，除非用户明确要求。
- **保留文件命名习惯**：继续使用中文知识点名称作为文件名，例如 `二叉树.md`，不要改成 slug。
- **防止双后缀**：概念 `.md` 文件不得以 `.md` 结尾再加 `.md`（禁止 `CLAUDE.md.md`、`index.md.md`、`log.md.md`）。若概念名本身含 `.md`（如 `CLAUDE.md`），应命名为 `CLAUDE.md 配置文件.md` 或 `CLAUDE.md 项目规范.md`。
- **仅在明确需要对外导出 OKF 时**，才批量把 `[[...]]` 转换为标准 Markdown 链接；转换前需告知用户并征得同意。

## 其他注意事项

- 有不确定的地方请向用户提问。
- 如果需要更好的 Obsidian 编辑支持，可在项目级别安装 kepano 的 `obsidian-skills`，安装完后请用户重启 agent 再继续；不安装也能正常使用。