Communitygithub.com

Supabase

Skill abrangente para tarefas envolvendo Supabase (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues) e integrações com client libraries e SSR em frameworks como Next.js, React, SvelteKit, Astro e Remix. Inclui boas práticas de segurança, uso da CLI e do servidor MCP.

O que é Supabase?

Este skill foi projetado para desenvolvedores e agentes de IA que trabalham com o ecossistema Supabase. Ele cobre todos os produtos principais da Supabase — Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron e Queues — além das integrações com `supabase-js` e `@supabase/ssr` para frameworks como Next.js, React, SvelteKit, Astro e Remix. O skill fornece orientações detalhadas sobre segurança, incluindo armadilhas comuns de RLS, uso correto de `SECURITY DEFINER`, tratamento de sessões e JWTs, e configuração de políticas de acesso. Também ensina como usar a Supabase CLI (comandos com `--help`, criação de migrações, execução de consultas) e o servidor MCP (autenticação OAuth 2.1, resolução de problemas de conexão e busca de documentação). O objetivo é evitar que o agente confie em dados de treinamento desatualizados, incentivando a verificação contra o changelog oficial e a documentação atual. Funciona com agentes que suportam execução de comandos shell, acesso à web e ao MCP da Supabase.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Jo5i4swastaken/Skills-Locker/tree/HEAD/skills/supabase

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Supabase faz?

Princípios Fundamentais

1. A Supabase muda com frequência — verifique o changelog e a documentação atual antes de implementar. Não confie nos dados de treinamento para funcionalidades da Supabase. Assinaturas de funções, configurações do config.toml e convenções de API mudam entre versões.

Primeiro, acesse https://supabase.com/changelog.md (um índice resumido leve — não uma busca pesada), procure por tags breaking-change relevantes para sua tarefa e siga a página vinculada para qualquer uma que se aplique. Em seguida, consulte o tópico relevante usando os métodos de acesso à documentação abaixo.

2. Verifique seu trabalho. Após implementar qualquer correção, execute uma consulta de teste para confirmar que a alteração funciona. Uma correção sem verificação está incompleta.

3. Recupere-se de erros, não repita em loop. Se uma abordagem falhar após 2 a 3 tentativas, pare e reconsidere. Tente um método diferente, verifique a documentação, inspecione o erro com mais cuidado e revise os logs relevantes quando disponíveis. Os problemas da Supabase nem sempre são resolvidos repetindo o mesmo comando, e a resposta nem sempre está nos logs, mas vale a pena verificar os logs antes de prosseguir.

4. Expondo tabelas à API de Dados: Dependendo das configurações da API de Dados do usuário, tabelas recém-criadas podem não ser expostas automaticamente pela API REST. Se for esse o caso, será necessário conceder acesso explicitamente aos papéis anon e authenticated.

Observe que isso é separado do RLS, que controla quais linhas são visíveis depois que uma tabela está acessível, e não se a tabela é acessível ou não.

Quando um usuário relatar que uma tabela criada via SQL está inesperadamente inacessível, verifique as configurações da API de Dados e se os papéis receberam acesso via GRANT SQL explícito. Ao conceder acesso público (anon/authenticated), sempre habilite também o RLS. Consulte Expondo uma Tabela à API de Dados para o fluxo de configuração completo.

5. RLS em esquemas expostos. Habilite o RLS em todas as tabelas de qualquer esquema exposto, o que inclui public por padrão. Isso é crítico na Supabase porque tabelas em esquemas expostos podem ser acessadas pela API de Dados quando os papéis anon/authenticated têm acesso (consulte Expondo uma Tabela à API de Dados). Para esquemas privados, prefira RLS como defesa em profundidade. Após habilitar o RLS, crie políticas que correspondam ao modelo de acesso real, em vez de usar o mesmo padrão auth.uid() para todas as tabelas.

