GNO Skill 教 Claude Code、Codex 或 OpenClaw 检索本地资料：先找相关段落，再读取原文，最后给出带出处的回答。适合查项目决策、会议记录，以及散落在电脑里的 PDF 和办公文档。
先分清三个层次：GNO 程序负责索引与搜索；Skill 教 Agent 使用命令；MCP 是连接同一索引的另一种方式。只下载 SKILL.md 不会自动建好知识库。
安装程序，再准备一个小集合
本文按 GNO 2.11.0 与对应源码说明整理。需要 Bun 1.4.1+；macOS 的向量搜索还需要 Homebrew SQLite。Linux CLI 当前支持 x64，Windows 支持 x64，Windows ARM 尚不支持。已有程序时先检查版本，不必直接覆盖安装。
在普通终端执行；这里固定版本，便于与下文参数对照：
bun --version
bun install -g @gmickel/gno@2.11.0
gno --version
macOS 准备向量搜索时另需：
brew install sqlite3
先用一个小文件夹跑通关键词检索，再接入 Agent 和语义模型，不要从整个主目录开始。
第一次练习：找回发布与回滚决定
下面是可自己准备的练习，不是运行记录。创建 ~/gno-starter 文件夹，保存 UTF-8 文件 release-notes.md：
# Release Atlas
The release window is Friday at 14:00 UTC.
A rollback requires the previous artifact and a database backup.
Mina owns the rollback decision; Leo checks the migration logs.
用明确的英文标记先检查精确检索，减少首次练习中的分词、同义词和跨语言干扰；跑通后再用自己的中文资料测试。
gno setup ~/gno-starter --name starter --no-semantic
gno search "Release Atlas" -c starter --json
gno status --json
setup 创建或复用集合、索引文件，并用文件里的词证明能找回真实文档。--no-semantic 主动跳过语义工作和这一阶段的模型下载。成功的检查点不是“存在数据库”，而是搜索结果对应刚才的文件。
核对集合是否为 starter、路径是否对应 release-notes.md、片段是否包含笔记内容。复制结果里的实际 gno:// URI，再读取全文：
gno get "把这里替换为搜索结果中的实际 gno:// URI"
必须替换占位内容。读到负责人和回滚条件，才算完成第一轮检索；摘要可能省略条件。关键词激活与语义状态是分开的，本次跳过语义阶段不等于关键词失败。
接入你使用的 Agent
CLI 能检索后，在普通终端选择一个实际使用的客户端：
| 客户端 | 安装命令 |
|---|---|
| Claude Code | gno skill install --target claude --scope user |
| Codex | gno skill install --target codex --scope user |
| OpenClaw | gno skill install --target openclaw --scope user |
user 对当前用户的多个项目可用；只想在当前项目安装，用 --scope project。不要让多个安装器管理同一个 Skill 目录。程序携带的 Skill 与其版本配套，升级后重新核对 Skill；使用覆盖参数前保留自己的修改。
新开 Agent 会话，可以这样输入：
使用 GNO，在 starter 集合中找 Release Atlas 的发布与回滚说明。
先做关键词搜索，再读取匹配文档全文。
告诉我谁决定回滚、回滚前需要准备什么，并引用文档位置。
资料没写清的地方请说明，不要替我补全。
检查实际检索与读取，而不是只看回答是否听起来合理。回答应符合文件中写下的负责人和条件，并能回到源文档。如果不一致，先在终端复查集合，再检查 Agent 是否加载了 Skill。
安装工具可能显示 target_runtime_unverifiable：它能检查 Skill 文件，但不能替你证明 Agent 已加载并正确使用。新会话的检索和引用检查仍要做。
希望 Agent 日常先查知识库时，还可选择安装官方检索规则。以下是 Codex 示例：
gno agents install --target codex
gno agents verify --target codex
此步骤会写入 Agent 指令，先检查目标与已有自定义规则；其他支持客户端换相应 target。verify 核对规则块，不证明回答正确；只是偶尔查资料时可先不做。
Skill 与 MCP 怎么选？
Claude Desktop 等客户端可使用 MCP，例如 gno mcp install --target claude-desktop。Skill 走命令行，MCP 走工具调用，两者使用同一索引。选客户端支持的入口，安装后重启并检查集合即可，首次练习不必同时装两种方式。
按需添加语义搜索
精确名称、编号、报错用 gno search。不知道原文措辞时，再准备嵌入并使用自然语言查询：
gno models pull --embed
gno embed
gno query "what must be ready before rolling back a release" -c starter --fast
gno query "what must be ready before rolling back a release" -c starter --explain
embed 处理待嵌入内容；已有多个集合时也可能处理其他待办，先查看状态与命令帮助确定范围。下载模型、生成向量和查询是不同阶段。首次加载可能较慢，资源消耗随模型与机器变化，不把作者演示的速度当成自己电脑的保证。
用 --explain 检查本次是否用了向量；完全回退到关键词模式会显示 bm25_only，不能把有结果误认为语义已准备好。gno ask "your question" --answer 可生成答案，还需要生成模型；先把检索、全文读取和引用链路做好，再增加自动总结。
三种可以延伸的工作流
查项目决定。 按项目建立集合，问题限定对象和时间，例如“这个项目为什么延期迁移？”先找会议记录，再读决定及条件。区分当时提议与最终决策，避免混入另一项目的同名术语。
检索 PDF 和办公资料。 把少量本地 PDF、DOCX、XLSX 或 PPTX 放入专门集合，先搜一个确定存在的词，再试概念问题。格式支持不等于所有文件都能解析，加密、损坏或未下载完整的文件要检查逐文件报告。GNO 不提供 Gmail、公众号或网站的原生实时授权搜索；这些资料先要通过另一个合适入口取得或导出。
持续使用改过的笔记。 编辑源文件后执行 gno update，再复查同一搜索；新内容需要语义检索时完成嵌入。需要持续后台更新才考虑 gno daemon，一次性查资料不必启动常驻服务。
常见卡点：先确认哪一层出问题
| 现象 | 检查与下一步 |
|---|---|
找不到 gno | 用 which gno 检查安装和 PATH，Agent 环境也要能找到同一程序 |
| 有索引但找不到练习笔记 | 看 gno ls、集合名、实际目录；搜原文精确短词，用 gno doctor 检查关键词激活 |
| macOS 向量失败 | 看 doctor 的 sqlite-vec，检查 Homebrew SQLite；关键词能用不证明向量能用 |
| 模型下载卡住 | 看网络、磁盘和缓存状态；显式运行 gno models pull --embed 查看错误，先用关键词路径继续工作 |
| 文件改了却还是旧结果 | gno update 后重查，按需完成 gno embed |
| CLI 能查、Agent 不能查 | 检查安装 target、新会话、Agent PATH，核对真实调用与引用 |
| 第一轮语义请求慢 | 区分模型下载与冷加载，固定集合和查询比较，不把慢等同于没匹配 |
不要一开始就清空数据库或整个模型缓存。先保留版本、实际命令与错误，再按 doctor 提示处理。
隐私、适用范围与替代方案
本地索引和本地推理不需要云模型 API key，模型下载仍联网。配置 HTTP 推理后端或使用 gno.sh 发布，是另外的数据出网路径。检索片段交给云端 Agent 后，还受该客户端数据处理方式影响；“本地检索”不等于“资料绝不离开电脑”。从练习材料开始，再按自己的数据边界选择集合和客户端。
只找代码里的已知字符串，普通文本搜索可能已经够用。资料只有 Markdown 时，也可以查看 QMD 的当前官方方案；QMD 同样提供 Skill 和 MCP，旧对比文章不能把这些说成 GNO 独有。GNO 值得考虑的场景是混合文档格式、可浏览的本地工作区，以及同一索引供不同 Agent 使用。按资料类型和接入需求选，不依据厂商自评的效果下结论。