kb-skills

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

npx kb-skills@latest install

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

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

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

npx kb-skills@latest where

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

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 说

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

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

这些 skills 分别做什么

initializing-kb

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

ingesting-sources

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

updating-related-pages

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

querying-the-wiki

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

linting-the-wiki

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

这个知识库长什么样

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

.
├── 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

npx kb-skills@latest install

初始化模板

npx kb-skills@latest init

初始化到指定目录

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

查看安装位置

npx kb-skills@latest where

检查安装状态

npx kb-skills@latest doctor

对知识库跑基础检查

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），不影响个人使用

容器场景示例：

# 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：

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

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

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