传统RAG已经落伍了？清华大神开源的这个 rag-skill，让知识库检索直接升维

被向量检索毒打过的人，才会真正理解这个东西的价值。

一、先聊聊你被传统 RAG 坑过没有

做过知识库问答系统的人，大概都有过这样的崩溃时刻——

你辛辛苦苦把几百份文档切成几千个 Chunk，跑 Embedding 向量化，存进 Milvus 或者 Chroma，以为大功告成。结果一上线，用户问了一个稍微绕一点的问题，AI 给出的答案要么文不对题，要么把不相关的段落硬凑在一起，要么直接幻觉。

问题出在哪？

出在"Chunk + Embedding"这个模式的根本局限上：

• • 语义切割失真：一个段落强行被截断，上下文完全丢失，向量表示也就失真了
• • 检索即终局：检索一次不行就没有第二次，不会回头反思
• • 静态流水线：不管问题简单还是复杂，一套流程走到底，没有自适应能力
• • 长上下文淹没：一口气把所有 Chunk 都塞给 LLM，重要信息被稀释

就是这个背景下，一个新思路开始在 AI 圈流行起来：用 Agent Skills 做知识库检索。

二、什么是 rag-skill？来自 code秘密花园 的开源方案

rag-skill 是由知名 AI 博主 ConardLi（code秘密花园）开源的一个 Agent Skill，专门用于本地知识库检索。

项目地址：https://github.com/ConardLi/rag-skill

它的核心思想颠覆了传统 RAG 的逻辑：

不再"切片-向量化-检索一步到位"，而是让 AI 像一个有经验的研究员一样，先看目录，再按需深入，不满意就迭代，直到找到真正有价值的信息。

这个 Skill 的核心特性如下：

三、它和传统 RAG 到底有什么本质区别？

用一个比喻就能说清楚：

传统 RAG 像是开卷考试的学生——随机翻到哪页抄哪页，翻不到就开始编。

rag-skill 像是一个专业研究员——先看目录，制定检索计划，用不同策略找信息，找不够就换关键词反复搜，收集到足够证据才开始回答。

从技术层面看，区别在这几个地方：

1. 从"一次检索"到"多轮迭代"

rag-skill 内置了最多 5 轮的智能检索机制。第一轮找不准？换个关键词、换个思路再来一轮，直到找到足够相关的内容。这就是为什么它在复杂问题上显著优于传统 RAG。

2. 从"全文加载"到"渐进式披露"

传统 RAG 的索引是平铺的，找到 Chunk 就全部丢给 LLM。rag-skill 则通过分层索引（先读目录，再读章节摘要，再读具体段落），大幅减少了无效 token 的消耗。

3. 从"静态流水线"到"动态认知循环"

rag-skill 的检索行为由 LLM 驱动，能根据上一轮检索结果动态调整下一轮策略。这是从"脚本"到"智能体"的本质升级。

四、文件结构长什么样？

在使用之前，先搞清楚 rag-skill 的目录结构：

skilltest/
├── .agent/
│   └── skills/
│       ├── rag-skill/               # 核心知识库检索 Skill
│       │   ├── SKILL.md             # Skill 主文件（约13KB）
│       │   └── references/          # 参考文档
│       │       ├── pdf_reading.md   # PDF 处理方法指南
│       │       ├── excel_reading.md # Excel 读取方法
│       │       └── excel_analysis.md # Excel 分析方法
│       └── skill-creator/           # Skill 创建指南（可选）
│
└── knowledge/                       # 你的知识库目录
    ├── data_structure.md            # 根目录索引（关键！）
    ├── AI Knowledge/
    │   ├── data_structure.md        # 子目录索引
    │   └── *.pdf                    # 具体文档
    └── ...

关键点：data_structure.md 是整个系统的导航地图。 每一层目录下都应该有一个这样的索引文件，告诉 Agent 这个目录里有什么内容、用来解决什么问题。没有它，rag-skill 就失去了"先看目录"的能力，退化成普通搜索。

五、手把手使用教程

方式一：通过 npx skills CLI 安装（推荐）

这是最快的方式，一行命令搞定：

# 安装 rag-skill（最新版）
npx skills add ConardLi/rag-skill

# 或者通过 garden-skills 集合安装
npx skills add ConardLi/garden-skills -s kb-retriever

# 指定安装到 Claude Code
npx skills add ConardLi/garden-skills -s kb-retriever -a claude-code

# 全局安装（适用于所有项目）
npx skills add ConardLi/garden-skills -s kb-retriever --global

安装完成后，Skill 会自动放到 .claude/skills/ 或 .agent/skills/ 目录下。

方式二：手动克隆安装

# 克隆仓库
git clone https://github.com/ConardLi/rag-skill.git

# 将 rag-skill 目录复制到你的项目
cp -r rag-skill/.agent/skills/rag-skill  你的项目/.agent/skills/

Step 1：准备你的知识库

这是最关键的一步，也是最容易被忽视的一步。

1.1 创建知识库目录

mkdir -p knowledge/产品文档
mkdir -p knowledge/技术规范
mkdir -p knowledge/FAQ

1.2 编写根目录 data_structure.md（核心！）

# 知识库结构索引

## 目录概览

本知识库包含以下主要分类：

### 产品文档 (`/knowledge/产品文档/`)
- 产品功能说明、使用手册、版本更新记录
- 适用场景：用户咨询产品功能、操作步骤

