rag-skills 1.0.0 → 1.0.1

package/.agents/skills/rag-skills/CONTRIBUTING.md

@@ -0,0 +1,211 @@
+# Contributing to rag-skills
+
+Thank you for your interest in contributing to rag-skills! This document provides guidelines for submitting new skills, reviewing existing skills, and maintaining the repository.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Submitting New Skills](#submitting-new-skills)
+- [Skill Review Criteria](#skill-review-criteria)
+- [Naming Conventions](#naming-conventions)
+- [Testing and Validation](#testing-and-validation)
+- [Credit and Attribution](#credit-and-attribution)
+- [Reporting Issues](#reporting-issues)
+
+## Code of Conduct
+
+- Be respectful and inclusive
+- Provide constructive feedback
+- Focus on what is best for the community
+- Show empathy towards other community members
+
+## Getting Started
+
+### Development Setup
+
+### Running Validation
+
+## Submitting New Skills
+
+### Step 1: Choose Your Topic
+
+Before creating a new skill, check that:
+
+1. The topic is not already covered by an existing skill
+2. The topic is relevant to RAG systems
+3. You have practical experience with the topic
+
+### Step 2: Use the Template
+
+Start with [templates/skill-template.md](templates/skill-template.md):
+Use the template as a lightweight reference format: brief illustrative text, no long runnable code, and 3-5 external implementation links folded into the relevant sections instead of a separate `References` block.
+
+### Step 3: Place Your Skill
+
+Organize skills by category:
+
+```text
+skills/<category>/<skill-name>/SKILL.md
+```
+
+For example:
+
+```text
+skills/chunking/semantic-chunking/SKILL.md
+```
+
+If your category doesn't exist, create it in the appropriate location.
+
+### Step 4: Validate Your Skill
+
+Run the validation script and fix any errors before submitting.
+
+### Step 5: Submit a Pull Request
+
+1. Commit your changes
+2. Push to your fork
+3. Open a pull request with a descriptive title
+
+Example PR title: `Add skill: Semantic Chunking for Markdown Documents`
+
+## Skill Review Criteria
+
+When reviewing skills, maintainers evaluate them against these criteria:
+
+### Clarity
+
+- [ ] Is the problem statement clear and specific?
+- [ ] Are key concepts well-defined?
+- [ ] Are implementation steps logically ordered?
+- [ ] Is the writing free of ambiguity?
+
+### Accuracy
+
+- [ ] Are the technical statements correct?
+- [ ] Do code examples run as expected?
+- [ ] Are references valid and current?
+- [ ] Are the metrics/success criteria realistic?
+
+### Completeness
+
+- [ ] All required sections are present
+- [ ] Code examples are brief and illustrative, not full implementations
+- [ ] Related skills are properly linked
+- [ ] Both use cases and anti-patterns are covered
+
+### Practicality
+
+- [ ] The skill addresses a real-world problem
+- [ ] The approach is production-viable
+- [ ] The complexity matches the difficulty level
+- [ ] Dependencies are reasonable and well-known
+
+### Code Quality
+
+- [ ] Code follows Python conventions (PEP 8)
+- [ ] Code includes comments for complex logic
+- [ ] Code handles errors appropriately
+- [ ] Code examples stay lightweight and defer to external implementations
+
+## Naming Conventions
+
+### Skill Files
+
+- Use kebab-case directory names: `semantic-chunking/SKILL.md`
+- Be descriptive: `hybrid-search-bm25-dense/SKILL.md`
+- Keep names under 50 characters
+
+### Categories
+
+Use existing category names:
+- `chunking`
+- `vector-databases`
+- `retrieval-strategies`
+- `data-type-handling`
+- `performance-optimization`
+- `evaluation-metrics`
+- `rag-agents`
+- `deployment`
+
+### Tags
+
+- Use 3-5 relevant tags per skill
+- Use lowercase: `["semantic", "nlp", "context"]`
+- Avoid overly specific tags
+- Focus on searchable terms
+
+## Testing and Validation
+
+### Local Validation
+
+Before submitting, ensure your skill passes validation:
+
+Strict mode treats warnings as errors.
+
+### Link Validation
+
+Verify all internal links work and that external implementation links are placed inline in the relevant step or sentence:
+
+## Credit and Attribution
+
+### Author Field
+
+Include your name in the `author` field:
+
+For organizational contributions:
+
+### Last Updated
+
+Update the `last_updated` field with the current date:
+
+### Co-Authors
+
+For substantial contributions from multiple people, list them in the pull request description:
+
+## Reporting Issues
+
+When reporting issues, include:
+
+- A clear title
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment information
+- Screenshots if applicable
+
+### Issue Templates
+
+#### Bug Report
+
+#### Feature Request
+
+## Community Guidelines
+
+### Discussions
+
+- Use GitHub Discussions for questions and ideas
+- Be specific in your questions
+- Share code snippets when helpful
+- Follow up on responses
+
+### Code Review
+
+- Be constructive in your reviews
+- Explain the reasoning for suggested changes
+- Acknowledge good work
+- Be patient with maintainers' time
+
+### Maintainer Response Time
+
+Maintainers aim to respond to:
+- Pull requests: Within 7 days
+- Issues: Within 7 days
+- Discussions: Within 3 days
+
+## Additional Resources
+
+- [Project README](README.md)
+- [Skill Template](templates/skill-template.md)
+- [GitHub Community Guidelines](https://docs.github.com/en/site-policy/github-terms/github-community-guidelines)
+
+Thank you for contributing to rag-skills!

package/.agents/skills/rag-skills/INDEX.md

@@ -0,0 +1,113 @@
+# RAG Skills Index
+
+Generated: 2026-04-11 03:11:54
+
+Total Skills: 28
+
+---
+
+## Browse by Category
+
+### Chunking
+
+- [Choosing a Chunking Framework](skills/chunking/choosing-a-chunking-framework/SKILL.md)
+  - *Chunking quality depends as much on the framework as on the strategy itself.*
+- [Contextual Chunk Headers](skills/chunking/contextual-chunk-headers/SKILL.md)
+  - *Contextual chunk headers (CCH) enhance retrieval by prepending higher-level context (document title, section headers, summaries) to each chunk before embedding.*
+- [Hierarchical Chunking](skills/chunking/hierarchical-chunking/SKILL.md)
+  - *Hierarchical chunking creates multi-level chunk structures that preserve document hierarchies (chapters, sections, subsections).*
+- [Semantic Chunking](skills/chunking/semantic-chunking/SKILL.md)
+  - *Semantic chunking divides documents into segments based on natural language boundaries and semantic meaning rather than fixed character counts.*
+- [Chunking](skills/chunking/SKILL.md)
+  - *Use this parent skill when the main RAG problem is how to split source material into retrievable units.*
+- [Sliding Window Chunking](skills/chunking/sliding-window-chunking/SKILL.md)
+  - *Sliding window chunking creates overlapping chunks where each chunk shares content with adjacent chunks.*
+
+### Data Type Handling
+
+- [RAG for Code Documentation](skills/data-type-handling/rag-for-code-documentation/SKILL.md)
+  - *RAG for code documentation requires specialized handling due to code's structured nature, syntax-specific patterns, and the importance of preserving function signatures, imports, and contextual relationships.*
+- [RAG for Multimodal Content](skills/data-type-handling/rag-for-multimodal-content/SKILL.md)
+  - *Multimodal RAG extends retrieval to include images, videos, audio, and mixed media content alongside text.*
+- [Data Type Handling](skills/data-type-handling/SKILL.md)
+  - *Use this parent skill when source material is not plain prose or when different data types need different parsing, metadata, chunking, and retrieval strategies.*
+
+### Performance Optimization
+
+- [Optimize Retrieval Latency](skills/performance-optimization/optimize-retrieval-latency/SKILL.md)
+  - *Optimizing RAG retrieval latency is critical for production applications where user experience depends on fast response times.*
+- [Performance Optimization](skills/performance-optimization/SKILL.md)
+  - *Use this parent skill when the RAG system works functionally but is too slow, expensive, or unstable under expected traffic.*
+
+### Retrieval Strategies
+
+- [Adaptive Retrieval](skills/retrieval-strategies/adaptive-retrieval/SKILL.md)
+  - *Adaptive retrieval classifies queries into types (factual, analytical, opinion, contextual) and applies different retrieval strategies optimized for each type.*
+- [Context Enrichment Window](skills/retrieval-strategies/context-enrichment-window/SKILL.md)
+  - *Context enrichment window expands retrieved chunks by including neighboring text from the original document.*
+- [CRAG - Corrective RAG](skills/retrieval-strategies/crag-corrective-rag/SKILL.md)
+  - *Corrective RAG (CRAG) extends standard retrieval by dynamically evaluating document relevance and correcting the retrieval process when needed.*
+- [Explainable Retrieval with Citations](skills/retrieval-strategies/explainable-retrieval/SKILL.md)
+  - *Explainable retrieval adds citations, source attribution, and traceability to RAG systems.*
+- [Graph RAG - Knowledge Graph Retrieval](skills/retrieval-strategies/graph-rag/SKILL.md)
+  - *Graph RAG enhances traditional retrieval by constructing knowledge graphs from documents, identifying communities of related entities, and using these structures to improve retrieval.*
+- [Hybrid Search: BM25 + Dense](skills/retrieval-strategies/hybrid-search-bm25-dense/SKILL.md)
+  - *Hybrid search combines BM25 (keyword search) with dense vector embeddings (semantic search) to leverage both exact term matching and semantic understanding.*
+- [HyDE - Hypothetical Document Embeddings](skills/retrieval-strategies/hyde-hypothetical-document-embeddings/SKILL.md)
+  - *HyDE (Hypothetical Document Embeddings) is a query expansion technique that generates a hypothetical document answering the user's query, then uses this synthetic document as the query for vector search.*
+- [HyPE - Hypothetical Prompt Embeddings](skills/retrieval-strategies/hype-hypothetical-prompt-embeddings/SKILL.md)
+  - *HyPE (Hypothetical Prompt Embeddings) transforms retrieval from query-document matching to question-question matching by generating multiple hypothetical questions for each document chunk during the indexing phase.*
+- [Multi-Pass Retrieval with Reranking](skills/retrieval-strategies/multi-pass-retrieval-with-reranking/SKILL.md)
+  - *Multi-pass retrieval with reranking is a two-stage approach that first retrieves a broad set of candidates using fast bi-encoder search, then refines them using a more accurate but slower cross-encoder reranker.*
+- [Query Transformation Strategies](skills/retrieval-strategies/query-transformation-strategies/SKILL.md)
+  - *Query transformation strategies modify or expand user queries before retrieval to bridge the gap between natural language queries and document representations.*
+- [RAPTOR - Hierarchical Abstractive Retrieval](skills/retrieval-strategies/raptor-hierarchical-retrieval/SKILL.md)
+  - *RAPTOR (Recursive Abstractive Processing and Tree-Organized Retrieval) creates a hierarchical tree of document summaries, allowing retrieval at multiple levels of abstraction.*
+- [Self-RAG - Self-Reflective Retrieval](skills/retrieval-strategies/self-rag/SKILL.md)
+  - *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.*
+- [Retrieval Strategies](skills/retrieval-strategies/SKILL.md)
+  - *Use this parent skill when the main RAG problem is search quality, ranking, recall, context selection, or evidence traceability.*
+
+### Vector Databases
+
+- [Choosing Vector Database by Data Type](skills/vector-databases/choosing-vector-db-by-datatype/SKILL.md)
+  - *Selecting the right vector database depends heavily on your data type (text, images, code, multimodal) and use case requirements.*
+- [Qdrant for Production RAG](skills/vector-databases/qdrant-for-production-rag/SKILL.md)
+  - *Productionizing a RAG system with Qdrant requires considerations beyond basic setup: horizontal scaling, high availability, performance optimization, monitoring, and cost management.*
+- [Qdrant Setup for RAG](skills/vector-databases/qdrant-setup-rag/SKILL.md)
+  - *Qdrant is an open-source vector similarity search engine designed for high-performance RAG applications.*
+- [Vector Databases](skills/vector-databases/SKILL.md)
+  - *Use this parent skill when the main RAG problem is choosing, configuring, or operating the vector storage layer.*
+
+## All Skills
+
+| Title | Category | Tags |
+|-------|----------|------|
+| [Adaptive Retrieval](skills/retrieval-strategies/adaptive-retrieval/SKILL.md) | retrieval-strategies | adaptive, query-classification, dynamic-strategy (+1) |
+| [CRAG - Corrective RAG](skills/retrieval-strategies/crag-corrective-rag/SKILL.md) | retrieval-strategies | crag, corrective, web-search (+2) |
+| [Choosing Vector Database by Data Type](skills/vector-databases/choosing-vector-db-by-datatype/SKILL.md) | vector-databases | selection, text, multimodal (+2) |
+| [Choosing a Chunking Framework](skills/chunking/choosing-a-chunking-framework/SKILL.md) | chunking | framework-selection, chonkie, langchain (+3) |
+| [Chunking](skills/chunking/SKILL.md) | chunking | chunking, routing, rag (+1) |
+| [Context Enrichment Window](skills/retrieval-strategies/context-enrichment-window/SKILL.md) | retrieval-strategies | context-enrichment, surrounding-context, window (+1) |
+| [Contextual Chunk Headers](skills/chunking/contextual-chunk-headers/SKILL.md) | chunking | contextual-headers, metadata, chunk-enhancement (+1) |
+| [Data Type Handling](skills/data-type-handling/SKILL.md) | data-type-handling | data-types, code, multimodal (+1) |
+| [Explainable Retrieval with Citations](skills/retrieval-strategies/explainable-retrieval/SKILL.md) | retrieval-strategies | explainability, citations, traceability (+1) |
+| [Graph RAG - Knowledge Graph Retrieval](skills/retrieval-strategies/graph-rag/SKILL.md) | retrieval-strategies | graph-rag, knowledge-graph, entity-extraction (+1) |
+| [Hierarchical Chunking](skills/chunking/hierarchical-chunking/SKILL.md) | chunking | nested, multi-level, document-structure (+1) |
+| [HyDE - Hypothetical Document Embeddings](skills/retrieval-strategies/hyde-hypothetical-document-embeddings/SKILL.md) | retrieval-strategies | hyde, query-expansion, llm-generation (+1) |
+| [HyPE - Hypothetical Prompt Embeddings](skills/retrieval-strategies/hype-hypothetical-prompt-embeddings/SKILL.md) | retrieval-strategies | hype, precomputed-queries, indexing-time (+1) |
+| [Hybrid Search: BM25 + Dense](skills/retrieval-strategies/hybrid-search-bm25-dense/SKILL.md) | retrieval-strategies | hybrid, bm25, dense (+2) |
+| [Multi-Pass Retrieval with Reranking](skills/retrieval-strategies/multi-pass-retrieval-with-reranking/SKILL.md) | retrieval-strategies | reranking, cross-encoder, two-stage (+1) |
+| [Optimize Retrieval Latency](skills/performance-optimization/optimize-retrieval-latency/SKILL.md) | performance-optimization | latency, performance, caching (+2) |
+| [Performance Optimization](skills/performance-optimization/SKILL.md) | performance-optimization | latency, performance, caching (+1) |
+| [Qdrant Setup for RAG](skills/vector-databases/qdrant-setup-rag/SKILL.md) | vector-databases | qdrant, setup, ingestion (+1) |
+| [Qdrant for Production RAG](skills/vector-databases/qdrant-for-production-rag/SKILL.md) | vector-databases | production, scaling, optimization (+1) |
+| [Query Transformation Strategies](skills/retrieval-strategies/query-transformation-strategies/SKILL.md) | retrieval-strategies | query-expansion, step-back, sub-query (+1) |
+| [RAG for Code Documentation](skills/data-type-handling/rag-for-code-documentation/SKILL.md) | data-type-handling | code, programming, syntax (+2) |
+| [RAG for Multimodal Content](skills/data-type-handling/rag-for-multimodal-content/SKILL.md) | data-type-handling | multimodal, images, text (+2) |
+| [RAPTOR - Hierarchical Abstractive Retrieval](skills/retrieval-strategies/raptor-hierarchical-retrieval/SKILL.md) | retrieval-strategies | raptor, hierarchical, clustering (+2) |
+| [Retrieval Strategies](skills/retrieval-strategies/SKILL.md) | retrieval-strategies | retrieval, ranking, hybrid-search (+1) |
+| [Self-RAG - Self-Reflective Retrieval](skills/retrieval-strategies/self-rag/SKILL.md) | retrieval-strategies | self-rag, reflection, retrieval-decision (+1) |
+| [Semantic Chunking](skills/chunking/semantic-chunking/SKILL.md) | chunking | semantic, nlp, sentence-boundary (+1) |
+| [Sliding Window Chunking](skills/chunking/sliding-window-chunking/SKILL.md) | chunking | overlap, context-preservation, window (+1) |
+| [Vector Databases](skills/vector-databases/SKILL.md) | vector-databases | vector-database, qdrant, metadata (+1) |

package/.agents/skills/rag-skills/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rag-skills contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/.agents/skills/rag-skills/README.md

@@ -0,0 +1,169 @@
+# Rag-skills
+
+<p>
+  <code>agent routing</code> <code>RAG skills</code> <code>markdown</code>
+</p>
+
+A modular collection of best-practice guides and skill definitions for building Retrieval-Augmented Generation (RAG) systems. Designed for AI coding agents, agent frameworks, and teams that want a structured way to route RAG work to the right strategy.
+
+## Overview
+
+RAG-skills consolidates actionable skills that help AI agents and builders improve RAG performance, choose appropriate vector databases, implement effective chunking strategies, optimize retrieval quality, and orchestrate multi-step RAG workflows.
+
+## Installation
+
+### Claude Code
+
+Add this repository as a Claude Code plugin marketplace:
+
+```text
+/plugin marketplace add Goodnight77/rag-skills
+```
+
+Then install the RAG skills plugin:
+
+```text
+/plugin install rag-skills@rag-skills
+```
+
+Restart Claude Code after installation.
+
+### Skills CLI
+
+Install with the Skills CLI:
+
+```bash
+npx skills add Goodnight77/rag-skills
+```
+
+This installs the root [`SKILL.md`](SKILL.md) plus the native skill tree under
+[`skills/`](skills/). Claude Code can discover category skills such as
+`/chunking` and specific skills such as `/semantic-chunking`.
+
+### Manual Usage
+
+You can also clone the repository and reference the Markdown skills directly:
+
+```bash
+git clone https://github.com/Goodnight77/rag-skills.git
+```
+
+Then point your agent or coding assistant to the `skills/` directory.
+
+> Note: This repository follows the Claude Code/Qdrant-style structure: category routers live at paths like `skills/chunking/SKILL.md`, and specific skills live at paths like `skills/chunking/semantic-chunking/SKILL.md`.
+
+## Skills by Decision Area
+
+This repo is organized as a routing layer for RAG work. Agents can use the category and metadata in each skill file to decide which path to follow for a given problem, instead of treating the repo like a generic reference manual.
+
+### Chunking
+Use these when the main problem is how to split source material into retrievable units.
+- [Semantic Chunking](skills/chunking/semantic-chunking/SKILL.md) - Chunk documents based on semantic boundaries
+- [Hierarchical Chunking](skills/chunking/hierarchical-chunking/SKILL.md) - Multi-level chunking for nested structures
+- [Sliding Window Chunking](skills/chunking/sliding-window-chunking/SKILL.md) - Overlap-based chunking for context preservation
+- [Contextual Chunk Headers](skills/chunking/contextual-chunk-headers/SKILL.md) - Adding higher-level context to chunks
+
+### Vector Databases
+Use these when the main problem is choosing or operating the storage layer for embeddings and metadata.
+- [Qdrant Setup for RAG](skills/vector-databases/qdrant-setup-rag/SKILL.md) - Setting up Qdrant for RAG
+- [Qdrant for Production RAG](skills/vector-databases/qdrant-for-production-rag/SKILL.md) - Scaling RAG with Qdrant
+- [Choosing Vector DB by Datatype](skills/vector-databases/choosing-vector-db-by-datatype/SKILL.md) - Database selection guide
+
+### Retrieval Strategies
+Use these when the main problem is search quality, ranking, recall, or combining search methods.
+- [Hybrid Search BM25 Dense](skills/retrieval-strategies/hybrid-search-bm25-dense/SKILL.md) - Combining keyword and semantic search
+- [Multi-Pass Retrieval with Reranking](skills/retrieval-strategies/multi-pass-retrieval-with-reranking/SKILL.md) - Two-pass retrieval with cross-encoder reranking
+- [Query Transformation Strategies](skills/retrieval-strategies/query-transformation-strategies/SKILL.md) - Query rewriting, step-back prompting, sub-query decomposition
+- [HyDE - Hypothetical Document Embeddings](skills/retrieval-strategies/hyde-hypothetical-document-embeddings/SKILL.md) - Query expansion with LLM-generated documents
+- [HyPE - Hypothetical Prompt Embeddings](skills/retrieval-strategies/hype-hypothetical-prompt-embeddings/SKILL.md) - Precomputed question embeddings at indexing time
+- [Self-RAG](skills/retrieval-strategies/self-rag/SKILL.md) - Self-reflective retrieval with relevance evaluation
+- [RAPTOR - Hierarchical Retrieval](skills/retrieval-strategies/raptor-hierarchical-retrieval/SKILL.md) - Multi-level tree of document summaries
+- [Context Enrichment Window](skills/retrieval-strategies/context-enrichment-window/SKILL.md) - Adding surrounding chunks to retrieved results
+- [Adaptive Retrieval](skills/retrieval-strategies/adaptive-retrieval/SKILL.md) - Dynamic strategy selection based on query type
+- [Explainable Retrieval with Citations](skills/retrieval-strategies/explainable-retrieval/SKILL.md) - Traceability and source attribution
+- [CRAG - Corrective RAG](skills/retrieval-strategies/crag-corrective-rag/SKILL.md) - Dynamic correction with web search
+- [Graph RAG](skills/retrieval-strategies/graph-rag/SKILL.md) - Knowledge graph-based retrieval
+
+### Data Type Handling
+Use these when the source content is code, APIs, diagrams, tables, or mixed media.
+- [RAG for Code Documentation](skills/data-type-handling/rag-for-code-documentation/SKILL.md) - Special handling for code and technical docs
+- [RAG for Multimodal Content](skills/data-type-handling/rag-for-multimodal-content/SKILL.md) - Images, tables, and mixed media
+
+### Performance Optimization
+Use these when the problem is latency, throughput, cache behavior, or production efficiency.
+- [Optimize Retrieval Latency](skills/performance-optimization/optimize-retrieval-latency/SKILL.md) - Caching, indexing, and query optimization
+
+### RAG Agents
+Use these when the problem is orchestration, delegation, or multi-step workflows.
+- *See [Examples](#examples) for multi-agent workflows*
+
+### Deployment
+Use these when the problem is production rollout, reliability, or operationalization.
+- *See [Production RAG Setup](#examples)*
+
+### Evaluation Metrics
+Use these when the problem is measurement, regression detection, or retrieval benchmarking.
+- *Coming soon*
+
+## Quick Start
+
+### For AI Agents
+
+Read the frontmatter metadata, then route to the skill that best matches the user’s problem. Treat the repo as a decision tree for RAG tasks: chunking, retrieval, vector store choice, embeddings, performance, and workflow orchestration.
+
+### For Framework Integration
+
+Build a lightweight index from the markdown frontmatter and use it to filter by category, tags, and task type. The goal is not to mirror all content in code, but to point an agent to the right skill or external implementation quickly.
+
+Keep examples in the repo lightweight and point readers to external implementations instead of embedding long code samples.
+
+## Examples
+
+Complete walkthroughs and reference implementations:
+
+- [Foundational RAG Pipeline Example](examples/foundational-rag-pipeline.md) - A guided RAG build path for agents and builders
+- [Multi-Agent RAG](examples/multi-agent-rag.md) - An orchestration pattern for specialized agents
+- [Production RAG Setup](examples/production-rag-setup.md) - A deployment-oriented route for production systems
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Quick Contribution Steps
+
+1. Fork the repository
+2. Create a new skill file using [templates/skill-template.md](templates/skill-template.md)
+3. Ensure your skill follows the required structure
+4. Run validation: `python scripts/validate-skills.py`
+5. Submit a pull request
+
+## Skill File Format
+
+Each skill follows a consistent structure with a short illustrative snippet, not a full implementation. See the template in [templates/skill-template.md](templates/skill-template.md).
+
+## Scripts
+
+- `validate-skills.py` — Validate all skill files for format compliance
+- `generate-index.py` — Generate browsable INDEX.md and SKILLS.json
+
+## Project Status
+
+This is an active open-source project. Skills are continuously added and updated as RAG best practices evolve.
+
+Current statistics:
+- **Native Skills**: 28
+- **Guide Skills**: 23
+- **Category Router Skills**: 5
+- **Categories**: 5
+- **Examples**: 3
+
+*Run `python scripts/generate-index.py` for current statistics.*
+
+## Acknowledgments
+
+Built for the RAG community. Special thanks to contributors and the open-source RAG ecosystem.
+
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

package/.agents/skills/rag-skills/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: rag-skills
+description: Use this skill when building, debugging, or improving Retrieval-Augmented Generation systems, including chunking, vector database selection, hybrid search, reranking, multimodal RAG, code documentation RAG, retrieval latency, and production RAG architecture.
+---
+
+# RAG Skills
+
+This skill routes RAG implementation work to the right guide in this repository.
+Use it when a user asks for help designing, implementing, improving, evaluating,
+or operating a Retrieval-Augmented Generation pipeline.
+
+## How to Use This Skill
+
+1. Identify the main RAG problem: chunking, vector storage, retrieval quality,
+   data type handling, latency, evaluation, agents, or deployment.
+2. Open the most relevant guide under `skills/`.
+3. Follow the guide's decision criteria, implementation notes, references, and
+   success metrics.
+4. Prefer lightweight examples in this repo, then use the linked external
+   implementations for production code patterns.
+
+## Skill Routes
+
+### Chunking
+
+- `skills/chunking/semantic-chunking/SKILL.md`: Chunk by semantic boundaries instead
+  of fixed token windows.
+- `skills/chunking/hierarchical-chunking/SKILL.md`: Preserve document hierarchy across
+  sections, headings, and nested structures.
+- `skills/chunking/sliding-window-chunking/SKILL.md`: Add overlap to preserve context
+  near chunk boundaries.
+- `skills/chunking/contextual-chunk-headers/SKILL.md`: Add inherited section context
+  to chunks.
+- `skills/chunking/choosing-a-chunking-framework/SKILL.md`: Select chunking libraries
+  and frameworks.
+
+### Vector Databases
+
+- `skills/vector-databases/qdrant-setup-rag/SKILL.md`: Set up Qdrant for RAG with
+  metadata and filtering.
+- `skills/vector-databases/qdrant-for-production-rag/SKILL.md`: Operate Qdrant in
+  production RAG systems.
+- `skills/vector-databases/choosing-vector-db-by-datatype/SKILL.md`: Choose a vector
+  database for text, code, multimodal, and structured data.
+
+### Retrieval Strategies
+
+- `skills/retrieval-strategies/hybrid-search-bm25-dense/SKILL.md`: Combine keyword
+  and dense vector retrieval.
+- `skills/retrieval-strategies/multi-pass-retrieval-with-reranking/SKILL.md`: Retrieve
+  broadly, then rerank with a stronger model.
+- `skills/retrieval-strategies/query-transformation-strategies/SKILL.md`: Rewrite,
+  decompose, or expand queries before retrieval.
+- `skills/retrieval-strategies/hyde-hypothetical-document-embeddings/SKILL.md`: Use
+  hypothetical answer documents to improve query embeddings.
+- `skills/retrieval-strategies/hype-hypothetical-prompt-embeddings/SKILL.md`: Index
+  likely prompts or questions alongside source content.
+- `skills/retrieval-strategies/self-rag/SKILL.md`: Add self-reflection and retrieval
+  validation to generation workflows.
+- `skills/retrieval-strategies/raptor-hierarchical-retrieval/SKILL.md`: Retrieve over
+  hierarchical summaries and source chunks.
+- `skills/retrieval-strategies/context-enrichment-window/SKILL.md`: Expand retrieved
+  chunks with neighboring context.
+- `skills/retrieval-strategies/adaptive-retrieval/SKILL.md`: Choose retrieval strategy
+  dynamically based on query type.
+- `skills/retrieval-strategies/explainable-retrieval/SKILL.md`: Improve traceability
+  with source attribution and citations.
+- `skills/retrieval-strategies/crag-corrective-rag/SKILL.md`: Correct weak retrieval
+  with validation and fallback search.
+- `skills/retrieval-strategies/graph-rag/SKILL.md`: Use graph structure and entity
+  relationships for retrieval.
+
+### Data Type Handling
+
+- `skills/data-type-handling/rag-for-code-documentation/SKILL.md`: Handle code,
+  APIs, examples, and technical documentation.
+- `skills/data-type-handling/rag-for-multimodal-content/SKILL.md`: Handle images,
+  tables, diagrams, and mixed media.
+
+### Performance Optimization
+
+- `skills/performance-optimization/optimize-retrieval-latency/SKILL.md`: Reduce
+  retrieval latency with indexing, caching, and query optimization.
+
+## Success Criteria
+
+- The selected RAG pattern matches the user's actual bottleneck.
+- Retrieval quality improves without adding unnecessary architecture.
+- The implementation keeps metadata, evaluation, and production constraints in
+  view from the start.
+- External references are used for real implementation details instead of
+  copying large code blocks into this skill.