Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →jpoindexter/rag-architecture
Design production retrieval-augmented generation systems — the full ingest→chunk→embed→index→retrieve→rerank→assemble→generate pipeline, with concrete numbers on chunking, embeddings, hybrid search, reranking, query processing, indexing ops, context assembly, and the failure modes that wreck precision.
Passed 22 of 22 test cases with the skill, and 16 of 22 without it.
and 5 more in the full report
6 fixed17 passed either way0 still failing0 broke
Tokens, turns and time describe resource use, not a dollar price.
One of 5 test cases the skill fixed. Same model, same prompt, with and without the skill.
I am writing a technical specification for a high-precision corporate search assistant and need guidance on designing our RAG pipeline from ingestion to generation. Provide a complete architecture spec formatted with markdown headers and diagnostic tables covering: text splitting and metadata enrichment, hybrid search fusion, candidate re-ranking before prompt insertion, index maintenance during embedding model updates, and offline evaluation metrics. The output must clearly define how to prevent context dilution during prompt assembly and how to separate retrieval performance from generation quality during testing.
| Checked | Without skill | With skill |
|---|---|---|
| Specifies re-embedding the entire corpus when updating the embedding model. | Missed | Passed |
| Specifies a target Recall@10 metric of at least 0.9 for retrieval evaluation. | Missed | Passed |
| Instructs the generation prompt to explicitly abstain when context is insufficient. | Passed | Passed |
The instructions your model reads when the skill loads.
RAG is search + prompt, not magic. The model can only answer from what retrieval puts in the context window, so 80% of RAG quality is the retrieval system and 20% is the prompt. Most "the LLM hallucinated" bugs are actually "retrieval returned garbage and the model dutifully summarized it." Build the pipeline so the right chunks land in context with citations, and tell the model to say "I don't know" when they don't. This skill is the concrete playbook: numbers, methods, tables, and the failure modes that cost precision.
Index time (offline, batch): ingest → chunk → embed → index. Query time (online, latency-bound): retrieve → rerank → assemble → generate.
| Stage | Job | Latency budget (typical) |
|---|---|---|
| Ingest | Parse source → clean text + metadata | offline |
| Chunk | Split into retrievable units | offline |
| Embed | Text → vector | offline (docs), ~10–50ms (query) |
| Index | Store vectors + metadata for ANN | offline |
| Retrieve | top-k candidates (dense + sparse) | 10–50ms |
| Rerank | Cross-encoder reorders k→n | 50–300ms |
| Assemble | Select, dedup, order, budget, cite | <5ms |
| Generate | LLM answers from context | 1–10s (dominates) |
Do treat each stage as independently measurable and swappable. Don't optimize generation prompts before you've measured retrieval recall — you're polishing the 20%.
When RAG vs alternatives: RAG when knowledge is large, changing, private, or needs citations (docs, tickets, codebases, policies). Long-context stuffing when the whole corpus fits the window and is small/static — simpler, no index. Fine-tuning to teach style/format/behavior, not facts — fine-tuning bakes knowledge in stale and unverifiable; it's the wrong tool for "answer from current documents." Tool/SQL calling when the answer is a precise lookup or computation over structured data, not fuzzy text. Most production systems combine RAG (facts) + light fine-tuning or few-shot (format) + routing (§7) to the right one per query.
A chunk is the atomic unit of retrieval. Chunk wrong and the answer is split across two chunks that never co-retrieve, or buried in a 2000-token wall of noise. There is no universal best size; it's a recall/precision tradeoff against your content and embedding model's context window.
| Strategy | How | Use when | Cost |
|---|---|---|---|
| Fixed-size | N tokens, hard cut | Uniform prose, fast baseline | Splits mid-sentence/mid-table |
| Recursive | Split on ¶→sentence→word, respecting separators | General default (most corpora) | Slightly more compute |
| Semantic | Split where embedding similarity between adjacent sentences drops below a threshold | Topic-dense docs, mixed subjects | Embedding cost at index time |
| Structural | Split by Markdown heading / HTML section / AST function | Docs, code, anything with structure | Needs a parser per format |
Size + overlap (start here, then tune):
Metadata per chunk (index this, filter and cite on it): source_id, doc_title, section_heading, url, page, created_at, updated_at, version, author/acl. Filtering on metadata at retrieval (WHERE tenant_id = X AND updated_at > …) is often a bigger precision win than any embedding tweak.
test cases passed, vs 16 / 22 without
More skills from the same source and nearby in the registry, with their headline benchmark lift.