rag-skill teaches an assistant to search a local folder without loading it all at once

A Skill is a set of instructions, not a library

The repository calls itself a demonstration project for an AI Skill dedicated to local knowledge base retrieval, and the structure shows what that means in practice. There is no package to install and no service to run. The top level contains three entries: the .agent directory, the README, and a knowledge folder of sample data.

Inside .agent there is a skills directory holding the core Skill at .agent/skills/rag-skill, with a SKILL.md file of about 13 KB and a references directory containing three method guides, one for PDF reading and two for Excel, plus an optional skill-creator directory that explains how Skills are written in the first place.

The knowledge folder is the demonstration corpus, and it is deliberately heterogeneous. There is an AI Knowledge directory with 14 PDF industry reports, a Financial Report Data directory with 6 PDFs of company results, an E-commerce Data directory with 4 Excel workbooks covering customers, employees, inventory and sales orders, and a Safety Knowledge directory of Markdown notes on web security topics.

So the audience is someone building an assistant that has to answer questions from a mixed collection of local files, and the repository shows both halves of that job: the instructions and a corpus with enough variety to expose the awkward cases, a PDF that has to be converted before it can be searched and a spreadsheet that must not be loaded whole.

Every directory carries a data_structure.md index

The first of the core design ideas is hierarchical indexing. Each directory in the knowledge base contains a data_structure.md file that explains what the subdirectories and files are for, when they apply, and what data range they cover. The assistant reads the root index, recognises which area of the corpus is relevant, and descends rather than searching everything.

The README is explicit about the purpose: the assistant reads the index files to pick the most relevant path and avoid blind searching. In the AI trends example the flow is to read the root knowledge/data_structure.md, enter the AI Knowledge directory, read its subdirectory index, and only then locate the specific report file.

The cost of the approach is that someone has to write the index. The README documents exactly that as a maintenance task for anyone adding their own knowledge area: create a directory under knowledge, add a data_structure.md describing its purpose, put the relevant PDF, Excel or Markdown files in it, and then update the root knowledge/data_structure.md. A template is provided with sections for purpose, a per-file description of what each file covers, and the data range such as time span and version information.

That is the trade in one sentence. You maintain a directory of metadata instead of relying on the assistant to guess from filenames, and in exchange the assistant does not waste turns on directories that cannot answer the question.

The assistant must read the method guide before it opens the file

The second rule is the one that makes this more than a retrieval demo. When the task involves a PDF or an Excel file, the Skill forces a learning step first: the assistant has to read references/pdf_reading.md, or references/excel_reading.md and references/excel_analysis.md, understand the recommended tools and commands, and only then process the file.

The README states the required sequence with a checklist, and then lists what is forbidden: processing a PDF without learning first, processing Excel without learning first, and skipping the processing step and going straight to retrieval.

The stated reason appears in the FAQ. Reading the references first is there to make sure the right tool and method are used, and to avoid three specific failures: using an inefficient processing method, dumping output that consumes a large number of tokens, and repeating failed approaches.

Whether forcing a read is the right call depends on how the assistant is wired. If the model already knows the tools, the extra step is overhead on every query. If the model does not know them, the same step is what stops it from trying three wrong extraction commands and burning the turn budget. The design assumes the second case, and it accepts a fixed cost to remove a variable one.

Progressive retrieval in at most five rounds

The third principle is that the assistant must not read whole files. The core rule listed in the README is to avoid loading an entire file at once, to use grep to locate keywords, to read only the context around the matching lines with a limit of 200 to 500, and to iterate over multiple rounds to narrow the range.

The iteration loop has five steps per round. Generate or update the search keywords, choose a file that has not been searched enough, run the search with grep or a partial read, analyse the extracted context, and decide whether there is enough to answer.

There are two termination conditions: enough information has been found, or five attempts have been made. The cap matters as much as the loop, because it is what keeps a question about a 135 MB folder of reports from turning into an open ended crawl.

The tool guidance that supports this is specific. grep is for keyword search with a precise include and path, read_file is for partial reads with a reasonable limit, pdftotext is for PDF text extraction and must output to a file rather than to standard output, and pandas is for spreadsheet analysis with nrows used to limit how many rows are read. A separate note covers Excel directly: read the first 10 to 50 rows to understand the structure, identify the key columns such as time, ID and category, then filter with a condition such as `df[df['column'] == value]`, and avoid reading the whole table at once.

For a very large PDF the FAQ gives the page-limited variant, `pdftotext -f 1 -l 10`, then grep over the extracted text, then read only near the matches.

A first run against the e-commerce workbooks

Nothing needs to be installed, which is unusual for a repository of this kind. The README's environment section lists what the assistant has to be able to do, and that is the entire setup: grep for text search, read_file for reading files, pdftotext or pdfplumber for PDF handling, and pandas for Excel analysis.

So the first use is a question, and the Skill's job is to route it. Take the inventory question from the README, which asks which products are running low on stock. The flow is: identify the E-commerce Data directory from the index, locate inventory.xlsx inside it, read references/excel_reading.md and references/excel_analysis.md first, then use pandas to read the first 50 rows to understand the structure, identify the stock related column such as stock_quantity, and filter for low stock before answering.

