Supabase Skills for Claude Code

Comprehensive Claude Code skills that wrap the Supabase API for database operations, authentication, storage, realtime subscriptions, and edge functions.

Features

• Database Operations - CRUD operations, queries, filters, RPC functions
• Authentication - User management, sign up/in/out, password recovery
• Storage - File uploads, downloads, bucket management, signed URLs
• Realtime - WebSocket subscriptions to database changes, broadcast, presence
• Edge Functions - Deploy and invoke serverless Deno functions

Installation

1. Clone Repository

git clone https://github.com/Nice-Wolf-Studio/claude-code-supabase-skills.git
cd claude-code-supabase-skills

2. Set Environment Variables

Export your Supabase credentials:

export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_KEY="your-anon-or-service-role-key"

Permanent setup (add to ~/.zshrc or ~/.bashrc):

echo 'export SUPABASE_URL="https://your-project.supabase.co"' >> ~/.zshrc
echo 'export SUPABASE_KEY="your-anon-or-service-role-key"' >> ~/.zshrc
source ~/.zshrc

3. Add Skills to Claude Code

Skills are automatically available in Claude Code when this repository is in your workspace. Alternatively, you can:

Option A: Link to global skills directory

# Create skills directory if it doesn't exist
mkdir -p ~/.claude/skills

# Link individual skills
ln -s "$(pwd)/skills/supabase-database" ~/.claude/skills/
ln -s "$(pwd)/skills/supabase-auth" ~/.claude/skills/
ln -s "$(pwd)/skills/supabase-storage" ~/.claude/skills/
ln -s "$(pwd)/skills/supabase-realtime" ~/.claude/skills/
ln -s "$(pwd)/skills/supabase-edge-functions" ~/.claude/skills/

Option B: Use skills from this repository directly

Just reference the skills when working in Claude Code - they'll be available when this project is your working directory.

Available Skills

supabase-database

Database operations using the Supabase REST API.

Common operations:

• SELECT with filters, ordering, pagination
• INSERT single or multiple rows
• UPDATE with conditions
• DELETE rows
• Call RPC functions
• Upsert operations

Usage in Claude Code:

Use the supabase-database skill to query my users table

supabase-auth

Authentication and user management.

Common operations:

• Sign up new users
• Sign in with email/password
• Sign out users
• Get current user
• Update user metadata
• Password recovery
• Admin user management (requires service role key)

Usage in Claude Code:

Use the supabase-auth skill to create a new user account

supabase-storage

File storage operations.

Common operations:

• Create and manage buckets
• Upload files
• Download files
• List files with filters
• Delete files
• Generate public URLs
• Create signed URLs for private files
• Image transformations

Usage in Claude Code:

Use the supabase-storage skill to upload a file to my avatars bucket

supabase-realtime

Realtime WebSocket subscriptions.

Common operations:

• Subscribe to database table changes
• Listen for INSERT, UPDATE, DELETE events
• Broadcast messages to channels
• Track presence
• Filter subscriptions

Usage in Claude Code:

Use the supabase-realtime skill to listen for changes on my posts table

supabase-edge-functions

Serverless edge functions deployment and invocation.

Common operations:

• Invoke edge functions
• Deploy functions via Supabase CLI
• Set environment variables/secrets
• Local function development
• View function logs

Usage in Claude Code:

Use the supabase-edge-functions skill to invoke my process-payment function

Quick Start Examples

Query Database

source scripts/supabase-api.sh

# Get all users
supabase_get "/rest/v1/users?select=*"

# Get users with filter
supabase_get "/rest/v1/users?select=*&age=gt.18&order=created_at.desc"

Create User

source scripts/supabase-api.sh

# Sign up new user
supabase_post "/auth/v1/signup" '{
  "email": "user@example.com",
  "password": "secure_password"
}'

Upload File

BUCKET_NAME="avatars"
FILE_PATH="/path/to/image.jpg"
STORAGE_PATH="user-123/avatar.jpg"

curl -X POST \
  "${SUPABASE_URL}/storage/v1/object/${BUCKET_NAME}/${STORAGE_PATH}" \
  -H "apikey: ${SUPABASE_KEY}" \
  -H "Authorization: Bearer ${SUPABASE_KEY}" \
  -F "file=@${FILE_PATH}"

Invoke Edge Function

source scripts/supabase-api.sh

supabase_post "/functions/v1/hello-world" '{
  "name": "Alice"
}'

Architecture

Shared Helper Script

scripts/supabase-api.sh provides common functions:

• supabase_get(endpoint) - GET requests
• supabase_post(endpoint, json_data) - POST requests
• supabase_patch(endpoint, json_data) - PATCH requests
• supabase_delete(endpoint) - DELETE requests
• validate_env() - Check environment variables
• success(message), error(message), warning(message) - Formatted output

All skills source this helper to avoid duplication.

Skill Structure

Each skill is organized as:

skills/
└── supabase-{feature}/
    └── SKILL.md          # Skill documentation with examples

Skills are self-contained and can be used independently.

Requirements

Environment

• Bash 4.0+
• curl
• jq (recommended for JSON parsing)

Optional Tools

• Supabase CLI (for edge functions deployment)
• websocat or wscat (for realtime WebSocket connections)
• Deno (for local edge function development)

Install Optional Tools

jq (JSON processor):

# macOS
brew install jq

# Linux
sudo apt-get install jq  # Debian/Ubuntu
sudo yum install jq      # RHEL/CentOS

Supabase CLI:

# macOS
brew install supabase/tap/supabase

# Linux
curl -fsSL https://github.com/supabase/cli/releases/latest/download/supabase_linux_amd64.tar.gz | tar -xz
sudo mv supabase /usr/local/bin/

websocat (WebSocket client):

# macOS
brew install websocat

# Linux
wget https://github.com/vi/websocat/releases/download/v1.12.0/websocat.x86_64-unknown-linux-musl
chmod +x websocat.x86_64-unknown-linux-musl
sudo mv websocat.x86_64-unknown-linux-musl /usr/local/bin/websocat

Security

API Keys

Anon Key (public):

• Use for client-side operations
• Respects Row Level Security (RLS) policies
• Safe to expose in client applications

Service Role Key (secret):

• Full admin access, bypasses RLS
• Use only for admin operations
• NEVER expose to clients or commit to git

Best Practices

1. Never commit credentials - Use environment variables
2. Enable Row Level Security - Configure RLS policies in Supabase dashboard
3. Use appropriate keys - Anon for client ops, service role for admin only
4. Validate input - Sanitize user input in edge functions
5. Set file size limits - Configure storage bucket limits
6. Implement rate limiting - Protect public endpoints

Troubleshooting

Environment Variables Not Set

Error: SUPABASE_URL environment variable is not set

Solution: Export your environment variables (see Installation step 2)

Authentication Errors

Error: HTTP 401

Solution: Check that your SUPABASE_KEY is valid and has necessary permissions

File Upload Failures

Error: HTTP 413 Payload too large

Solution: Check bucket file size limits in Supabase dashboard

Edge Function Timeout

Error: HTTP 504 Gateway timeout

Solution: Edge functions have 150s wall clock limit. Optimize function or break into smaller operations.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Resources

• Supabase Documentation
• Supabase REST API
• Supabase Auth API
• Supabase Storage API
• Supabase Realtime
• Supabase Edge Functions

License

MIT License - See LICENSE file for details

Support

For issues and questions:

• GitHub Issues
• Supabase Discord
• Supabase GitHub Discussions

---

Created for Claude Code - Comprehensive Supabase API wrapper skills