### 技术规范 (`/knowledge/技术规范/`)
- API 接口文档、架构设计、部署指南
- 适用场景：开发人员查阅技术细节

### FAQ (`/knowledge/FAQ/`)
- 常见问题汇总、故障排查指南
- 适用场景：快速定位已知问题的解决方案

1.3 每个子目录也需要 data_structure.md

# 产品文档目录

## 文件列表

- `产品手册_v2.3.md` - 完整产品功能说明，覆盖所有核心模块
- `快速开始指南.md` - 新用户入门，10分钟上手教程
- `更新日志.md` - 各版本功能变更记录

Step 2：放入你的文档

支持的格式：

• • Markdown（.md）：直接放，效果最好
• • PDF：放入对应目录，Skill 会自动学习 PDF 处理方法再读取
• • Excel（.xlsx）：同上，有专门的处理流程

最佳实践：Markdown 格式效果最优，建议把 PDF 文档用工具提前转换为 Markdown，再放入知识库。

Step 3：启动 Claude Code 并激活 Skill

在你的项目目录下启动 Claude Code：

claude

Skill 会自动被 Claude Code 检测到。你可以直接开始提问：

用户：我们的 API 限流策略是什么？超出限制后怎么处理？

Claude（启用 rag-skill）：
[检索第1轮] 读取根目录 data_structure.md，定位到"技术规范"目录
[检索第2轮] 读取技术规范/data_structure.md，找到 API 文档
[检索第3轮] 局部读取 API接口文档.md 的限流相关章节
[生成答案] 基于检索到的内容，结合上下文给出准确回答

Step 4：针对 PDF 和 Excel 的特殊处理

rag-skill 内置了"强制学习机制"：

• • 遇到 PDF 文件，Agent 会先读取 references/pdf_reading.md，学习正确的 PDF 处理方法，再去提取内容
• • 遇到 Excel 文件，同样先读 excel_reading.md 和 excel_analysis.md

这个机制避免了直接粗暴地 cat 二进制文件导致的乱码或错误。

六、实际效果对比

以下是同一个问题在传统 RAG 和 rag-skill 下的对比（基于实测反馈整理）：

测试问题： "我们的退款政策在哪些情况下不适用？有没有例外条款？"

传统 RAG 表现：

• • 返回 3 个相关度 70% 左右的 Chunk
• • 答案拼凑感强，遗漏了"例外条款"部分
• • 没有说明信息来源

rag-skill 表现：

• • 第 1 轮：定位到"用户协议"目录
• • 第 2 轮：在退款政策文档中找到主要条款
• • 第 3 轮：发现"附录"中存在例外说明，主动深入检索
• • 最终答案：完整覆盖主要条款和例外情形，附注具体文档位置

七、常见问题和注意事项

Q1：知识库太大，检索变慢怎么办？

rag-skill 的渐进式检索本身就是为大型知识库设计的，它不会一次性加载所有内容。关键是要做好 分层索引：根目录 → 子目录 → 文件，每层都有清晰的 data_structure.md，这样前两轮检索消耗极少，缩小范围后再深入。

Q2：data_structure.md 怎么写才够好？

几个原则：

• • 用问题驱动描述，而不是单纯罗列文件名（"用户咨询退款流程时查这里"比"退款.md"更有价值）
• • 说明每个文件/目录的适用场景
• • 保持及时更新，新增文档后同步更新索引

Q3：适合什么规模的知识库？

根据社区实测，rag-skill 在中小型知识库（文档数量在几十到几百篇）上效果最为突出。大型知识库（上万篇）建议结合传统向量检索做粗筛，再用 rag-skill 做精检。

Q4：和 RAGFlow、Dify 这些产品有什么区别？

RAGFlow、Dify 是完整的 RAG 平台产品，有 UI 界面、用户管理等功能，部署成本高。rag-skill 是一个轻量级的 Agent Skill，直接在 Claude Code 等 Agent 框架下使用，零额外部署，适合开发者在自己的项目中快速集成。

Q5：一定要用 Claude Code 吗？

不是。rag-skill 遵循标准的 Skill 规范，理论上可以在支持 Skills 的 Agent 框架中使用，包括 Cursor、Codex 等。但目前在 Claude Code 上的适配最为成熟。

Q6：PDF 处理效果怎么样？

扫描版 PDF（纯图片）效果较差，建议提前 OCR 转文字。文字型 PDF 效果良好，rag-skill 的强制学习机制确保了正确的提取流程。

八、总结：什么场景最值得用？

适合用 rag-skill 的场景：

• • 中小型专业知识库（公司内部文档、技术手册、产品文档）
• • 复杂多步骤问题（需要跨文档关联信息）
• • 需要可解释性（想知道答案来自哪个文档哪个位置）
• • 开发者本地使用（轻量、零部署成本）

暂时不适合的场景：

• • 超大规模知识库（>1万篇文档，先用向量检索粗筛）
• • 需要实时更新的知识（Skill 本身不维护索引数据库，需手动更新 data_structure.md）

结语

传统 RAG 不是没用，而是它在遇到真实世界的复杂问题时力不从心。rag-skill 提供的这套"研究员式检索"范式，代价极低（一个 Skill 文件），收益却很实在——特别是对那些被 Chunk 切割和向量召回率折磨过的人来说。

项目是开源的，可以直接拿来用，也可以作为参考来构建自己的 Agent Skills 知识检索体系。如果你正在搭建 Agent 工作流，这个思路值得认真研究。

GitHub 地址：https://github.com/ConardLi/rag-skill