How to use the RAG Architect agent skill: setup and examples

What the rag-architect skill makes the agent do

An agent skill is a folder of instructions that an AI agent loads when a task matches the skill's description. The rag-architect skill covers the full RAG pipeline: splitting documents into chunks, turning chunks into embeddings (numerical representations used for semantic search), storing them in a vector database, combining keyword and semantic search, reranking results, and measuring retrieval quality.

The skill's SKILL.md file lays out five steps: requirements analysis, vector store design, chunking strategy, retrieval pipeline, and evaluation and iteration. It also includes reference notes on comparing vector databases and embedding models, and on chunking, retrieval optimization and RAG evaluation.

• Chunking documents with LangChain's RecursiveCharacterTextSplitter and metadata such as source and timestamp
• Generating embeddings with OpenAI and indexing them in Qdrant with deterministic IDs
• Hybrid search that combines dense vector results with BM25 keyword scores
• Reranking the top results with Cohere
• Evaluating retrieval with precision@k, recall@k, MRR and Ragas metrics

Install the rag-architect skill

Download the rag-architect ZIP from this page and unzip it. To make the skill available across all your projects, place the unzipped folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal (all projects): ~/.claude/skills/
• Single project: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How to trigger the skill with natural requests

You do not need to name the skill. The skill's description tells the agent when to use it, and it activates for requests about building RAG systems, vector databases, knowledge-grounded AI applications, semantic search, document retrieval, embedding-based indexing or similarity search. The metadata also lists trigger terms such as RAG, vector search, embeddings, knowledge base and context retrieval.

Describe your goal and your constraints. Mention your data, scale and latency needs so the agent can work through requirements first.

• "Design a RAG pipeline for our 5,000 internal support articles, with source citations."
• "Which vector database should I use for a multi-tenant document Q&A feature?"
• "Write chunking code for Markdown documentation and explain the chunk size choice."
• "Help me set up hybrid search and measure precision@10 and recall@10."

Examples of what you get back

The skill asks the agent to deliver a system architecture diagram, a vector database selection with trade-offs, a chunking strategy with rationale, a retrieval pipeline design from query to results, and an evaluation plan with pass/fail thresholds.

The code examples are Python. The chunking example splits text with RecursiveCharacterTextSplitter (chunk_size=800, chunk_overlap=100) and attaches source metadata. The indexing example creates a Qdrant collection sized for OpenAI's text-embedding-3-small model. The evaluation example runs Ragas metrics such as context_precision and context_recall. The skill notes that chunk size should be evaluated on your own data rather than used blindly.

What you need before running the examples

The skill itself runs no scripts, but its code patterns assume a Python environment and several services. The skill uses network access, and the examples call third-party APIs.

• Python
• LangChain (text splitters)
• An OpenAI API key for the embedding examples
• The Qdrant client and a running Qdrant instance
• A Cohere API key for the reranking example
• The rank_bm25 library
• Ragas and datasets libraries for the evaluation example

Safety notes: scripts, network and data

The skill does not run scripts itself, but it does use the network. Its examples send document text to third-party embedding and reranking APIs, which may expose that data. Review this before using sensitive documents.

The skill's own guidance is to load provider API keys from environment variables or a secrets manager and never commit them to source code. Store API keys that way and check the code the agent writes before you run it.

• Do not send confidential or regulated documents to third-party APIs without review.
• Keep API keys out of source code.
• Test on production-like data volumes before deploying.

Tips for getting good results

Ask the agent to evaluate chunk sizes and embedding models on your domain data before committing. The skill's rules call for hybrid search in production, metadata filters for multi-tenant retrieval, and retrieval metrics alongside LLM output quality.

• Give the agent your document types, query volume and latency targets up front.
• Ask for metadata such as source, timestamp and section on every chunk.
• Use deterministic IDs so re-ingesting documents does not create duplicates.
• Track retrieval quality over time, not just once.