# Kernel Docs System

> Use when you need to treat `docs/**/*.md` as a routed docs system for kernel and low-level repos: list doc entrypoints, choose what to read from `summary` and `read_when`, lint metadata quality, initialize empty front matter for legacy docs, or decide the correct `version/domain` landing path before writing. Do not use for archive and knowledge-lift work, or when the main job is reading code and turning that code reading into a durable doc.

- Skill: `apple-ouyang/kernel-docs-system` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add apple-ouyang/kernel-docs-system`
- Raw SKILL.md: https://api.skillmd.com/api/skills/apple-ouyang/kernel-docs-system/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: apple-ouyang (https://skillmd.com/u/apple-ouyang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/apple-ouyang/kernel-docs-system

---


# Docs System

维护 `docs/` 入口系统，而不是把 markdown 当散文件处理。
长期文档仓固定入口是 `~/kernel-docs`；如果实际仓库不在这个目录，安装脚本会维护同名软链接。
长期文档默认只写入 `~/kernel-docs/docs/<version>/<domain>/topic.md`，不要把长期文档写回当前代码仓的 `docs/`。

## When To Use

- 先看当前仓有哪些长期文档入口
- 根据 `summary` 和 `read_when` 决定先读哪篇
- 校验 `docs/` 元数据质量
- 为旧文档补空 YAML 头，或为已有 YAML 头补缺字段
- 判断文档该落到哪个 `version/domain`

## Execution Modes

- `Daily Sync`
  - 每次进入本 Skill 都先检查当前 `repo_root + branch` 今天是否已经成功执行过 `git pull --rebase`
  - 同一个 `repo_root + branch` 在同一个自然日最多成功 pull 一次
  - 状态记录在 `~/.claude/kernel-docs-pull-state.json`
  - 如果今天尚未成功 pull，且工作区干净，则先执行 `git pull --rebase`
  - 如果工作区不干净，先停止并明确说明无法安全 rebase，不要跳过后继续
- `Discover`
  - 先跑 `docs-list`
  - 需要时用 `--version`、`--domain`、`--json` 缩小范围
  - 如果没有命中文档，或命中的文档明显不覆盖当前问题，则调用 `kernel-code-to-docs` skill
- `Lint`
  - 运行 `docs-lint`
  - 同时检查路径、缺字段、占位 `summary`、空泛 `read_when`
- `Init Front Matter`
  - 运行 `docs-init-frontmatter --write`
  - 没有 YAML 头时补空外壳；已有 YAML 头时只补缺字段，不重写正文
- `Route`
  - 先判断版本，再判断领域，再决定是否需要抽查同主题旧文档

默认先走 `Discover`。

## Core Rules

- 每次进入本 Skill，先做一次每日 `git pull --rebase` 检查，再继续后续动作
- 每日 pull 的频率按“自然日 + `repo_root + branch`”控制，不按 24 小时滑窗控制
- 只有成功 pull 才更新 `~/.claude/kernel-docs-pull-state.json`
- pull 失败时不要记成功，也不要伪装成已同步
- 文档入口发现必须先走 `docs-list`
- 不要用 `rg`、`grep`、`find` 直接扫描 `docs/` 决定先读哪篇
- `archive` 默认隐藏；只有显式 `--all` 才展示
- `archive` 是生命周期，不是版本维度；归档路径固定为 `docs/archive/<domain>/`
- 文档路径固定为 `~/kernel-docs/docs/<version>/<domain>/topic.md`
- 不使用 `plan` / `research` 深目录
- `process` 已并入 `arch`
- `docs-init-frontmatter` 只补空的 YAML 外壳，或补缺失字段；不自动生成字段内容
- `summary` 必须回答“这篇文档帮助做什么判断/操作”
- `summary` 不能写成 `TODO`、`待补充`、`占位`
- `read_when` 必须写成任务触发语句
- `read_when` 不能只写“修改前”“需要时”“排查时”
- `Discover` / `Route` 场景下，如果文档入口不足以覆盖当前问题，默认继续读代码并转交 `kernel-code-to-docs`，不要停在“没有文档”
- 这个转交是单向的；一旦已经进入 `kernel-code-to-docs`，不要再回跳到本 Skill 做二次分发

## Version And Domain Rules

固定版本目录：

- `v2`
- `v3`
- `lite`

固定领域目录：

- `arch`
- `memory`
- `filesystem`
- `dfx`
- `debug`
- `security`
- `drivers`

归类规则：

- 架构、启动、调度、IPC、跨子系统机制：`arch`
- 内存管理、页表、分配器、缺页异常：`memory`
- VFS、具体文件系统实现、缓存一致性：`filesystem`
- 日志、trace、观测、诊断链路：`dfx`
- GDB、crash 分析、现场定位、调试手册：`debug`
- 权限、隔离、认证、加固：`security`
- 设备模型、总线、驱动框架、外设适配：`drivers`

版本判断：

- 仓名以 `hm-` 开头：`v3`
- 绝对路径包含 `RTOS_V3_master`：`v3`
- 绝对路径包含 `RTOS_V2_master`：`v2`
- 路径或仓名包含 `kernel-5.x`：`v2`
- `lite` 只有用户明确说明时才按 `lite` 处理

阅读已有文档时遵循非对称规则：

- 当前路径命中 `v2`：只看 `docs/v2/`
- 当前路径命中 `v3`：默认看 `docs/v3/`；只有用户明确要求参考 `v2` / `Linux` 时，才额外看 `docs/v2/`
- 当前上下文是 `lite`：先看 `docs/lite/`；不够时再补看 `docs/v2/`；不看 `docs/v3/`
- 当前路径无法判断版本：根据用户提到的 `V2` / `Linux` / `V3` / `鸿蒙` / `lite` 选择版本文档
- 需要追历史实现或废弃方案时，再额外看 `docs/archive/`

## Front Matter

推荐最小模板：

```yaml
---
summary: 一句话说明这篇文档帮助完成什么判断或操作
read_when:
  - 遇到什么任务、决策或排障场景时先读
