feature: vectors agent references by Rodriguespn · Pull Request #41 · supabase/agent-skills

Rodriguespn · 2026-02-09T20:37:08Z

Summary

Adds 8 vector/AI reference files for pgvector-based search and RAG:

Setup (vectors-setup-pgvector): Extension installation, column types, and dimension choices
Indexing (vectors-index-*): HNSW (recommended default) and IVFFlat with parameter tuning
Search (vectors-search-*): Semantic search with cosine similarity and hybrid search using RRF (Reciprocal Rank Fusion)
Embeddings (vectors-embed-generation): Built-in gte-small (384 dims) and OpenAI (1536 dims) patterns
RAG (vectors-rag-patterns): Retrieval-augmented generation with RLS-aware security invoker functions
Performance (vectors-perf-tuning): Compute sizing per tier, index parameter tuning, and probes/ef_search optimization

All search functions use security invoker to respect RLS. Includes compute sizing guidance (Free: 20K vectors, Small: 50K, Medium: 100K for 1536-dim). Updates SKILL.md, AGENTS.md, and _sections.md.

The CLAUDE.md symlink causes installation errors when using `npx skills add` as it tries to copy AGENTS.md to itself. - Remove createClaudeSymlink function from build.ts - Remove claudeSymlink from SkillPaths interface - Remove CLAUDE.md references from AGENTS.md structure documentation - Delete existing CLAUDE.md symlink from skills directory Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add a sanity test that verifies the skills CLI installation works: - Runs `npx skills add . -a claude-code -y` using current directory - Checks command doesn't fail (exit code 0) - Verifies .claude/skills directory is created - Dynamically discovers skills in the repo and verifies they're installed - Checks SKILL.md exists in each installed skill The test runs on every push to main and pull requests. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

This reverts commit c07c234.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: supabase db references * refactor: move database references to db subdirectory Move all database reference files to references/db/ to organize by product area and take advantage of the new subdirectory support in the build system. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

The build system now correctly preserves subdirectory paths when generating the Available References section. For example, files in references/db/ are now listed as references/db/file.md instead of just references/file.md. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-authored-by: Filipe Cabaço <filipecabaco@gmail.com>

The CLAUDE.md symlink causes installation errors when using `npx skills add` as it tries to copy AGENTS.md to itself. - Remove createClaudeSymlink function from build.ts - Remove claudeSymlink from SkillPaths interface - Remove CLAUDE.md references from AGENTS.md structure documentation - Delete existing CLAUDE.md symlink from skills directory Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add a sanity test that verifies the skills CLI installation works: - Runs `npx skills add . -a claude-code -y` using current directory - Checks command doesn't fail (exit code 0) - Verifies .claude/skills directory is created - Dynamically discovers skills in the repo and verifies they're installed - Checks SKILL.md exists in each installed skill The test runs on every push to main and pull requests. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

This reverts commit c07c234.

