feat: vectors agent references

[Rodriguespn]

What kind of change does this PR introduce?

New skill enhancement: Vector/AI reference documentation for the Supabase skill.

What is the current behavior?

The Supabase skill covers database operations, RLS, migrations, schema design, and performance tuning, but lacks guidance on vector search, embeddings, and AI-related features. Users working with semantic search, RAG applications, or pgvector integration have no structured references to follow.

What is the new behavior?

Adds comprehensive vector/AI documentation organized into 6 categories with 8 reference files

Coverage:
Each reference follows the established pattern of showing incorrect/correct examples for common mistakes, with quick reference tables and links to Supabase documentation.

Decisions

Key architectural and content decisions made during development:

1. HNSW as default recommendation: Based on Supabase docs and performance characteristics, HNSW is positioned as the primary index type (CRITICAL impact) while IVFFlat is presented as an alternative (MEDIUM-HIGH). HNSW provides better query performance for most use cases and doesn't require VACUUM for updates.

2. Security invoker emphasis: Every search function example explicitly includes security invoker to ensure RLS policies are respected. This addresses a critical security mistake where functions default to security definer and bypass row-level security, potentially exposing all data.

3. Six-category organization: Split vector topics into Setup, Indexing, Search, Embeddings, RAG, and Performance rather than fewer broader categories. This enables agents to load only the relevant context (e.g., just indexing docs when creating indexes vs. loading all vector documentation).

4. Built-in gte-small prioritized: Positioned Supabase's built-in gte-small embedding model (384 dims) as the primary option before OpenAI (1536 dims). This reduces external dependencies, API costs, and latency for many use cases, though both patterns are documented.

5. Compute sizing guidance: Included specific RAM requirements per Supabase tier (Free: 20K vectors, Small: 50K, Medium: 100K, Large: 250K for 1536-dim vectors). This addresses the common mistake of running large vector workloads on undersized compute where indexes don't fit in memory.

6. Hybrid search with RRF: Documented the complete RRF (Reciprocal Rank Fusion) pattern for combining semantic and full-text search. Emphasized the need to over-fetch (2x match_count) from each source before fusion to avoid missing relevant results.

Additional context

Sources consulted:

• Supabase official documentation pages: pgvector, vector-columns, semantic-search, hybrid-search, vector-indexes, hnsw-indexes, ivf-indexes, automatic-embeddings, rag-with-permissions, going-to-prod, choosing-compute-addon
• Used mcp__claude_ai_Supabase__search_docs tool for targeted documentation queries during development

Integration with existing skill:
The Vectors/AI section integrates with existing Database references, particularly RLS policies (security invoker), connection pooling (transaction mode for pgvector operations), and performance monitoring (pg_stat_statements for vector queries).

Coverage scope:
Focused on production-ready patterns rather than experimental features. Covers the complete lifecycle: setup → indexing → embedding generation → search (semantic and hybrid) → RAG architecture → performance optimization.

[gregnr]

As I'm reviewing this I'm coming up with more questions than answers - not specifically because anything is incorrect in these skills, but moreso because our vector docs themselves need some rework. Can we park these rules for the first iteration of the Supabase skill and iterate on them after initial release?

[Rodriguespn]

As I'm reviewing this I'm coming up with more questions than answers - not specifically because anything is incorrect in these skills, but moreso because our vector docs themselves need some rework. Can we park these rules for the first iteration of the Supabase skill and iterate on them after initial release?

Vectors are a main feature of AI apps for searching and embedding storing, so I would like to have vectors as part of the initial release of Supabase skills. If you think that these skills will mislead agents and do more harm than good happy to keep this PR out of skills initial release @gregnr

[gregnr]

Vectors are a main feature of AI apps for searching and embedding storing

Agreed, but is this our target use case for launch? To me we want a holistic Supabase skill, particularly on high-usage APIs / features. People do use vectors, but not as frequently as other core products. Feel free to push back if you still think we should include these.

[Rodriguespn]

People do use vectors, but not as frequently as other core products.

I agree with you that this feature might not be as popular as our core features so I'm comfortable to ship this first version without the vector references.

not specifically because anything is incorrect in these skills, but moreso because our vector docs themselves need some rework

Could you please give me more context about this and the next steps to take to have these skills? What rework do you think our vector docs need?