被向量检索毒打过的人，才会真正理解这个东西的价值。
* *
一、先聊聊你被传统 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 的核心特性如下：
| 特性 | 说明 |
| — | — |
| 多格式支持 | Markdown、PDF、Excel 等多种文件格式 |
| 分层索引 | 通过data_structure.md实现智能目录导航 |
| 渐进式检索 | 避免全文加载，按需局部读取，节省 token |
| 强制学习机制 | 处理 PDF/Excel 前必须先学习处理方法 |
| 多轮迭代 | 最多 5 轮智能检索，确保找到最相关信息 |
* *
三、它和传统 RAG 到底有什么本质区别？
用一个比喻就能说清楚：
传统 RAG像是开卷考试的学生——随机翻到哪页抄哪页，翻不到就开始编。
rag-skill像是一个专业研究员——先看目录，制定检索计划，用不同策略找信息，找不够就换关键词反复搜，收集到足够证据才开始回答。
从技术层面看，区别在这几个地方：
从"一次检索"到"多轮迭代"
rag-skill 内置了最多 5 轮的智能检索机制。第一轮找不准？换个关键词、换个思路再来一轮，直到找到足够相关的内容。这就是为什么它在复杂问题上显著优于传统 RAG。
从"全文加载"到"渐进式披露"
传统 RAG 的索引是平铺的，找到 Chunk 就全部丢给 LLM。rag-skill 则通过分层索引（先读目录，再读章节摘要，再读具体段落），大幅减少了无效 token 的消耗。
从"静态流水线"到"动态认知循环"
rag-skill 的检索行为由 LLM 驱动，能根据上一轮检索结果动态调整下一轮策略。这是从"脚本"到"智能体"的本质升级。
* *
四、文件结构长什么样？
在使用之前，先搞清楚 rag-skill 的目录结构：
skilltest/├── .agent/│ └── skills/│ ├── rag-skill/ # 核心知识库检索 Skill│ │ ├── SKILL.md # Skill 主文件（约13KB）│ │ └── references/ # 参考文档│ │ ├── pdfreading.md # PDF 处理方法指南│ │ ├── excelreading.md # Excel 读取方法│ │ └── excelanalysis.md # Excel 分析方法│ └── skill-creator/ # Skill 创建指南（可选）│└── knowledge/ # 你的知识库目录 ├── datastructure.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 Codenpx 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轮] 读取根目录 datastructure.md，定位到"技术规范"目录[检索第2轮] 读取技术规范/datastructure.md，找到 API 文档[检索第3轮] 局部读取 API接口文档.md 的限流相关章节[生成答案] 基于检索到的内容，结合上下文给出准确回答
* *
Step 4：针对 PDF 和 Excel 的特殊处理
rag-skill 内置了"强制学习机制"：
• 遇到 PDF 文件，Agent 会先读取references/pdf_reading.md，学习正确的 PDF 处理方法，再去提取内容
• 遇到 Excel 文件，同样先读excelreading.md和excelanalysis.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