6. Lista de verificação de segurança. Ao trabalhar em qualquer tarefa da Supabase que envolva autenticação, RLS, views, armazenamento ou dados do usuário, percorra esta lista. Estas são armadilhas de segurança específicas da Supabase que criam vulnerabilidades silenciosamente:

  • Segurança de autenticação e sessão

    • Nunca use claims de user_metadata em decisões de autorização baseadas em JWT. Na Supabase, raw_user_meta_data é editável pelo usuário e pode aparecer em auth.jwt(), portanto, não é seguro para políticas de RLS ou qualquer outra lógica de autorização. Armazene dados de autorização em raw_app_meta_data / app_metadata.
    • Excluir um usuário não invalida tokens de acesso existentes. Faça logout ou revogue as sessões primeiro, mantenha a expiração do JWT curta para aplicativos sensíveis e, para garantias rigorosas, valide session_id em relação a auth.sessions em operações sensíveis.
    • Se você usar app_metadata ou auth.jwt() para autorização, lembre-se de que as claims do JWT nem sempre estão atualizadas até que o token do usuário seja renovado.
  • Exposição de chave de API e cliente

    • Nunca exponha a chave service_role ou a chave secreta em clientes públicos. Prefira chaves publicáveis para código frontend. Chaves anon legadas são apenas para compatibilidade. No Next.js, qualquer variável de ambiente NEXT_PUBLIC_ é enviada ao navegador.
  • RLS, views e código de banco de dados privilegiado

    • Views ignoram RLS por padrão. No Postgres 15 e superior, use CREATE VIEW ... WITH (security_invoker = true). Em versões mais antigas do Postgres, proteja suas views revogando o acesso dos papéis anon e authenticated, ou colocando-as em um esquema não exposto.
    • UPDATE requer uma política SELECT. No RLS do Postgres, um UPDATE precisa primeiro fazer SELECT da linha. Sem uma política SELECT, updates retornam silenciosamente 0 linhas — sem erro, apenas nenhuma alteração.
    • auth.role() está obsoleto — use a cláusula TO. A Supabase descontinuou auth.role() em favor da especificação direta do papel alvo na política com TO authenticated ou TO anon. Além da descontinuação, auth.role() = 'authenticated' quebra silenciosamente quando logins anônimos estão habilitados, porque usuários anônimos carregam o papel Postgres authenticated e passam na verificação independentemente de o usuário estar realmente logado.
      -- Obsoleto (não use)
      create policy "example" on table_name for select
      using ( auth.role() = 'authenticated' );
      
    • TO authenticated sozinho é autenticação sem autorização (BOLA / IDOR). Usar TO authenticated apenas verifica o papel — não restringe quais linhas um usuário pode acessar. O padrão correto combina TO authenticated com um predicado de propriedade em USING:
      create policy "example" on table_name for select
      to authenticated
      using ( (select auth.uid()) = user_id );
      
    • Políticas de UPDATE exigem USING e WITH CHECK. Sem WITH CHECK, um usuário pode reatribuir o user_id de uma linha para outro usuário:
      create policy "example" on table_name for update
      to authenticated
      using ( (select auth.uid()) = user_id )
      with check ( (select auth.uid()) = user_id );
      
    • Funções SECURITY DEFINER ignoram RLS. Uma função SECURITY DEFINER é executada com os privilégios de seu criador — normalmente um papel com bypassrls (por exemplo, postgres). Nunca adicione SECURITY DEFINER para resolver um erro de permissão; ele remove silenciosamente o controle de acesso sem corrigir a causa subjacente. Prefira SECURITY INVOKER.
    • Funções SECURITY DEFINER em public são chamáveis por todos os papéis. O Postgres concede EXECUTE a PUBLIC por padrão para cada nova função, portanto, qualquer função SECURITY DEFINER em public é um endpoint de API pública chamável por anon e authenticated (que herdam de PUBLIC) sem qualquer concessão adicional. Quando SECURITY DEFINER for realmente necessário (por exemplo, ignorar RLS em uma tabela de consulta interna), mantenha a função em um esquema não exposto, sempre inclua uma verificação auth.uid() no corpo da função e execute supabase db advisors após fazer alterações.
  • Controle de acesso ao Storage

    • Upsert no Storage requer INSERT + SELECT + UPDATE. Conceder apenas INSERT permite novos uploads, mas a substituição de arquivos (upsert) falha silenciosamente. Você precisa de todos os três.