- Add references/getting-started-locally.md for local development - Update SKILL.md with Local Development reference - Add CLI usage note recommending npx for version consistency Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Remove .claude from git tracking and add to .gitignore. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…itignore Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Merge feature/supabase-skill - Move realtime/* files to realtime-* prefix in references/ - Remove .claude from git tracking - Update SKILL.md with flat paths - Rebuild AGENTS.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…erence

feat: realtime agent reference

Move all database reference files to references/db/ to organize by product area and take advantage of the new subdirectory support in the build system. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- pg_cron requires pg_catalog schema, not extensions (critical fix) - Add publishable/secret key types to Identifying Keys section - Fix Dashboard path to Settings > API Keys - Fix migration up comment: applies all pending, not single Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace bullet list with proper table showing publishable/secret keys alongside legacy anon/service_role keys, matching current Supabase docs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add root _sections.md with db and realtime sections. All reference files use flat structure in references/ directory. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Use <#> (inner product) operator instead of <=> (cosine distance) - Use extensions.vector(512) instead of vector(1536) - Remove `stable` and `security invoker` qualifiers - Add full_text_weight, semantic_weight, rrf_k parameters - Use least(match_count, 30) cap for over-fetching - Remove default value from match_count (required param) - Use parameterized rrf_k and weights in RRF scoring formula Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- hybrid search: improve examples with proper table schema, HNSW index, parameter docs, and operator guidance - perf tuning: fix compute sizing (Nano 0.5GB, add Micro tier, correct Large to ~225K) - rag patterns: add missing match_document_chunks SQL function definition Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Rodriguespn · 2026-02-10T17:37:12Z

@gregnr commented on closed PR

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 · 2026-02-10T17:37:53Z

@Rodriguespn commented on closed PR

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

Rodriguespn · 2026-02-10T17:38:36Z

@gregnr commented on closed PR

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 · 2026-02-10T17:39:05Z

@Rodriguespn commented on closed PR

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?

Rodriguespn and others added 30 commits January 28, 2026 15:53

Revert "fix: remove CLAUDE.md symlink generation from build"

da22ed8

This reverts commit c07c234.

starting point for each product

b7dac62

fix format

e58c06d

templates for skills

87e7356

new structure

0ec4be8

update agents.md

c8974d3

second refactor

3a4c46f

add readme

e193f97

review skills.md and template through skill-creator skill

fbfa46f

chore: update AGENTS.md after build

94b786b

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

sub agents

ee526ca

research agent keeps track of the source URLs

d7a419c

chore: remove CLAUDE.md symlink from supabase skill

f5587cb

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

feat: realtime agent references

3cfd5f9

PR feedback

bbeb790

chore: rebuild AGENTS.md

cfdaec4

Update skills/supabase/references/realtime/_sections.md

8a6ac3c

Co-authored-by: Filipe Cabaço <filipecabaco@gmail.com>

Update skills/supabase/references/realtime/patterns-cleanup.md

b0fdc14

Co-authored-by: Filipe Cabaço <filipecabaco@gmail.com>

Update skills/supabase/references/realtime/broadcast-basics.md

fc7cf49

Co-authored-by: Filipe Cabaço <filipecabaco@gmail.com>

Update skills/supabase/references/realtime/postgres-changes.md

7cdce13

Co-authored-by: Filipe Cabaço <filipecabaco@gmail.com>

Update skills/supabase/references/realtime/presence-tracking.md

313aed0

Co-authored-by: Filipe Cabaço <filipecabaco@gmail.com>

Revert "fix: remove CLAUDE.md symlink generation from build"

1718f83

This reverts commit c07c234.

starting point for each product

82564e4

fix format

51360c8

Rodriguespn and others added 20 commits January 30, 2026 13:40

chore: ignore .claude directory

fff97dc

Remove .claude from git tracking and add to .gitignore. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

chore: remove getting-started-locally guide and .claude/skills from g…

05cc2b1

…itignore Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

chore: remove getting-started-locally references from SKILL.md

b6359f7

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

chore: remove .claude directory from tracking

c677664

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix: revert build.ts to flat structure version

7a37c51

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Merge branch 'feature/supabase-skill' into feature/realtime-agent-ref…

1aca995

…erence

Merge pull request #21 from supabase/feature/realtime-agent-reference

0cad768

feat: realtime agent reference

feat: supabase db references

7b36415

refactor: move database references to db subdirectory

afb57a7

Move all database reference files to references/db/ to organize by product area and take advantage of the new subdirectory support in the build system. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix: update API key types to table format with 4 key types

26b8ecb

Replace bullet list with proper table showing publishable/secret keys alongside legacy anon/service_role keys, matching current Supabase docs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix: add npx prefix to supabase CLI commands in db migration references

f505510

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor: add _sections.md and flatten reference structure

397502e

Add root _sections.md with db and realtime sections. All reference files use flat structure in references/ directory. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat: vector agent references

f4d228d

refactor: flatten vectors references to root references directory

6bbc7d3

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

chore: refresh branch for PR

d19a939

Rodriguespn requested a review from gregnr February 9, 2026 20:37

Rodriguespn self-assigned this Feb 9, 2026

Rodriguespn added the new-rule Adding a new rule(s) to a skill label Feb 9, 2026

Rodriguespn force-pushed the feature/supabase-skill branch 3 times, most recently from 92fcd19 to 6bb9a7c Compare February 16, 2026 15:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Comments

feature: vectors agent references#41

feature: vectors agent references#41
Rodriguespn wants to merge 63 commits intofeature/supabase-skillfrom
feature/vectors-agent-references

Rodriguespn commented Feb 9, 2026

Uh oh!

Rodriguespn commented Feb 10, 2026

Uh oh!

Rodriguespn commented Feb 10, 2026

Uh oh!

Rodriguespn commented Feb 10, 2026

Uh oh!

Rodriguespn commented Feb 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Comments

Conversation

Rodriguespn commented Feb 9, 2026

Summary

Uh oh!

Rodriguespn commented Feb 10, 2026

Uh oh!

Rodriguespn commented Feb 10, 2026

Uh oh!

Rodriguespn commented Feb 10, 2026

Uh oh!

Rodriguespn commented Feb 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants