feat: realtime agent reference

[Rodriguespn]

What kind of change does this PR introduce?

Adds comprehensive Realtime reference documentation to the Supabase skill.

What is the current behavior?

The Supabase skill lacks detailed guidance for Realtime features. Developers using the skill had no reference material for Broadcast messaging, Presence tracking, or Postgres Changes subscriptions.

What is the new behavior?

Added a complete set of 8 reference files organized in skills/supabase/references/realtime/ covering:

• Channel Setup (2 files): Channel creation with structured naming conventions (scope:entity:id pattern), configuration options, and authentication setup including RLS policies on realtime.messages
• Broadcast Messaging (2 files): Client-to-client pub/sub patterns and database-triggered broadcasts using realtime.broadcast_changes() and realtime.send()
• Presence Tracking (1 file): Online status tracking, shared state synchronization, custom presence keys, and quota awareness
• Postgres Changes (1 file): Database change listeners with clear guidance on when to use (prototyping, low scale) vs. when to migrate to Broadcast (production, high scale)
• Implementation Patterns (2 files): Critical React cleanup patterns to prevent memory leaks and connection quota exhaustion, plus error handling and connection status management

The SKILL.md resources table was updated to reflect the new Realtime categories, and AGENTS.md was regenerated to include navigation to the new reference files.

Decisions

Key architectural and content decisions made during development:

1. Organized by feature prefix: Adopted the existing db/ pattern with prefixes (setup-, broadcast-, presence-, postgres-, patterns-) to enable predictable file discovery and maintain consistency with other reference categories.

2. Broadcast over Postgres Changes: References consistently recommend Broadcast for new production applications due to scalability advantages. Postgres Changes is positioned as useful for prototyping but limited by per-subscriber RLS checks (100 subscribers = 100 DB reads per change). This guidance came from Supabase's own documentation and the kiro-powers steering file.

3. Security-first approach: Private channels and RLS policies on realtime.messages are emphasized throughout. All examples use private: true and include authentication setup with supabase.realtime.setAuth(). The setup-auth.md reference is marked CRITICAL impact.

4. React cleanup patterns emphasized: Memory leak prevention through proper channel cleanup is given CRITICAL impact rating. The patterns-cleanup.md file includes detailed useRef and useEffect patterns to prevent duplicate subscriptions and ensure channels are removed on unmount.

5. Structured naming convention: Introduced scope:entity:id topic naming pattern (e.g., room:123:messages) to enable topic-based RLS policies and make channel purposes clear and filterable.

6. Database-triggered broadcasts: Highlighted realtime.broadcast_changes() as the scalable alternative to postgres_changes subscriptions, with complete examples of trigger setup and client subscription patterns.

Additional context

Sources consulted:

• Supabase Realtime documentation: concepts, broadcast, presence, postgres-changes, authorization
• Supabase Realtime quotas and pricing documentation
• Supabase Realtime troubleshooting guides
• kiro-powers [supabase-prompts-use-realtime.md](https://github.com/supabase-community/kiro-powers/blob/main/shared/supabase-prompts-use-realtime.md) steering file

Impact ratings:

• CRITICAL: setup-auth.md, broadcast-database.md, patterns-cleanup.md (security and stability)
• HIGH: setup-channels.md, broadcast-basics.md, patterns-errors.md (core functionality)
• MEDIUM: presence-tracking.md, postgres-changes.md (optional features with usage caveats)

Trade-offs considered:

• Postgres Changes is included despite scalability limitations because it's useful for prototyping and appears in existing Supabase projects. Clear guidance directs users to Broadcast for production scenarios.
• Presence is marked MEDIUM impact because it has computational overhead and lower message rate quotas, making it appropriate only for specific use cases (online indicators, typing status) rather than general state synchronization.

[edgurgel]

Added a few comments!