feat(redis-vector-search): add spec-compliant skill for embeddings and RAG

Introduces skills/redis-vector-search/ covering the four vector-* rules
from skills/redis-development/rules/ in agentskills.io spec layout:

  vector-algorithm-choice → references/algorithm-choice.md  (HNSW vs FLAT)
  vector-index-creation   → references/index-creation.md    (DIM, metric, etc.)
  vector-hybrid-search    → references/hybrid-search.md     (filtered vector)
  vector-rag-pattern      → references/rag-pattern.md       (full RAG pipeline)

SKILL.md summarizes index configuration, algorithm choice, hybrid
filtering, and the RAG pattern; the four reference files carry the
full code samples. The skill positions itself as a layer on top of
redis-query-engine, since vector fields live inside RQE indexes.

Additive only: the source vector-*.md rules under skills/redis-development/
remain in place so the legacy compiled AGENTS.md continues to serve
existing plugin consumers unchanged. They are removed in the final
cleanup PR alongside the rest of the rules/ tree.

Validation:
- skill-validator check skills/redis-vector-search → passed (0 warnings)
- npm run validate → rules + plugin validators green

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: valkirilov

skills/redis-vector-search/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: redis-vector-search
+description: Redis vector search guidance covering HNSW vs FLAT algorithm choice, vector index configuration (dims, distance metric, datatype), filtered hybrid search combining vector similarity with TAG or NUMERIC filters, and the RAG retrieval pattern with RedisVL. Use when defining a VECTOR field in FT.CREATE, integrating embeddings (OpenAI, Cohere, sentence-transformers), tuning HNSW parameters (M, EF_CONSTRUCTION, EF_RUNTIME), building a retrieval-augmented generation pipeline, or filtering vector results by attribute.
+license: MIT
+metadata:
+  author: Redis, Inc.
+  version: "0.1.0"
+---
+
+# Redis Vector Search
+
+Guidance for storing and searching embeddings in Redis. Covers index configuration, algorithm selection, hybrid filtering, and the RAG retrieval pattern with RedisVL.
+
+## When to apply
+
+- Defining a `VECTOR` field in `FT.CREATE` (raw RQE) or a RedisVL `IndexSchema`.
+- Choosing HNSW vs FLAT and tuning HNSW parameters.
+- Adding category, date, or tenant filters to a vector query.
+- Building a retrieval-augmented generation (RAG) pipeline on top of Redis.
+
+This skill builds on the `redis-query-engine` skill — vector fields live inside RQE indexes and share the same `FT.CREATE` / `FT.SEARCH` machinery.
+
+## 1. Configure the vector index properly
+
+Three settings must match the embedding model:
+
+- **`DIM`** — the model's output dimensionality (e.g. 1536 for OpenAI `text-embedding-3-small`). A mismatch produces silent garbage.
+- **`DISTANCE_METRIC`** — `COSINE` for normalized text embeddings (the common case), `IP` for unnormalized inner-product, `L2` for raw Euclidean.
+- **`TYPE` / `datatype`** — usually `FLOAT32`. Use `FLOAT16` or quantized variants only when memory cost is a hard constraint.
+
+Raw RQE:
+
+```
+FT.CREATE idx:docs ON HASH PREFIX 1 doc:
+    SCHEMA
+        content TEXT
+        embedding VECTOR HNSW 6
+            TYPE FLOAT32
+            DIM 1536
+            DISTANCE_METRIC COSINE
+```
+
+RedisVL:
+
+```python
+schema = IndexSchema.from_dict({
+    "index": {"name": "idx:docs", "prefix": "doc:"},
+    "fields": [
+        {"name": "content", "type": "text"},
+        {"name": "embedding", "type": "vector", "attrs": {
+            "dims": 1536, "algorithm": "HNSW",
+            "datatype": "FLOAT32", "distance_metric": "COSINE",
+        }},
+    ]
+})
+```
+
+See [references/index-creation.md](references/index-creation.md) for redis-py and RedisVL variants.
+
+## 2. HNSW vs FLAT
+
+| Algorithm | Speed | Accuracy | Memory | Best for |
+|---|---|---|---|---|
+| **HNSW** | Fast (approximate) | ~95%+ recall (tunable) | Higher | Large datasets (>10k vectors), latency-sensitive |
+| **FLAT** | Slow (exact) | 100% | Lower | Small datasets (<10k), accuracy-critical |
+
+Default to **HNSW** for any production-scale workload. Tuning levers:
+
+- `M` — connections per node (16–64). Higher = better recall, more memory.
+- `EF_CONSTRUCTION` — build-time graph quality (100–500). Higher = better index, slower build.
+- `EF_RUNTIME` — query-time candidate-list size. Higher = better recall, slower queries.
+
+Use **FLAT** when the corpus is small and you need exact results (e.g. semantic dedup over a few thousand items).
+
+See [references/algorithm-choice.md](references/algorithm-choice.md).
+
+## 3. Hybrid search — filter before vector
+
+Apply attribute filters (TAG / NUMERIC) so the engine narrows the search space *before* the vector comparison. Don't fetch a wide result set and then filter client-side — that's slower and less accurate.
+
+```python
+from redisvl.query import VectorQuery
+from redisvl.query.filter import Num, Tag
+
+filters = (Tag("category") == "technology") & (Num("date") >= 2024)
+
+query = VectorQuery(
+    vector=query_embedding,
+    vector_field_name="embedding",
+    return_fields=["content", "category", "date"],
+    num_results=10,
+    filter_expression=filters,
+)
+results = index.query(query)
+```
+
+For **text + vector fusion** (BM25-weighted text scoring combined with vector similarity), use `HybridQuery` on Redis ≥ 8.4 with redis-py ≥ 7.1, or `AggregateHybridQuery` on older Redis. That's a different "hybrid" from filtered vector search above.
+
+See [references/hybrid-search.md](references/hybrid-search.md).
+
+## 4. RAG pattern
+
+Standard pipeline: embed the user query → vector search Redis → pass top-K context to the LLM.
+
+```python
+# Index documents with embeddings
+records = [{"content": doc.content,
+            "embedding": embed_model.encode(doc.content).tolist(),
+            "source": doc.source}
+           for doc in documents]
+index.load(records)
+
+# Retrieve relevant context for a user question
+q_emb = embed_model.encode(user_question)
+results = index.query(VectorQuery(
+    vector=q_emb,
+    vector_field_name="embedding",
+    return_fields=["content", "source"],
+    num_results=5,
+))
+
+# Generate with retrieved context
+context = "\n".join(r["content"] for r in results)
+response = llm.generate(f"Context: {context}\n\nQuestion: {user_question}")
+```
+
+Practical tips:
+
+- **Match metric to model.** Most modern text embedding models pair best with `COSINE`.
+- **Chunk long documents** before indexing — retrieval over 200–500-token chunks usually beats indexing whole pages.
+- **Batch inserts** with `index.load([...])` instead of one call per record.
+- **Pre-filter with attributes** (tenant, recency, document type) before the vector search.
+
+See [references/rag-pattern.md](references/rag-pattern.md).
+
+## References
+
+- [Redis: Vectors](https://redis.io/docs/latest/develop/ai/search-and-query/vectors/)
+- [Redis: RAG quickstart](https://redis.io/docs/latest/develop/get-started/rag/)
+- [RedisVL documentation](https://docs.redisvl.com/en/latest/)

skills/redis-vector-search/references/algorithm-choice.md

@@ -0,0 +1,52 @@
+# Choose HNSW vs FLAT Based on Requirements
+
+Select the right algorithm based on your accuracy requirements and dataset size.
+
+| Algorithm | Speed | Accuracy | Memory | Best For |
+|-----------|-------|----------|--------|----------|
+| HNSW | Fast (approximate) | ~95%+ recall tunable | Higher | Large datasets (>10k vectors) |
+| FLAT | Slower (exact) | 100% (exact) | Lower | Small datasets, accuracy-critical |
+
+**Correct:** Use HNSW for large-scale production workloads.
+
+```python
+from redisvl.schema import IndexSchema
+
+# HNSW - fast approximate search, tunable accuracy
+schema = IndexSchema.from_dict({
+    "index": {"name": "idx:docs", "prefix": "doc:"},
+    "fields": [
+        {"name": "embedding", "type": "vector", "attrs": {
+            "dims": 1536,
+            "algorithm": "HNSW",
+            "distance_metric": "COSINE",
+            "datatype": "FLOAT32",
+            "m": 16,                      # Higher = more accurate, more memory
+            "ef_construction": 200        # Higher = better index quality, slower build
+        }}
+    ]
+})
+```
+
+**Correct:** Use FLAT when exact results are required.
+
+```python
+# FLAT - exact brute-force search, guaranteed accuracy
+schema = IndexSchema.from_dict({
+    "index": {"name": "idx:small", "prefix": "small:"},
+    "fields": [
+        {"name": "embedding", "type": "vector", "attrs": {
+            "dims": 1536,
+            "algorithm": "FLAT",
+            "distance_metric": "COSINE"
+        }}
+    ]
+})
+```
+
+**Tuning HNSW accuracy vs speed:**
+- `M`: Connections per node (16-64). Higher = better recall, more memory
+- `EF_CONSTRUCTION`: Build-time parameter (100-500). Higher = better graph quality
+- `EF_RUNTIME`: Query-time parameter. Higher = better recall, slower queries
+
+Reference: [Redis Vector Search](https://redis.io/docs/latest/develop/ai/search-and-query/vectors/)

skills/redis-vector-search/references/hybrid-search.md

@@ -0,0 +1,43 @@
+# Use Hybrid Search for Better Results
+
+Combine vector similarity with attribute filtering for more relevant results. In this rule, "hybrid" means filtered vector search. Redis and RedisVL also use "hybrid search" for text + vector fusion via `FT.HYBRID` / `HybridQuery`.
+
+**Correct:** Apply filters to reduce search space.
+
+```python
+from redisvl.query import VectorQuery
+from redisvl.query.filter import Num, Tag
+
+filters = (Tag("category") == "technology") & (Num("date") >= 2024) & (Num("date") <= 2025)
+
+query = VectorQuery(
+    vector=query_embedding,
+    vector_field_name="embedding",
+    return_fields=["content", "category", "date"],
+    num_results=10,
+    filter_expression=filters
+)
+
+results = index.query(query)
+```
+
+**Incorrect:** Searching entire vector space when filters apply.
+
+```python
+# Bad: No filter - searches all vectors then filters client-side
+results = index.query(VectorQuery(
+    vector=query_embedding,
+    vector_field_name="embedding",
+    num_results=1000
+))
+# Client-side filtering - wasteful
+filtered = [r for r in results if r["category"] == "technology"]
+```
+
+**Tips:**
+- Use TAG fields for category filters
+- Use NUMERIC fields for date/price ranges
+- Redis auto-selects the filtered vector execution strategy; tune `hybrid_policy` only when needed
+- For true text + vector fusion, use `HybridQuery` on Redis >= 8.4.0 with redis-py >= 7.1.0; use `AggregateHybridQuery` on earlier Redis versions
+
+Reference: [Redis Vector Search](https://redis.io/docs/latest/develop/ai/search-and-query/vectors/)

skills/redis-vector-search/references/index-creation.md

@@ -0,0 +1,76 @@
+# Configure Vector Indexes Properly
+
+Set the correct dimensions, algorithm, and distance metric for your embeddings. Vector indexes can be created via CLI, Redis Insight, or any client library.
+
+**Correct:** Create index via Redis CLI or Insight.
+
+```
+FT.CREATE idx:docs ON HASH PREFIX 1 doc:
+    SCHEMA
+        content TEXT
+        embedding VECTOR HNSW 6
+            TYPE FLOAT32
+            DIM 1536
+            DISTANCE_METRIC COSINE
+```
+
+**Correct:** Create index via Python (redis-py).
+
+```python
+from redis import Redis
+from redis.commands.search.field import TextField, VectorField
+from redis.commands.search.index_definition import IndexDefinition
+
+r = Redis()
+
+# Define schema with vector field
+schema = [
+    TextField("content"),
+    VectorField(
+        "embedding",
+        algorithm="HNSW",
+        attributes={
+            "TYPE": "FLOAT32",
+            "DIM": 1536,  # Must match your embedding model
+            "DISTANCE_METRIC": "COSINE"
+        }
+    )
+]
+
+r.ft("idx:docs").create_index(schema, definition=IndexDefinition(prefix=["doc:"]))
+```
+
+**Correct:** Create index via RedisVL.
+
+```python
+from redisvl.index import SearchIndex
+from redisvl.schema import IndexSchema
+
+schema = IndexSchema.from_dict({
+    "index": {"name": "idx:docs", "prefix": "doc:"},
+    "fields": [
+        {"name": "content", "type": "text"},
+        {"name": "embedding", "type": "vector", "attrs": {
+            "dims": 1536,
+            "algorithm": "HNSW",
+            "datatype": "FLOAT32",
+            "distance_metric": "COSINE"
+        }}
+    ]
+})
+
+index = SearchIndex(schema)
+index.create(overwrite=True)
+```
+
+**Incorrect:** Mismatched dimensions or wrong distance metric.
+
+```python
+# Bad: Wrong dimensions for your model
+{"dims": 768}  # But your selected embedding model outputs a different size
+
+# Bad: Wrong metric for normalized embeddings
+{"distance_metric": "L2"}  # When embeddings are normalized for COSINE
+```
+
+Reference: [Redis Vector Search](https://redis.io/docs/latest/develop/ai/search-and-query/vectors/)

skills/redis-vector-search/references/rag-pattern.md

@@ -0,0 +1,43 @@
+# Implement RAG Pattern Correctly
+
+Store documents with embeddings, retrieve relevant context, and pass to LLM.
+
+**Correct:** Full RAG pipeline with RedisVL.
+
+```python
+from redisvl.index import SearchIndex
+from redisvl.query import VectorQuery
+
+# 1. Store documents with embeddings
+records = []
+for doc in documents:
+    records.append({
+        "content": doc["content"],
+        "embedding": embed_model.encode(doc["content"]).tolist(),
+        "source": doc["source"]
+    })
+
+index.load(records)
+
+# 2. Query with vector similarity
+query_embedding = embed_model.encode(user_question)
+results = index.query(VectorQuery(
+    vector=query_embedding,
+    vector_field_name="embedding",
+    return_fields=["content", "source"],
+    num_results=5
+))
+
+# 3. Pass context to LLM
+context = "\n".join([r["content"] for r in results])
+response = llm.generate(f"Context: {context}\n\nQuestion: {user_question}")
+```
+
+**Best practices:**
+- Match your distance metric to your embedding model; many modern text embeddings already work well with COSINE
+- Batch inserts using `index.load()` with lists
+- Set appropriate M and EF_CONSTRUCTION for HNSW based on dataset size
+- Use filters to reduce the search space before vector comparison
+- Consider chunking long documents for better retrieval
+
+Reference: [Redis RAG Quickstart](https://redis.io/docs/latest/develop/get-started/rag/)