# kb-skills

![kb-skills hero](./assets/optima-kb-hero.png)

`kb-skills` 是一套给 Claude Code 和 Codex 用的知识库 skills。它的目标不是“每次提问都重新检索原始资料”，而是让 agent 持续维护一个基于 Markdown 的长期知识库。

如果你手上已经有一堆文章、PDF、网页摘录、研究笔记或项目资料，希望 agent 不只是临时回答，而是把这些内容逐步沉淀成可维护的 wiki，这个项目就是干这个的。

## 适合谁

- 想做个人研究型知识库的人
- 想把阅读笔记沉淀成结构化 wiki 的人
- 在一个主题上长期跟踪资料、观点和来源的人
- 想给团队留下一份能持续维护的 Markdown 知识库的人

## 你会得到什么

- 5 个可直接在 agent 里触发的知识库 skills
- 一套可初始化到本地目录的知识库模板
- 一份默认的 `AGENTS.md`，约束 agent 如何维护 wiki
- 一个示例知识库，演示整套工作流怎么落地
- 一个简单的 CLI，用来安装 skills、初始化模板和做基础 lint

## 快速开始

### 1. 安装 skills

```bash
npx kb-skills@latest install
```

这一步会把 skills 安装到本机默认目录：

- Claude Code：`~/.claude/skills/<skill-name>`
- Codex：`~/.codex/skills/kb-skills/<skill-name>`

如果你想先确认安装位置，可以运行：

```bash
npx kb-skills@latest where
```

如果你想检查安装是否成功，可以运行：

```bash
npx kb-skills@latest doctor
```

### 2. 让 agent 帮你初始化知识库

安装完成后，更推荐直接在 Claude Code 或 Codex 里说：

- “把当前目录初始化成知识库”
- “帮我为这个仓库建立知识库结构”
- “使用 `initializing-kb`，按这个主题初始化知识库”

默认路径应该是让 agent 来完成这一步，而不是你手动先搭好目录。

## 在 agent 里开始使用

初始化完成后，后续都可以直接说：

- “把这份资料 ingest 进知识库”
- “更新受影响的页面”
- “基于当前 wiki 回答这个问题”
- “帮我 lint 一下这个知识库”

## 第一次使用时怎么走

最简单的路径是：

1. 运行 `npx kb-skills@latest install`
2. 进入你准备维护知识库的目录
3. 在 agent 里触发 `initializing-kb`
4. 让 agent 建立或修订知识库结构
5. 开始 ingest 第一批来源

## 可以直接这样对 agent 说

如果你第一次用，不想自己组织措辞，可以直接发这一句：

```text
使用 `initializing-kb`，帮我把当前目录初始化成一个可长期维护的知识库。
```

## 这些 skills 分别做什么

### `initializing-kb`

定义这个知识库的运行契约。它会帮你确认页面类型、目录结构、维护规则，以及 `AGENTS.md` 里的约束。

### `ingesting-sources`

把原始材料第一次落库。产物不只是摘要，而是一页来源页，以及一份“哪些页面接下来需要更新”的清单。

### `updating-related-pages`

在 ingest 完新来源之后，更新受影响的实体页、综述页和交叉链接。

### `querying-the-wiki`

把当前维护后的 wiki 当成主要知识层来回答问题，而不是每次都回到原始资料重新拼答案。

### `linting-the-wiki`

检查 wiki 的结构问题、维护债务和明显缺口，帮助你看清哪些地方需要补。

## 这个知识库长什么样

初始化后的目录大致会是这样：

```text
.
├── AGENTS.md
├── index.md
├── log.md
├── raw/
└── wiki/
    ├── analyses/
    ├── entities/
    ├── overview/
    └── sources/
```

各部分职责是：

- `raw/`：保存原始资料
- `wiki/`：保存持续维护的知识页面
- `index.md`：做稳定导航
- `log.md`：记录知识库演化过程
- `AGENTS.md`：定义 agent 维护规则

## 日常工作流

这套 skills 的默认闭环是：

`schema -> ingest -> update -> query -> lint`

对应到实际使用里，一般就是：

1. 先定义或修订知识库结构
2. ingest 一个新来源
3. 更新受影响页面
4. 基于 wiki 回答问题
5. 把高价值的新结论回写进 wiki
6. 定期 lint 整个知识库

## CLI 命令

### 安装 skills

```bash
npx kb-skills@latest install
```

### 初始化模板

```bash
npx kb-skills@latest init
```

### 初始化到指定目录

```bash
npx kb-skills@latest init --dir /path/to/your-kb
```

### 查看安装位置

```bash
npx kb-skills@latest where
```

### 检查安装状态

```bash
npx kb-skills@latest doctor
```

### 对知识库跑基础检查

```bash
npx kb-skills@latest lint
```

当前 `lint` 主要检查：

- Markdown 坏链
- `index.md` 条目格式是否正确
- 长期页面是否缺失索引
- `index.md` 是否重复列出同一页面
- 没有任何入链的 orphan wiki 页面
- `log.md` 标题是否符合约定

## 自定义工作区路径（`KB_HOME`）

默认情况下，所有 skills 把 KB workspace 当作 `~/kb`。设置环境变量 `KB_HOME` 可以指向任意路径，适合：

- 把工作区放到非 `$HOME` 的目录（如外挂磁盘、企业共享盘）
- 在容器里把工作区挂到 NAS / EFS 之类的共享存储
- 多个互不干扰的 workspace 之间切换（`KB_HOME=/path/to/work-kb` vs `KB_HOME=/path/to/personal-kb`）

设置之后：

- 5 个 skill 的所有路径都会基于 `KB_HOME` 解析
- `kb-skills lint` 不带 `--dir` 时也会使用 `KB_HOME` 作为默认工作区
- 没设置时一切行为与之前完全一致（默认 `~/kb`），不影响个人使用

容器场景示例：

```yaml
# docker-compose.yml
services:
  agent:
    image: your-agent-runtime
    environment:
      - KB_HOME=/mnt/knowledge
    volumes:
      - knowledge-vol:/mnt/knowledge
```

agent 在容器里运行 skill 时，所有 ingest / query / lint 都会落在 `/mnt/knowledge/` 下，与代码部署 / EFS swap 等机制解耦。

> **前提**：你使用的 agent runtime 会把容器进程的环境变量透传给 Bash 工具子进程。绝大多数 runtime（包括 Claude Code 自身、Optima agent runtime）默认都是这样；少数沙箱化方案可能会过滤 env。可以在 agent 里跑一句 `echo "$KB_HOME"` 验证。

## 一个重要心智模型

`kb-skills` 不是“问一次，答一次”的资料检索工具。

它更像一套维护协议：你把原始资料交给 agent，agent 不只是临时读完回答，而是持续把内容整理进一层结构化 wiki。随着来源和问题越来越多，这份 wiki 会越来越有用。

所以它更接近“长期维护知识库”，而不是“即时 RAG”。

## 示例

仓库里带了一个可直接检查的 example repo：

```bash
npx kb-skills@latest lint --dir examples/personal-research-kb
```

如果一切正常，预期会输出：

```text
OK: no lint issues found in examples/personal-research-kb
```

## 文档导航

- `docs/installation.md`：安装和初始化细节
- `docs/examples.md`：示例知识库说明
- `docs/workflow.md`：完整工作流说明
- `docs/schema.md`：模板结构和页面类型
- `docs/vision.md`：为什么这不是普通 RAG
- `docs/search.md`：知识库变大后的搜索思路

## 当前状态

当前已经形成一个最小但可用的闭环：

`schema -> ingest -> update -> query -> lint`