name	pdf-rag-knowledge
description	Search and retrieve information from indexed PDF documentation. This includes IC datasheets, FPGA manuals, and technical specifications. Use this when the user asks about hardware specifications, pin configurations, register details, timing diagrams, or any technical information that might be in datasheets or technical documentation.
argument-hint	<query> [top-k] (e.g., "STM32F407 GPIO config", "Artix-7 power specs" 3, "ESP32 I2C timing" 15)
user-invocable	true
disable-model-invocation	false
context	inline

PDF RAG Knowledge Base Skill

A GitHub Copilot Agent Skill for using Retrieval-Augmented Generation (RAG) to increase accuracy of AI responses based on information from manuals, datasheets, etc. Uses a locally stored vector store based on hashlib to store the embeddings, and provides a CLI tool for generating embeddings from PDF files using Ollama.

🎯 Fully Portable & Self-Contained

This skill is 100% self-contained in the .github/skills/pdf-rag-knowledge/ directory:

• ✅ Portable Python search script (rag_search.py)
• ✅ Repo-specific vector database (vector_store.json)
• ✅ Bash helper script (search_rag.sh)
• ✅ No external dependencies on project structure

Copy the entire folder to any repo to use it!

When to Use This Skill

Use this skill when users ask about:

• IC specifications (STM32, ESP32, microcontroller datasheets)
• FPGA documentation and configurations
• Hardware pin configurations and GPIO settings
• Register addresses and bit fields
• Timing specifications and electrical characteristics
• Communication protocols (I2C, SPI, UART, etc.) as documented in datasheets
• Power consumption and thermal specifications
• Any technical details that would be found in PDF datasheets

How It Works

1. Indexing: PDFs chunked into 2000-char segments with 400-char overlap
2. Embeddings: Generated via Ollama (local, free, private)
3. Search: Semantic similarity using cosine distance
4. Integration: Auto-loads when Copilot detects relevant questions

Installation

Add this skill as a git submodule to your repo

cd your-repo

git submodule add https://github.com/redfave/vscode-pdf-rag-skill.git .github/skills/pdf-rag-knowledge
git submodule update --init --recursive

5. Enable in VS Code Insiders

Add to your repo's .vscode/settings.json (or set it globally):

{
  "chat.useAgentSkills": true
}

Setup

All commands below should be run from the skill directory:

cd .github/skills/pdf-rag-knowledge

Prerequisites

• Linux / MacOS - Windows users need to use the WSL.
• Docker – required for the recommended setup (the Dockerfile builds an image with the mxbai-embed-large model baked in). If you prefer a manual installation, you only need a local Ollama server.
• uv – fast Python package installer and runner (replaces pip/venv)
  • Linux/WSL: curl -LsSf https://astral.sh/uv/install.sh | sh
• Python – for the CLI scripts (managed by uv, you need just uv for the installation)

Quick Setup with Docker (Recommended)

# Build the ollama image (only needed the first time) and start the container
docker compose up -d --build

The container is build and starts instantly and is ready to use because the mxbai-embed-large model is baked into the image, no further configuration needed.

The skill relies on a few Python dependencies managed by uv. After installing uv, install the project defined in pyproject.toml:

uv sync

The basic project does not need any optional extras or dependency groups for plain usage.

Manual Setup (Alternative)

If you prefer to run Ollama directly on the host / don't want to use docker.

# Install Ollama (see https://ollama.com)
ollama pull mxbai-embed-large

Search the Knowledge Base

# Using the helper script
./search_rag.sh "your search query"

# Or directly with uv
uv run python rag_search.py --search "your search query"

# Limit results
./search_rag.sh "FPGA power" 3

Adding PDFs to the Knowledge Base

uv run python rag_search.py --index /path/to/your/datasheets/my_file.pdf

Adding multiple files:

find {pdf_dir} -type f -name "*.pdf" -print0 | xargs -0 -n1 uv run python rag_search.py --index

Knowledge Base Management

# Check the vector store status
uv run python rag_search.py --stats

# Clear the database if needed
uv run python rag_search.py --clear

With GitHub Copilot

Ask natural questions in Copilot Chat. The skill activates automatically when you ask about:

• Hardware specifications
• Pin configurations
• Register details
• Timing diagrams
• Power requirements
• Communication protocols
• Any technical info from datasheets

File Structure

.github/skills/pdf-rag-knowledge/
├── SKILL.md              # This file (skill definition)
├── Dockerfile            # Container definition baking the model in
├── docker-compose.yml    # Compose configuration for the service
├── rag_search.py         # Portable search script
├── search_rag.sh         # Bash helper script
├── pyproject.toml        # Python project config (dependencies, ruff)
└── vector_store.json     # Repo-specific indexed PDFs

Example usage

Example 1: GPIO Configuration

User: "How do I configure GPIO pins on STM32F407?"

Skill searches: ./search_rag.sh "GPIO configuration STM32F407"

Returns: Relevant sections from STM32F407 datasheet with page numbers

Example 2: FPGA Specifications (with top-k)

User: "What are the specifications for Artix-7 FPGAs?"

Skill searches: ./search_rag.sh "Artix-7 specifications" 10

Returns: Device specifications, logic resources, I/O counts (top 10 results)

Example 3: Power Requirements (with top-k)

User: "What are the power requirements?"

Skill searches: ./search_rag.sh "power supply voltage requirements" 3

Returns: Voltage ranges, current consumption, power modes (top 3 results)

Configuration

Optional environment variables (the defaults are defined in rag_search.py):

export OLLAMA_BASE_URL=http://localhost:11434
export OLLAMA_MODEL=mxbai-embed-large
export CHUNK_SIZE=2000
export CHUNK_OVERLAP=400

Index your repo-specific PDFs

uv run python rag_search.py --index /path/to/your/pdfs/*.pdf

Each repo maintains its own vector_store.json with repo-specific documentation!

Pre‑commit Setup (required for contributors)

To ensure code quality and consistent formatting, this repository uses pre‑commit and further dependencies.

Install development dependencies:

uv sync --all-groups

Install the pre‑commit hooks locally:

uv run pre-commit install

You can also run the hooks manually on all files:

uv run pre-commit run --all-files

Technical Details

Search Process

1. Query converted to 1024-dimension embedding via Ollama
2. Cosine similarity calculated against all stored embeddings
3. Top K most relevant chunks returned
4. Results include similarity scores and source citations

Vector Store Format

JSON file with documents and embeddings:

{
  "doc_id": {
    "id": "unique_hash",
    "content": "text chunk",
    "embedding": [0.123, ...],
    "source": "filename.pdf",
    "page": 42,
    "metadata": {...}
  }
}

PDF Chunking

• Chunk Size: 2000 characters
• Overlap: 400 characters (preserves context)
• Min Size: 100 characters (filters noise)

Troubleshooting

Verify Ollama

curl http://localhost:11434/api/tags

Check Status

uv run python rag_search.py --stats

Test Search

./search_rag.sh "test query"

Common Issues

No results found:

• Check if PDFs are indexed: uv run python rag_search.py --stats
• Verify Ollama is running: curl http://localhost:11434

Import errors:

• Sync dependencies: uv sync

Permission denied:

• Make scripts executable: chmod +x *.sh *.py

Integration with VS Code Copilot

This skill integrates with GitHub Copilot through Agent Skills:

1. Copilot detects hardware/datasheet questions
2. Skill loads automatically (progressive disclosure)
3. Search executes against repo-specific knowledge base
4. Results seamlessly integrated into Copilot responses
5. You don't manually invoke - just ask natural questions

Important Notes

1. Repo-Specific: Each repository has its own vector_store.json with repo-specific documentation.
2. Ollama Must Be Running: Ensure Ollama is running locally (either via Docker or host installation). Use docker compose up to start the container, when it's stopped.
3. Source Citations: Always reference the source document and page number when providing information from the knowledge base.
4. Context Limitations: The skill returns the most relevant chunks. For comprehensive answers, it may help to search multiple times with related queries.

Related Resources

• Ollama - Local embedding service
• Agent Skills Standard
• VS Code Agent Skills Docs
• uv - Fast Python package installer and runner

<style> body { counter-reset: h1counter h2counter h3counter h4counter h5counter h6counter; } h1 { counter-reset: h2counter; } h2 { counter-reset: h3counter; } h3 { counter-reset: h4counter; } h4 { counter-reset: h5counter; } h5 { counter-reset: h6counter; } h6 {} h2:before { counter-increment: h2counter; content: counter(h2counter) ".\0000a0\0000a0"; } h3:before { counter-increment: h3counter; content: counter(h2counter) "." counter(h3counter) ".\0000a0\0000a0"; } h4:before { counter-increment: h4counter; content: counter(h2counter) "." counter(h3counter) "." counter(h4counter) ".\0000a0\0000a0"; } h5:before { counter-increment: h5counter; content: counter(h2counter) "." counter(h3counter) "." counter(h4counter) "." counter(h5counter) ".\0000a0\0000a0"; } h6:before { counter-increment: h6counter; content: counter(h2counter) "." counter(h3counter) "." counter(h4counter) "." counter(h5counter) "." counter(h6counter) ".\0000a0\0000a0"; } </style>