The files that flow touches are the four workbooks in that directory:

    ├── customers.xlsx
    ├── employees.xlsx
    ├── inventory.xlsx
    └── sales_orders.xlsx

For the safety question the flow is shorter, because Markdown needs no conversion. The assistant identifies the Safety Knowledge directory, uses grep to search the Markdown files for the term, reads only the matching paragraphs, and extracts the countermeasures from them.

For a question about the AI industry reports, the PDF path is the longest. The assistant reads the root index, descends into the AI Knowledge directory, reads the subdirectory index, locates the report, reads references/pdf_reading.md, extracts the text with pdftotext to a temporary file, greps that file for the keywords, and then reads only the context around the matches.

That last step is the one to notice. The text is extracted to a file and searched, rather than streamed into the conversation, and the FAQ says the same for very large PDFs, where only a page range such as `pdftotext -f 1 -l 10` is extracted before the search.

The sample corpus, and the figures the README attaches to it

The bundled knowledge base is large enough to be a real test. The AI Knowledge area holds 14 PDFs totalling roughly 135 MB, the financial area holds 6 PDFs of quarterly and annual company reports, the e-commerce area holds 4 workbooks, and the safety area is Markdown covering web vulnerability topics such as XSS, SQL injection and CSRF.

The README attaches a table of performance figures to this sample set: 30 plus files, about 200 MB in total, an average retrieval time of 5 to 15 seconds, token consumption of 2K to 8K under the progressive retrieval approach, and an accuracy figure of 85 percent or better when explicit keywords are given.

Those are the project's own numbers for its own sample data, and they are worth reading with care rather than quoting. The accuracy figure is explicitly conditional on the query providing clear keywords, which is a claim about well-formed questions rather than about the corpus. The token figure is the interesting one, because it is the point of the whole design: a progressive search over a 200 MB corpus is said to cost a few thousand tokens instead of the tens of thousands a naive full read would need.

The FAQ adds the practical advice that matches those numbers. To improve retrieval accuracy, give more specific keywords, specify a time range or file name, and use domain terminology rather than general vocabulary. In other words, the accuracy number holds when the user does the narrowing work, which is a reasonable expectation for an assistant rather than a search engine.

Archived, and pointing somewhere else

The first thing the README says is that the project is archived. The notice states that the repository has stopped being maintained and will no longer be updated, and that the author's subsequent open source Skills will all be published in a different repository, garden-skills.

The GitHub archived flag is not set on this repository, so the archive exists in the README rather than in the platform's own metadata, and the last push was on 2026-04-25. The repository also has no GitHub releases, so there is no version series to pin and nothing to upgrade to.

The licence situation is equally informal. There is no LICENSE file in the repository, and the licence section says the project is for demonstration and learning purposes only, with the sample data coming from public reports and simulated data and provided for reference. That is a statement of intent rather than a licence, so if you want to reuse the Skill, the reference guides or the corpus in a product, you need permission from the author rather than relying on the terms as written.

The contribution section lists what the author wanted help with: new sample knowledge areas, suggestions for improving the Skill, improvements to the reference documents, and bug fixes. Since the repository is no longer maintained, the realistic route for any of those is the successor repository.

Where this Skill is the wrong tool

The first wrong case is a corpus without an index. The Skill depends on every directory having a data_structure.md that someone wrote. If your files sit in a flat folder with no metadata, the assistant has to fall back on searching, which is the behaviour the Skill is designed to avoid, and the progressive retrieval advantage shrinks towards nothing.

The second is a corpus that fits comfortably in the context window. If the whole knowledge base is a handful of Markdown files, the layered index, the method guides and the five round cap are all overhead. The rules make sense when reading everything would be expensive or impossible, which is the case for the 135 MB of PDFs in the sample and not the case for a folder of notes.

The third is a question that needs the whole file. The design deliberately avoids loading a document and reads only matched fragments. If the answer is a global property of a document, such as its overall argument, its full structure or a trend that only appears when you read the sections in order, partial reads will not produce it, and the five round cap will stop the assistant before it tries.

The alternative approach for the same problem is a real indexing pipeline, where documents are chunked, embedded and stored in a vector database, and the assistant queries that index. The difference in approach is exactly the trade the Skill refuses to make. A retrieval pipeline indexes once and answers many questions with semantic matching, at the cost of an embedding model, a store, an embedding step for every document and an index that goes stale when files change. The Skill in this repository indexes nothing and embeds nothing, and it pays for that with a manual index file per directory, a rule that each assistant has to follow correctly, and a keyword search that only finds the words you thought of.

Editorial conclusion

Adopt the pattern if you want your assistant to interrogate a folder of reports and spreadsheets without pulling whole files into the context window, because the layered index and the five iteration cap are reusable ideas regardless of the sample data. Do not adopt this repository as a dependency, since it is a demonstration with no licence file, whose README restricts it to learning purposes and whose author has moved later work to garden-skills. Before you copy any of it, read the two reference guides, pdf_reading.md and excel_reading.md, because the Skill's rules make no sense without them, and check the archive notice at the top of the README, which points to a different repository for everything that comes next.

Frequently asked questions

Official sources

1. ConardLi/rag-skill on GitHub
2. Issues
3. README