What is skill-vector-rag-tool?

This Claude skill provides a powerful Local RAG (Retrieval-Augmented Generation) solution by integrating Ollama embeddings with FAISS vector search. It enables AI agents to index, manage, and semantically query local codebases and documentation, significantly enhancing the agent's ability to retrieve relevant context for complex tasks while maintaining data privacy and reducing LLM hallucinations.

When should I use skill-vector-rag-tool?

skill-vector-rag-tool is useful in the following scenarios: • Semantic Code Search: Indexing large-scale repositories to find specific functions, classes, or logic patterns using natural language queries rather than simple keyword matching. • Private Knowledge Base: Creating a searchable local index of sensitive internal documents, project notes, or technical manuals for instant, context-aware information retrieval. • Enhanced RAG Grounding: Providing precise, relevant document chunks to LLMs to improve the accuracy of generated responses and ensure technical answers are grounded in the actual codebase. • Vector Store Management: Efficiently organizing and managing multiple vector stores across local environments or S3 cloud storage for different development projects.

name	skill-vector-rag-tool
description	Local RAG with Ollama and FAISS

When to use

Index codebases or documents for semantic search
Query vector stores for relevant code/document chunks
Manage vector stores (create, delete, list)
Set up local RAG with Ollama embeddings

vector-rag-tool Skill

Purpose

CLI for local RAG (Retrieval-Augmented Generation) with Ollama embeddings and FAISS vector search. Index codebases and documents into vector stores for semantic search.

When to Use

Use this skill when:

Indexing source code or documentation for semantic search
Querying indexed content by meaning (not just keywords)
Managing vector stores (create, list, delete, info)
Configuring S3 Vectors backend for cloud storage

Do NOT use for:

Simple text search (use grep instead)
Tasks unrelated to vector search or RAG

Prerequisites

# Ollama with embedding model
brew install ollama
ollama pull embeddinggemma

Quick Start

# Index Python files
vector-rag-tool index "**/*.py" --store my-project --no-dry-run

# Query for relevant code
vector-rag-tool query "how does authentication work" --store my-project

# List stores
vector-rag-tool store list

Commands

index - Index files into vector store

# Preview (dry-run default)
vector-rag-tool index "*.py" --store my-store

# Actually index files
vector-rag-tool index "*.md" "*.py" --store my-store --no-dry-run

# Index to S3 Vectors
vector-rag-tool index "src/**/*.py" --store my-store \
    --bucket my-vectors-bucket --profile dev --no-dry-run

# Force reindex all
vector-rag-tool index "docs/**/*.md" --store my-store --force --no-dry-run

# Custom chunk size
vector-rag-tool index "**/*.py" --store my-store --chunk-size 500 --no-dry-run

Options:

Option	Description
`--store/-s`	Store name (required)
`--bucket/-b`	S3 bucket for remote storage
`--region/-r`	AWS region (default: eu-central-1)
`--profile/-p`	AWS profile name
`--dry-run/-n`	Preview mode (default: enabled)
`--no-dry-run`	Actually perform indexing
`--force/-f`	Force reindexing all files
`--chunk-size/-c`	Target chunk size (default: 1500)
`--chunk-overlap/-o`	Overlap between chunks (default: 200)
`-v/-vv/-vvv`	Verbosity (INFO/DEBUG/TRACE)

query - Query vector store

# Basic query
vector-rag-tool query "machine learning" --store my-store

# More results
vector-rag-tool query "deep learning" --store my-store --top-k 10

# Query S3 backend
vector-rag-tool query "neural networks" --store my-store \
    --bucket my-vector-store --profile dev

# JSON output
vector-rag-tool query "attention mechanism" --store my-store --json

# From stdin
echo "query text" | vector-rag-tool query --store my-store --stdin

# Full chunks for RAG grounding
vector-rag-tool query "authentication" --store my-store --full --json

Options:

Option	Description
`--store/-s`	Store name (required)
`--top-k/-k`	Number of results (default: 5)
`--json`	JSON output
`--stdin`	Read query from stdin
`--snippet-length/-l`	Max snippet length (default: 300)
`--full/-F`	Return full chunk content

Output format:

{
  "query": "authentication",
  "store": "my-store",
  "total_results": 5,
  "results": [
    {
      "score": 0.85,
      "file_path": "src/auth.py",
      "line_start": 42,
      "line_end": 78,
      "content": "..."
    }
  ]
}

store - Manage vector stores

# List stores
vector-rag-tool store list
vector-rag-tool store list --format json

# Create store
vector-rag-tool store create my-store
vector-rag-tool store create my-store --dimension 1536

# Store info
vector-rag-tool store info my-store
vector-rag-tool store info my-store --format json

# Delete store
vector-rag-tool store delete my-store
vector-rag-tool store delete my-store --force

completion - Shell completion

# Bash
eval "$(vector-rag-tool completion bash)"

# Zsh
eval "$(vector-rag-tool completion zsh)"

# Fish
vector-rag-tool completion fish > ~/.config/fish/completions/vector-rag-tool.fish

Chunking Guidelines

Use Case	Chunk Size	Rationale
Code search	1000-1500	Full functions/classes
Documentation	500-1000	Paragraphs and sections
Fine-grained	300-500	More specific matches

Verbosity Levels

Flag	Level	Output
(none)	WARNING	Errors and warnings only
`-v`	INFO	High-level operations
`-vv`	DEBUG	Detailed info
`-vvv`	TRACE	Library internals

Troubleshooting

# Verify installation
vector-rag-tool --version

# Verify Ollama
ollama list  # Should show embeddinggemma

# List stores
vector-rag-tool store list

# Check store info
vector-rag-tool store info my-store

# Debug mode
vector-rag-tool query "test" --store my-store -vv

Exit Codes

0: Success
1: Client error (invalid arguments)
2: Server error (backend error)

skill-vector-rag-tool

When & Why to Use This Skill

Use Cases