Para qualquer preocupação de segurança não coberta acima, acesse o índice de segurança de produtos da Supabase: https://supabase.com/docs/guides/security/product-security.md

CLI da Supabase

Sempre descubra comandos usando --help — nunca adivinhe. A estrutura da CLI muda entre versões.

supabase --help                    # Todos os comandos de nível superior
supabase <grupo> --help            # Subcomandos (ex.: supabase db --help)
supabase <grupo> <comando> --help  # Flags para um comando específico

Pegadinhas conhecidas da CLI da Supabase:

  • supabase db query requer CLI v2.79.0+ → use MCP execute_sql ou psql como alternativa
  • supabase db advisors requer CLI v2.81.3+ → use MCP get_advisors como alternativa
  • Quando você precisar de um novo arquivo SQL de migração, sempre crie-o primeiro com supabase migration new <nome>. Nunca invente um nome de arquivo de migração ou confie na memória para o formato esperado.

Verificação de versão e atualização: Execute supabase --version para verificar. Para changelogs da CLI e funcionalidades específicas de versão, consulte a documentação da CLI ou os lançamentos no GitHub.

Servidor MCP da Supabase

Para instruções de configuração, URL do servidor e configuração, consulte o guia de configuração MCP.

Solução de problemas de conexão — siga estas etapas em ordem:

  1. Verifique se o servidor está acessível: curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp Um 401 é esperado (sem token) e significa que o servidor está ativo. Timeout ou "connection refused" significa que pode estar inativo.

  2. Verifique a configuração do .mcp.json: Verifique se a raiz do projeto tem um .mcp.json válido com a URL correta do servidor. Se estiver faltando, crie um apontando para https://mcp.supabase.com/mcp.

  3. Autentique o servidor MCP: Se o servidor estiver acessível e o .mcp.json estiver correto, mas as ferramentas não estiverem visíveis, o usuário precisa se autenticar. O servidor MCP da Supabase usa OAuth 2.1 — informe ao usuário para acionar o fluxo de autenticação em seu agente, concluí-lo no navegador e recarregar a sessão.

Documentação da Supabase

Antes de implementar qualquer funcionalidade da Supabase, encontre a documentação relevante. Use estes métodos em ordem de prioridade:

  1. Ferramenta MCP search_docs (preferida — retorna trechos relevantes diretamente)
  2. Buscar páginas de documentação como markdown — qualquer página de documentação pode ser obtida anexando .md ao caminho da URL.
  3. Pesquisa na web para tópicos específicos da Supabase quando você não souber qual página consultar.

Fazendo e Confirmando Alterações no Esquema

Para fazer alterações no esquema, use execute_sql (MCP) ou supabase db query (CLI). Eles executam SQL diretamente no banco de dados sem criar entradas no histórico de migração, permitindo iterar livremente e gerar uma migração limpa quando estiver pronto.

NÃO use apply_migration para alterar um esquema de banco de dados local — ele escreve uma entrada no histórico de migração a cada chamada, o que significa que você não pode iterar, e supabase db diff / supabase db pull produzirão diffs vazios ou conflitantes. Se você usá-lo, ficará preso ao SQL que passou na primeira tentativa.

Quando estiver pronto para confirmar suas alterações em um arquivo de migração:

  1. Execute os advisors → supabase db advisors (CLI v2.81.3+) ou MCP get_advisors. Corrija quaisquer problemas.
  2. Revise a Lista de Verificação de Segurança acima se suas alterações envolverem views, funções, triggers ou storage.
  3. Gere a migração → supabase db pull <nome-descritivo> --local --yes
  4. Verifique → supabase migration list --local

Guias de Referência

  • Feedback sobre o Skill → references/skill-feedback.md DEVE ler quando o usuário relatar que este skill forneceu orientação incorreta ou está faltando informações.

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

