Skip to content
Get packs

Guide · Agent skill

How to use the kb-retriever agent skill for local knowledge bases

Updated · written with AI from the project's own documentation and checked against our catalogue data

kb-retriever is an agent skill that lets an AI agent answer questions from a folder of files on your own computer. It walks through index files called data_structure.md, picks the most relevant files, and searches them piece by piece instead of loading whole documents. This guide explains what a skill is, how to install kb-retriever, how to ask for things in natural language, and what it needs to run safely.

Local Knowledge Base RetrieverConardLi/garden-skills · MIT

Quick start

  1. 1Download and unzip. Download the kb-retriever ZIP from this page and unzip it to get the kb-retriever folder.
  2. 2Place the skill folder. Copy kb-retriever into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, you can upload it under Settings → Capabilities → Skills.
  3. 3Prepare your knowledge folder. Put your files in knowledge/ or note the path you will use, and add data_structure.md index files where you can.
  4. 4Install the Python tools. Install pandas and pdfplumber, and pdftotext from poppler-utils. Add pdf2image and poppler if you will use the PDF-to-image script.
  5. 5Ask a question. Ask in plain language, naming the topic and folder or file if you know them.
  6. 6Check the sources. Review the file names and locations the agent cites, and open the originals to verify important figures.

What is an agent skill and what does kb-retriever do?

An agent skill is a folder containing a SKILL.md file and any supporting scripts or reference notes. When the skill is installed, the agent reads its instructions and follows them for matching requests. kb-retriever is designed for questions about a local knowledge directory, by default a folder named knowledge/ in the current project, or a path you name in your request.

The skill works in a fixed order: it navigates the hierarchical data_structure.md index files, then reads reference notes before processing any PDF or Excel file, then searches the processed files. Searches use grep and small windowed reads, so the agent does not load whole files into its context.

  • Reads data_structure.md files at each folder level to choose relevant subfolders and files.
  • Requires reading references/pdf_reading.md or the Excel reference notes before handling PDF or Excel files.
  • Runs up to 5 search rounds per question, then stops and reports what it found or did not find.
  • Cites file names and approximate locations (page, section or line) in its answer.

Install kb-retriever with a ZIP download

Download the kb-retriever ZIP from this page and unzip it. The skill folder is named kb-retriever and contains SKILL.md, README.md, README.zh-CN.md, manifest.json, a references/ folder and a scripts/ folder.

For a personal install, place the kb-retriever folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

  • Personal install: ~/.claude/skills/kb-retriever/
  • Project install: .claude/skills/kb-retriever/ inside your project
  • Claude apps: Settings → Capabilities → Skills, then upload the skill
~/.claude/skills/kb-retriever/SKILL.md

Set up your knowledge folder and index files

Put your files in a folder named knowledge/ in your project, or tell the agent where they are. The skill expects mixed formats such as .md, .txt, .pdf and .xlsx, often grouped into subfolders by type or business purpose.

The skill works best when each folder has a data_structure.md file that lists its subfolders and files and explains what each one is for. Index files can be nested, so deeper folders can have their own. Without them, the skill has less guidance for choosing files and results may be weaker or slower.

  • Default root: knowledge/ in the current project.
  • A custom path works too, for example ./docs or /data/kb, if you state it in your request.
  • If the default folder is missing, the agent should ask you for the correct path rather than guess.

How to trigger the skill with natural requests

You do not need a special command. Ask a question about your files in plain language, and mention the knowledge base or folder when it helps. The skill's description covers requests to answer from a knowledge folder, retrieve information or look up material.

Be specific about the topic, time range or file type when you can. Naming a file or a folder narrows the search and makes the answer easier to verify.

  • Answer from the knowledge base: what does our API gateway timeout policy say?
  • Search my knowledge folder at ./docs for the 2023 Q1 sales summary.
  • Look up the error_code mapping in the Excel reports under knowledge/.

Install the Python tools the skill uses

The skill uses Python with pandas and pdfplumber for Excel and PDF work. For PDF-to-image conversion, the included script needs pdf2image and its poppler dependency. Text extraction from PDFs is faster with the pdftotext command-line tool from poppler-utils, which the skill recommends.

The source does not give exact install commands or version numbers, so check the reference notes in references/ and your system's package manager for the correct steps on your machine.

  • Python with pandas and pdfplumber (required for Excel and PDF work).
  • pdf2image and poppler, needed for scripts/convert_pdf_to_images.py.
  • pdftotext from poppler-utils, recommended for PDF text extraction.

Safety notes: scripts, network and sensitive files

kb-retriever runs scripts; the package includes scripts/convert_pdf_to_images.py. The skill does not use the network, and its instructions tell the agent not to use web search when answering from the knowledge base. Answers are limited to what is on disk.

Everything the agent reads becomes part of its conversation. If your files contain confidential data, review them before asking the agent to read them, and check whether your AI service is appropriate for that content.

  • Review scripts before running them, as with any skill that runs code.
  • The skill is not meant for searching the open web.
  • Sensitive files are read into the conversation, so review them first.

Tips for better answers

Give the agent the narrowest useful scope. Point it to a folder or file when you know where the answer should be. If the first answer is incomplete, ask a follow-up with a more specific keyword, a field name or a date range.

When the agent reports that information may not be in the knowledge base, treat that as useful: it means the search did not find a match, not that the answer is hidden.

  • Name the file or folder when you know it.
  • Use exact field names or terms from your documents.
  • Add a time range such as a quarter or version if it matters.
  • Keep index files up to date so the agent can navigate efficiently.

What people use it for

  • Finding a specific policy or spec in a structured folder of internal Markdown documents.
  • Pulling figures from a large Excel report without loading the whole workbook.
  • Locating a passage in a PDF manual and getting the page reference.
  • Checking which configuration or mapping file defines a given field or code.

Frequently asked questions

Is kb-retriever free to use?

The skill is published under the MIT licence, as stated on this page. Check the licence file in the package for the full terms.

What do I need to run kb-retriever?

You need a local folder of knowledge files, ideally with data_structure.md index files. For PDF and Excel work you need Python with pandas and pdfplumber, and pdftotext from poppler-utils is recommended. The PDF-to-image script also needs pdf2image and poppler.

How do I install the kb-retriever skill?

Download the ZIP from this page and unzip it. Put the kb-retriever folder in ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it in the Claude apps under Settings → Capabilities → Skills.

Does kb-retriever search the internet?

No. The skill tells the agent not to use web search, so it answers only from files on your disk. It does not use the network.

Why does the agent ask for my knowledge folder path?

By default it looks for knowledge/ in the current project. If that folder is missing or cannot be accessed, the skill tells the agent to ask you for the real path instead of guessing.

How is kb-retriever different from just asking a chatbot about my files?

The skill navigates index files, reads PDF and Excel reference notes before processing them, and searches in small pieces rather than loading whole files. It also cites file names and approximate locations. Results depend on how well your folder is organised and indexed.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

kb-retriever suits teams and analysts who keep structured local documents or large Excel workbooks and want sourced, bounded answers from them. If you need web research, or your folders have no index files and little structure, pick a different approach or first add data_structure.md files.

Download the skill