The GNO Skill teaches Claude Code, Codex, or OpenClaw to search local documents, read the source, and answer with a traceable reference. It is useful for project decisions, meeting records, PDFs, and Office material stored on your machine.
GNO is the indexing and search program. The Skill teaches an agent its commands. MCP is another interface to the same index. Downloading SKILL.md alone does not create a searchable knowledge base.
Install the program and start small
This guide follows GNO 2.11.0 and its corresponding source documentation. Use Bun 1.4.1 or later. Vector retrieval on macOS needs Homebrew SQLite. The Linux CLI targets x64; Windows targets x64, with Windows ARM unsupported. Inspect an existing installation before replacing it.
Run these in a normal terminal. The version pin keeps the instructions aligned with the release:
bun --version
bun install -g @gmickel/gno@2.11.0
gno --version
For vector retrieval on macOS, also prepare:
brew install sqlite3
Prove keyword retrieval over a small folder before adding an agent or semantic models. Avoid starting with your entire home directory.
First exercise: retrieve a release decision
This is an editor-designed exercise, not a recorded run. Create ~/gno-starter and save a UTF-8 file called 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.
An exact marker reduces ambiguity in your first check. Build and test a keyword index without starting semantic work:
gno setup ~/gno-starter --name starter --no-semantic
gno search "Release Atlas" -c starter --json
gno status --json
Setup creates or reuses the collection, indexes its files, and proves retrieval using a term derived from them. --no-semantic deliberately skips semantic work and its model downloads at this stage. A useful check is a match for your note, not merely an existing database.
Verify the starter collection, the path to release-notes.md, and the matching passage. Copy the actual gno:// URI from the result and read the full source:
gno get "REPLACE WITH THE ACTUAL gno:// URI FROM YOUR RESULT"
Replace that placeholder. Read the owner and prerequisites; snippets can omit conditions. Keyword activation and semantic readiness are separate status fields. Skipped semantic work does not mean keyword retrieval failed.
Connect your agent
Once CLI retrieval works, select one client and run its installer in the terminal:
| Client | Command |
|---|---|
| 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 works across that user's projects; use --scope project for the current project. Do not manage one Skill directory with several installers. The bundled Skill matches the program release. Review it after upgrades and preserve custom changes before using overwrite options.
Start a fresh agent session and try:
Use GNO to find the Release Atlas release and rollback note in the starter collection.
Search by keywords first, then read the full matching document.
Tell me who owns the rollback decision and what must be ready beforehand.
Cite the document location and state anything the source does not establish.
Check actual search and source reading rather than plausible prose. The answer should match your note's owner and conditions and point back to the source. If it does not, test the same collection in the terminal before checking whether the agent loaded the Skill.
target_runtime_unverifiable means the installer can inspect Skill files but cannot prove the agent loaded and used them. You still need that fresh-session retrieval check.
For a daily retrieve-first workflow, GNO offers an optional instruction block. Here is a Codex example:
gno agents install --target codex
gno agents verify --target codex
This changes agent instructions, so inspect the target and existing custom rules. Choose the corresponding supported target for another harness. Verification checks the managed block, not answer correctness. Occasional lookups can start without it.
Skill or MCP?
Clients such as Claude Desktop can use MCP, for example gno mcp install --target claude-desktop. Skills use CLI commands; MCP exposes tool calls. Both access the same index. Choose a supported interface, restart the client, and verify the collection. You do not need both for this exercise.
Add semantic retrieval when needed
Use gno search for names, identifiers, and exact errors. When you do not know the source wording, prepare embeddings and try natural-language retrieval:
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 handles pending content, which may include other collections if you have them. Inspect status and help before broadening the scope. Model download, embedding generation, and retrieval are separate stages. Cold loading can slow the first request. Resource needs vary by model and machine; an author's demo is not a performance guarantee.
Explain output helps you check whether vectors contributed. A wholly lexical fallback reports bm25_only; finding a result does not prove semantic readiness. gno ask "your question" --answer adds generated answers and needs a generation model. Establish search, full-source reading, and citations before adding synthesis.
Three workflows to build on
Project decisions. Keep a project-scoped collection and ask a bounded question, such as why a migration was postponed. Retrieve meeting records and read the decision with its conditions. Distinguish proposals from final decisions and avoid similarly named facts from another project.
PDF and Office research. Add a few local PDFs, DOCX, XLSX, or PPTX files to a dedicated collection. Search a known phrase before trying concepts. Format support does not guarantee every file parses: inspect per-file reports for encrypted, damaged, or incompletely downloaded inputs. GNO does not supply native authorization for live Gmail, WeChat, or website search; obtain or export those inputs through a separate appropriate source.
Edited notes. After changing a source file, run gno update and repeat the search. Finish embeddings when the new text needs semantic retrieval. Consider gno daemon only for continuous background updates; a one-off lookup needs no resident service.
Troubleshoot the correct layer
| Symptom | Check and next step |
|---|---|
gno is not found | Use which gno to check installation and PATH; the agent must find the same program |
| The practice note is missing | Inspect gno ls, collection, and folder; search an exact source term and check keyword activation with gno doctor |
| Vector retrieval fails on macOS | Inspect sqlite-vec in doctor and Homebrew SQLite; working keywords do not prove vectors work |
| A model download stalls | Inspect network, disk, and cache state; run gno models pull --embed to expose errors and use keyword retrieval meanwhile |
| Results omit an edited note | Run gno update, repeat the search, and finish gno embed as needed |
| CLI works but the agent cannot search | Check install target, restarted session, agent PATH, actual calls, and citations |
| First semantic request is slow | Separate download from cold loading and compare the same collection/query; slowness is not an empty-result diagnosis |
Do not clear the database or entire model cache as a first response. Keep the version, command, and error, then follow doctor guidance.
Privacy, boundaries, and alternatives
Local indexing and inference do not require a cloud-model API key, although model downloads use the network. Configured HTTP inference backends and explicit gno.sh publishing introduce other outbound paths. Text retrieved into a cloud-backed agent follows that client's data handling. Local retrieval alone does not mean documents never leave the machine. Start with practice material, then choose collections and clients according to your boundaries.
Ordinary text search may suffice for a known string in code. For Markdown-only material, inspect QMD's current official setup too. QMD also offers a Skill and MCP; older comparisons should not make those sound exclusive to GNO. Consider GNO for mixed formats, a browsable local workspace, and an index shared by several agents. Choose based on material and integration needs rather than a vendor's claimed superiority.