---
```

约束：

- `summary` 优先写“作用 + 决策对象”，不要只重复标题
- `read_when` 表示“AI 在什么场景下应该优先读这篇文档”
- `read_when` 要写成任务触发语句，不要写成状态词、作者备注或空泛占位

`source` 如果需要写，语义是“这篇文档主要基于什么材料写成”，不是必填路径：

- 参考文档时，只记录文档名
- 参考代码时，写 `git仓库名:仓内相对路径`
- 不要求穷举所有参考文件；精确证据路径和行号放正文

## Stop Conditions

下面这些情况不要继续留在这里：

- 用户真正要的是归档、知识上浮、修复错误归档
- 任务核心已经变成代码调研沉淀，而不是 docs 入口维护
- 落点还没判断清楚，就准备直接新建文件

这时改走 archive / knowledge-lift 流程或 `kernel-code-to-docs`。

如果命中下面情况，也先停下并说明原因：

- 今天还没成功 pull，但当前工作区不干净，无法安全执行 `git pull --rebase`

## Commands

- `git pull --rebase`
- `~/.claude/bin/docs-list [--all] [--version <v2|v3|lite>] [--domain <domain>] [--json]`
- `~/.claude/bin/docs-lint [--files <path...>]`
- `~/.claude/bin/docs-init-frontmatter [--files <path...>] --write`
- 不传仓路径时，这些命令默认操作 `~/kernel-docs`

## Output Contract

默认输出必须至少回答下面一项：

- 这次应该先读哪些文档，以及为什么
- 哪些文件元数据不合规
- 哪些旧文档已补空 YAML 头，或哪些文档已补缺字段
- 某篇文档更适合哪个 `version/domain`
- 如果没有相关文档，为什么要转交 `kernel-code-to-docs`

## Done Criteria

- 入口发现：只看输出就能决定下一篇该读什么
- 元数据校验：问题文件、问题类型、下一步动作都明确
- 空 YAML 头初始化：正文原样保留，只补空外壳或缺字段
- 路由：版本和领域判断都有依据
- 缺文档时：不会停在入口层，而是明确转到 `kernel-code-to-docs`