Jo5i4swastaken/Skills-Locker

Implements the "100% Retrieval Strategy" by Vercel. Injects a compressed docs index into AGENTS.md/CLAUDE.md to guarantee the agent always uses your global skills and best practices.

Jo5i4swastaken/Skills-Locker

Premium brand-kit image generation skill for creating high-end brand-guidelines boards, logo systems, identity decks, and visual-world presentations. Trained for minimalist, cinematic, editorial, dark-tech, luxury, cultural, security, gaming, developer-tool, and consumer-app brand systems. Optimized for intentional logo concepting, refined composition, sparse typography, strong symbolic meaning, premium mockups, art-directed imagery, and flexible grid layouts.

Jo5i4swastaken/Skills-Locker

Rewrite text to make ideas and sentences clearer and easier to understand. Use when the user wants to simplify prose, untangle a tangled sentence, reduce jargon, sharpen vague claims, or make writing accessible to a wider audience. Works on any text: docs, emails, blog posts, reports, marketing copy, slide bullets, academic prose. TRIGGER on phrases like: "make this clearer", "clarify this", "simplify this", "rewrite for clarity", "plain language", "reduce jargon", "make it easier to understand", "untangle this", "explain this simply", "tighten this up", "make this readable". Returns the rewritten text only — no diff, no commentary.

Jo5i4swastaken/Skills-Locker

Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.

Jo5i4swastaken/Skills-Locker

Elite UX/UI & Advanced GSAP Motion Engineer. Enforces Python-driven true randomization for layout variance, strict AIDA page structure, wide editorial typography (bans 6-line wraps), gapless bento grids, strict GSAP ScrollTriggers (pinning, stacking, scrubbing), inline micro-images, and massive section spacing.

Jo5i4swastaken/Skills-Locker

Remove signs of AI-generated writing from text. Use when editing or reviewing text to make it sound more natural and human-written. Based on Wikipedia's comprehensive "Signs of AI writing" guide. Detects and fixes patterns including: inflated symbolism, promotional language, superficial -ing analyses, vague attributions, em dash overuse, rule of three, AI vocabulary words, negative parallelisms, and excessive conjunctive phrases.

Jo5i4swastaken/Skills-Locker

Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.

Jo5i4swastaken/Skills-Locker

Agent Media OS — resolve any media need (BGM, SFX, image, icon) into a frozen local file + ledger record. One verb (`resolve`) handles the full cascade — project cache, global cache, HeyGen catalog search, freeze, register. Keeps search noise on disk, hands the agent a path. Use when a composition needs background music, sound effects, images, or icons.

Jo5i4swastaken/Skills-Locker

Author a HyperFrames slideshow composition — a presentation, pitch deck, or interactive deck with discrete slides, fragment reveals, branching sequences, and hotspot navigation. Use as an intent check when the user asks for a presentation, pitch deck, slide deck, interactive deck, or page-to-deck conversion that might be a slideshow; if the user did not explicitly ask for a slideshow / slide show, confirm before authoring.

Jo5i4swastaken/Skills-Locker

When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms, or wants to do social listening and engagement triage. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' 'viral content,' 'what should I post,' 'repurpose this content,' 'tweet ideas,' 'LinkedIn carousel,' 'social media strategy,' 'grow my following,' 'TikTok video,' 'Reels,' 'Shorts,' 'video script,' 'video hook,' 'short-form video,' 'create a reel,' 'social listening,' 'brand mentions,' 'competitor monitoring,' 'top posts to comment on,' 'find people asking for,' 'carousel,' 'slide-by-slide,' or 'document post.' Use this for social media content creation, repurposing, scheduling, short-form video scripting, and social listening. For broader content strategy, see content-strategy. For paid ads, see ad-creative. For earned media, see public-relations.

Jo5i4swastaken/Skills-Locker

Watch a video (URL or local path). Downloads with yt-dlp, extracts auto-scaled frames with ffmpeg, pulls the transcript from captions (or Whisper API fallback), and hands the result to Claude so it can answer questions about what's in the video.

Habilidades Relacionadas