rag-skills 1.0.0

package/skills/retrieval-strategies/self-rag.md

@@ -0,0 +1,108 @@
+---
+title: "Self-RAG - Self-Reflective Retrieval"
+description: "Use self-reflective loops to make dynamic retrieval decisions and assess response quality."
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+category: "retrieval-strategies"
+tags: ["self-rag", "reflection", "retrieval-decision", "relevance-evaluation"]
+---
+
+## Overview
+Self-RAG is a reflective framework that decides whether to retrieve information, evaluates the relevance of retrieved documents, assesses response support, and rates output utility. This dynamic approach optimizes retrieval decisions based on query characteristics and retrieved content quality.
+
+## Problem Statement
+Traditional RAG systems lack introspection:
+- **Blind Retrieval**: Always retrieves regardless of whether it's needed
+- **Irrelevant Context**: Cannot filter out irrelevant retrieved documents
+- **No Grounding Assessment**: Cannot verify if responses are supported by context
+- **Fixed Strategy**: Cannot adapt to different query types
+- **Poor Quality Control**: No mechanism to assess output utility
+
+## Key Concepts
+- **Retrieval Decision**: LLM determines if retrieval is necessary for the query
+- **Relevance Evaluation**: Each retrieved document assessed for query relevance
+- **Response Generation**: Answers generated using only relevant context
+- **Support Assessment**: Evaluation of how well responses are grounded in context
+- **Utility Rating**: Assessment of how well the response addresses the original query
+
+## Implementation Guide
+
+### Step 1: Implement Retrieval Decision
+Use an LLM to determine if the query requires retrieval or can be answered directly.
+
+**Why**: Not all queries need retrieval—some can be answered from general knowledge or are simple enough that retrieval adds unnecessary cost and latency.
+
+Direct the LLM to make a binary decision: retrieve from documents or answer without retrieval.
+
+### Step 2: Implement Relevance Evaluation
+Assess each retrieved document for its relevance to the original query.
+
+**Why**: Not all retrieved documents are equally relevant. Filtering ensures only pertinent information is used for generation, reducing noise and improving answer quality.
+
+For each retrieved document, have the LLM rate its relevance to the query on a scale or classify as relevant/irrelevant.
+
+### Step 3: Implement Context Filtering
+Build a pipeline that filters documents based on relevance scores.
+
+**Why**: A systematic filtering process ensures consistent quality and prevents irrelevant information from contaminating the generation process.
+
+Select only documents that meet a relevance threshold for use in response generation.
+
+### Step 4: Implement Response Generation
+Generate responses using only relevant context, or without context if none is relevant.
+
+**Why**: Using only relevant context improves factual grounding. When no relevant context exists, the system can still provide a response (with appropriate caveats) rather than forcing use of irrelevant information.
+
+Generate responses conditioned on whether relevant context was found—using context if available, answering from general knowledge if not.
+
+### Step 5: Implement Support Assessment
+Evaluate how well the generated response is supported by the context.
+
+**Why**: Support assessment provides a confidence metric and helps detect hallucinations—responses not supported by context can be flagged or refined.
+
+Have the LLM classify the level of support: fully supported, partially supported, or no support.
+
+### Step 6: Implement Utility Rating
+Rate the usefulness of the generated response for the original query.
+
+**Why**: Utility rating provides feedback on response quality and can be used for continuous improvement, A/B testing, or filtering low-quality responses.
+
+Rate the response on a scale (e.g., 1-5) based on how well it addresses the user's query.
+
+### Step 7: Build Complete Self-RAG Pipeline
+Combine all components into a cohesive reflective system.
+
+**Why**: A complete pipeline with clear decision points allows for monitoring, optimization, and understanding of system behavior.
+
+Chain together the retrieval decision, relevance evaluation, response generation, and assessment steps into a unified workflow.
+
+For implementation patterns, see the [Self-RAG paper](https://arxiv.org/abs/2310.11511), [LangGraph agentic RAG guide](https://docs.langchain.com/oss/python/langgraph/agentic-rag), and [LlamaIndex SelfRAG pack](https://docs.llamaindex.ai/en/stable/api_reference/packs/self_rag/).
+
+## When to Use This Skill
+- Building RAG systems where response accuracy is critical
+- When retrieval quality varies significantly across queries
+- For applications requiring confidence scoring
+- When you need to detect and handle hallucinations
+- For systems that must adapt to different query types
+
+## When NOT to Use This Skill
+- For extremely latency-sensitive applications (multiple LLM calls)
+- When using a vector database with high-precision retrieval
+- For simple FAQ systems where queries are well-structured
+- When cost is a major constraint (multiple LLM calls per query)
+- For real-time systems with strict latency budgets
+
+## Related Skills
+- [CRAG (Corrective RAG)](./crag-corrective-rag.md) - Dynamic correction approach
+- [Adaptive Retrieval](./adaptive-retrieval.md) - Query-based strategy selection
+- [Explainable Retrieval](./explainable-retrieval.md) - Citation and traceability
+
+## Metrics & Success Criteria
+- **Retrieval Efficiency**: Reduced unnecessary retrievals by 30-50%
+- **Relevance Filtering**: High precision in identifying irrelevant documents
+- **Response Accuracy**: Improved factual grounding of responses
+- **Support Confidence**: Reliable support assessment metrics
+- **Utility Rating**: Consistent utility scores correlate with human evaluation

package/skills/vector-databases/choosing-vector-db-by-datatype.md

@@ -0,0 +1,112 @@
+---
+title: "Choosing Vector Database by Data Type"
+description: "Choose a vector database based on content type, metadata needs, and query patterns."
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+category: "vector-databases"
+tags: ["selection", "text", "multimodal", "code", "comparison"]
+---
+
+## Overview
+Selecting the right vector database depends heavily on your data type (text, images, code, multimodal) and use case requirements. This skill provides a decision framework for choosing between popular vector databases based on data characteristics and operational constraints.
+
+## Problem Statement
+Different vector databases excel at different use cases:
+- Text-heavy workloads need efficient semantic search
+- Code repositories require specialized embedding handling
+- Multimodal data needs multi-vector support
+- Production constraints (cost, scaling, latency) vary widely
+- Choosing the wrong database leads to poor performance or high costs
+
+## Key Concepts
+- **Data Type**: Text, code, images, audio, or multimodal combinations
+- **Embedding Model Compatibility**: Support for different embedding dimensions and models
+- **Multi-Vector Support**: Ability to store and search multiple embeddings per document
+- **Scaling Model**: Vertical vs. horizontal scaling capabilities
+- **Deployment Model**: Self-hosted, managed cloud, or hybrid
+
+## Database Comparison Matrix
+
+### Text-Heavy Workloads
+
+| Database | Strengths | Weaknesses | Best For |
+|----------|-----------|------------|----------|
+| **[Qdrant](https://qdrant.tech/documentation/)** | Open-source, excellent filtering, hybrid search | Smaller community than Pinecone | Production RAG, cost-sensitive |
+| **[Pinecone](https://docs.pinecone.io/)** | Managed, excellent scalability, easy setup | Expensive, vendor lock-in | Enterprise, zero-ops requirement |
+| **[Weaviate](https://docs.weaviate.io/weaviate/introduction)** | GraphQL API, modular, schema-first | Learning curve, can be complex | Teams wanting flexible schemas |
+| **[ChromaDB](https://docs.trychroma.com/)** | Simple API, embeds easily, open-source | Less scalable for production | Prototyping, small-medium scale |
+| **[Milvus](https://milvus.io/docs)** | Highly scalable, feature-rich | Complex setup, heavy | Enterprise with data team |
+
+### Code & Documentation
+
+| Database | Strengths | Weaknesses | Best For |
+|----------|-----------|------------|----------|
+| **[Qdrant](https://qdrant.tech/documentation/)** | Great metadata filtering, payload indexing | No code-specific features | Code search with metadata |
+| **[Weaviate](https://docs.weaviate.io/weaviate/introduction)** | Graph traversals, relationship handling | Setup complexity | Code graph/context search |
+| **[ChromaDB](https://docs.trychroma.com/)** | Simple integration with code tools | Limited scaling | IDE integrations, code assistants |
+| **[Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html)** | Text search + vectors, mature ecosystem | Not vector-first | Hybrid code + keyword search |
+
+### Multimodal (Text + Images)
+
+| Database | Strengths | Weaknesses | Best For |
+|----------|-----------|------------|----------|
+| **[Weaviate](https://docs.weaviate.io/weaviate/introduction)** | Multi-vector, CLIP support built-in | Performance overhead | Image + text search |
+| **[Qdrant](https://qdrant.tech/documentation/)** | Multi-vector via named vectors | Manual configuration | Custom multimodal pipelines |
+| **[Pinecone](https://docs.pinecone.io/)** | Multiple namespaces, sparse vectors | Limited multi-vector | Limited multimodal needs |
+| **[Milvus](https://milvus.io/docs)** | Multi-vector, hybrid search | Complex setup | Large-scale multimodal systems |
+
+## Implementation Guide
+
+### Step 1: Analyze Your Data Type
+Identify your primary data characteristics.
+
+**Why**: Data profiling ensures your choice aligns with actual requirements rather than hype or popularity.
+
+### Step 2: Evaluate Database Candidates
+Score databases based on your requirements.
+
+**Why**: A scoring framework provides objective criteria rather than subjective opinions.
+
+### Step 3: Implement Type-Specific Strategies
+Tailor your approach to each data type.
+
+**Why**: Different data types require fundamentally different approaches for optimal performance.
+
+### Step 4: Proof of Concept
+Create a PoC to validate your choice.
+
+**Why**: Nothing beats testing with your actual data and queries—PoCs reveal real-world performance characteristics.
+
+### Step 5: Migration Path
+Plan for potential future database changes.
+
+**Why**: An export strategy prevents lock-in and enables future migrations if requirements change.
+
+For comparisons and vendor docs, use [ANN Benchmarks](https://ann-benchmarks.com/), [Qdrant documentation](https://qdrant.tech/documentation/), [Pinecone documentation](https://docs.pinecone.io/), [Weaviate documentation](https://docs.weaviate.io/weaviate/introduction), [ChromaDB documentation](https://docs.trychroma.com/), [Milvus documentation](https://milvus.io/docs), and [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html).
+
+## When to Use This Skill
+- Starting a new RAG project and need database selection guidance
+- Evaluating whether to switch vector databases
+- Building a multimodal RAG system
+- When cost is a significant constraint
+- When scaling requirements are unclear
+
+## When NOT to Use This Skill
+- When you already have a working solution that meets requirements
+- For trivial prototypes (< 10k documents) where any DB will work
+- When using a managed service that handles database choice
+
+## Related Skills
+- [Qdrant Setup for RAG](./qdrant-setup-rag.md) - Setting up Qdrant
+- [RAG for Code Documentation](../data-type-handling/rag-for-code-documentation.md) - Code-specific RAG
+- [RAG for Multimodal Content](../data-type-handling/rag-for-multimodal-content.md) - Multimodal RAG
+
+## Metrics & Success Criteria
+- **Selection Accuracy**: Chosen database meets functional requirements
+- **Performance**: Meets or exceeds latency/throughput targets
+- **Cost**: Within budget constraints
+- **Scalability**: Can grow with expected data volume
+- **Operational Overhead**: Matches team capabilities

package/skills/vector-databases/qdrant-for-production-rag.md

@@ -0,0 +1,88 @@
+---
+title: "Qdrant for Production RAG"
+description: "Run Qdrant reliably in production with scaling, backups, monitoring, and operational tuning."
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+category: "vector-databases"
+tags: ["production", "scaling", "optimization", "deployment"]
+---
+
+## Overview
+Productionizing a RAG system with Qdrant requires considerations beyond basic setup: horizontal scaling, high availability, performance optimization, monitoring, and cost management. This skill covers deploying Qdrant at scale with resilience and efficiency.
+
+## Problem Statement
+Moving from development to production introduces challenges:
+- Single-node deployments can't handle increasing query/load volume
+- Indexing parameters need tuning for performance vs. recall trade-offs
+- Data durability and backup strategies are critical
+- Monitoring and alerting are essential for production reliability
+- Cost optimization becomes important as scale increases
+
+## Key Concepts
+- **Horizontal Scaling**: Distributing load across multiple Qdrant nodes
+- **Replication**: Data redundancy for high availability
+- **Sharding**: Partitioning data across nodes for scalability
+- **Performance Tuning**: Optimizing index parameters and cache settings
+- **Observability**: Monitoring metrics and setting up alerts
+
+## Implementation Guide
+
+### Step 1: Choose Deployment Strategy
+Select between self-hosted, managed cloud, or hybrid approaches.
+
+**Why**: Self-hosted gives control but requires ops overhead; managed cloud provides scalability with less operational burden.
+
+### Step 2: Configure Production Collections
+Optimize collection parameters for production workloads.
+
+**Why**: Production configurations balance performance, memory usage, and build time based on workload characteristics.
+
+### Step 3: Implement Efficient Batch Operations
+Optimize ingestion and query batching for production scale.
+
+**Why**: Asynchronous batch operations maximize throughput and prevent bottlenecks during ingestion.
+
+### Step 4: Configure Caching and Connection Pooling
+Optimize connection handling and implement query caching.
+
+**Why**: Caching reduces load on Qdrant for repeated queries and improves response times for common questions.
+
+### Step 5: Set Up Monitoring and Alerting
+Implement observability for production RAG systems.
+
+**Why**: Metrics enable proactive issue detection and capacity planning before problems impact users.
+
+### Step 6: Implement Backup and Recovery
+Set up automated backups for data durability.
+
+**Why**: Regular backups protect against data loss and enable quick recovery from failures.
+
+For deployment guidance, review the [Qdrant snapshots tutorial](https://qdrant.tech/documentation/tutorials-operations/create-snapshot/), [Qdrant snapshots concept](https://qdrant.tech/documentation/concepts/snapshots/), and [HNSW tuning guide](https://github.com/nmslib/hnswlib/blob/master/ALGO_PARAMS.md).
+
+## When to Use This Skill
+- Deploying RAG to production environments
+- Handling high query volume (> 100 QPS)
+- When data durability and high availability are critical
+- When scaling beyond single-node deployments
+- For cost optimization at scale
+
+## When NOT to Use This Skill
+- Early prototyping or MVP development
+- Small datasets (< 100k vectors)
+- When using managed services that handle these concerns
+- For experimental or temporary deployments
+
+## Related Skills
+- [Qdrant Setup for RAG](./qdrant-setup-rag.md) - Basic setup
+- [Optimize Retrieval Latency](../performance-optimization/optimize-retrieval-latency.md) - Performance tuning
+- [Multi-Agent RAG](../../examples/multi-agent-rag.md) - Complex workflows
+
+## Metrics & Success Criteria
+- **Availability**: > 99.9% uptime
+- **Query Latency**: P50 < 50ms, P99 < 200ms for typical queries
+- **Ingestion Throughput**: > 100,000 vectors/hour
+- **Recovery Time**: RTO < 1 hour, RPO < 5 minutes
+- **Cost Efficiency**: < $0.01 per 1000 queries at scale

package/skills/vector-databases/qdrant-setup-rag.md

@@ -0,0 +1,86 @@
+---
+title: "Qdrant Setup for RAG"
+description: "Set up Qdrant for RAG with collections, payload filtering, and batch ingestion."
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+category: "vector-databases"
+tags: ["qdrant", "setup", "ingestion", "filtering"]
+---
+
+## Overview
+Qdrant is an open-source vector similarity search engine designed for high-performance RAG applications. This skill covers setting up Qdrant, creating collections with proper indexing, implementing filtering with metadata, and managing document ingestion.
+
+## Problem Statement
+Setting up a vector database for RAG involves multiple considerations:
+- Choosing the right distance metric for your embedding model
+- Configuring optimal index parameters for performance vs. recall
+- Structuring metadata for effective filtering
+- Handling batch ingestion efficiently
+- Managing collection schema changes
+
+## Key Concepts
+- **Distance Metric**: Cosine similarity, dot product, or Euclidean distance for vector comparisons
+- **Index Type**: HNSW (Hierarchical Navigable Small World) for approximate nearest neighbors
+- **Payload Filtering**: Querying vectors based on associated metadata
+- **Collection Schema**: Defining vector dimensions and payload structure
+- **Batch Operations**: Efficient bulk insertion of vectors
+
+## Implementation Guide
+
+### Step 1: Install and Initialize Qdrant
+Set up Qdrant locally or connect to a cloud instance.
+
+**Why**: Docker provides an isolated environment with persistence, while the cloud option offers managed scalability.
+
+### Step 2: Create a Collection
+Configure collection parameters based on your embedding model and use case.
+
+**Why**: Proper configuration at creation time avoids expensive re-indexing later. COSINE is default for normalized embeddings.
+
+### Step 3: Design Metadata Schema
+Structure your payloads (metadata) for effective filtering.
+
+**Why**: Well-structured metadata enables powerful filtering queries and helps organize retrieval results.
+
+### Step 4: Ingest Documents
+Upload documents with their embeddings and metadata.
+
+**Why**: Batch operations significantly improve ingestion performance compared to individual uploads.
+
+### Step 5: Implement Filtering Queries
+Query with metadata filters for targeted retrieval.
+
+**Why**: Filtering enables domain-specific retrieval (e.g., "search only in documentation" or "search only code examples").
+
+### Step 6: Monitor and Maintain
+Set up monitoring for collection health.
+
+**Why**: Monitoring helps identify performance issues and scaling needs before they impact users.
+
+See the [Qdrant documentation](https://qdrant.tech/documentation/), [Qdrant filtering](https://qdrant.tech/documentation/concepts/filtering/), [Qdrant Python client](https://github.com/qdrant/qdrant-client), and the [HNSW paper](https://arxiv.org/abs/1603.09320) for production-ready setup patterns.
+
+## When to Use This Skill
+- Building a new RAG application from scratch
+- Setting up a local vector database for development
+- Migrating from another vector database to Qdrant
+- When you need open-source with no vendor lock-in
+
+## When NOT to Use This Skill
+- When you need managed, zero-ops solution (consider Qdrant Cloud)
+- For very small datasets (< 1000 vectors) where a simple list might suffice
+- When you need specialized features like multi-vector indexing (consider other DBs)
+
+## Related Skills
+- [Qdrant for Production RAG](./qdrant-for-production-rag.md) - Scaling for production
+- [Choosing Vector DB by Datatype](./choosing-vector-db-by-datatype.md) - Database selection guide
+- [Optimize Retrieval Latency](../performance-optimization/optimize-retrieval-latency.md) - Performance tuning
+
+## Metrics & Success Criteria
+- **Setup Time**: < 10 minutes to get a working collection
+- **Ingestion Speed**: > 10,000 vectors/minute on modest hardware
+- **Query Latency**: < 50ms for queries on 1M vectors
+- **Indexing**: Automatic HNSW indexing within reasonable time
+- **Recall**: > 0.95 for 10 nearest neighbors

package/templates/skill-template.md

@@ -0,0 +1,53 @@
+---
+title: "Skill Name"
+description: "Use this template to define an agent-friendly RAG skill with concise guidance, references, and allowed tool access."
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+category: "chunking|vector-databases|retrieval-strategies|data-type-handling|performance-optimization|evaluation-metrics|rag-agents|deployment"
+tags: ["tag1", "tag2", "tag3"]
+---
+
+## Overview
+[2-3 sentence description of what this skill covers and why it matters for RAG systems]
+
+## Problem Statement
+[Describe the specific challenge this skill addresses]
+
+## Key Concepts
+- **Concept 1**: Brief explanation
+- **Concept 2**: Brief explanation
+- **Concept 3**: Brief explanation
+
+## Implementation Guide
+
+### Step 1: [Step Name]
+[Detailed explanation with reasoning]
+
+### Step 2: [Step Name]
+[Detailed explanation with reasoning]
+
+### Step 3: [Step Name]
+[Detailed explanation with reasoning]
+
+## When to Use This Skill
+- Use case 1
+- Use case 2
+- Use case 3
+
+## When NOT to Use This Skill
+- Anti-pattern 1
+- Anti-pattern 2
+
+## Related Skills
+- [Related Skill 1](../category/skill-name.md)
+- [Related Skill 2](../category/skill-name.md)
+
+## Implementation Resources
+Fold external links into the surrounding text where possible. When a skill needs source material, reference the implementation inline, for example [project name](https://example.com) in the step or sentence that uses it.
+
+## Metrics & Success Criteria
+- Success indicator 1
+- Success indicator 2

package/templates/workflow-template.md

@@ -0,0 +1,67 @@
+---
+title: "Workflow Name"
+description: "Use this template to define an agent workflow with steps, inputs, outputs, and reference notes."
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+category: "rag-agents"
+tags: ["workflow", "multi-step", "orchestration"]
+---
+
+## Overview
+[Description of this multi-step workflow and its purpose in RAG systems]
+
+## Prerequisites
+- [Required Skill 1](../category/skill-name.md)
+- [Required Skill 2](../category/skill-name.md)
+- Required dependencies (Python packages, services, etc.)
+
+## Workflow Diagram
+
+## Workflow Steps
+
+### Step 1: [Step Name]
+**Purpose**: [What this step accomplishes]
+
+**Input**: [What data enters this step]
+**Output**: [What this step produces]
+**Notes**: [Short guidance or decision criteria]
+
+### Step 2: [Step Name]
+**Purpose**: [What this step accomplishes]
+
+**Input**: [What data enters this step]
+**Output**: [What this step produces]
+**Notes**: [Short guidance or decision criteria]
+
+### Step 3: [Step Name]
+**Purpose**: [What this step accomplishes]
+
+**Input**: [What data enters this step]
+**Output**: [What this step produces]
+**Notes**: [Short guidance or decision criteria]
+
+## Inline Implementation Notes
+
+Fold implementation links into the step that uses them. If a workflow needs supporting docs or repos, link them in the step purpose or notes rather than collecting them in a separate reference block.
+
+## Configuration Options
+| Option | Description | Default | Notes |
+|--------|-------------|---------|-------|
+| option1 | Description | value1 | Note |
+| option2 | Description | value2 | Note |
+
+## Troubleshooting
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Issue description | Root cause | Fix |
+
+## Performance Considerations
+- [Performance tip 1]
+- [Performance tip 2]
+
+## Related Workflows
+- [Related Workflow 1](workflow-name.md)
+- [Related Workflow 2](workflow-name.md)