Communitygithub.com

Supabase

Supabase(데이터베이스, 인증, Edge Functions, Realtime, Storage, Vectors, Cron, Queues) 관련 모든 작업을 수행할 때 사용합니다. 또한 클라이언트 라이브러리(supabase-js, @supabase/ssr)와 Next.js, React, SvelteKit, Astro, Remix에서의 SSR 통합, 인증 문제(로그인, 로그아웃, 세션, JWT, 쿠키, getSession, getUser, getClaims, RLS), Supabase CLI 또는 MCP 서버, 스키마 변경, 마이그레이션, 보안 감사, Postgres 확장(pg_graphql, pg_cron, pg_vector)을 다룹니다.

Supabase란 무엇인가요?

이 스킬은 Supabase 플랫폼의 모든 기능을 안전하고 효과적으로 사용할 수 있도록 설계된 포괄적인 가이드입니다. 핵심 원칙으로 Supabase의 빈번한 변경 사항을 수동으로 확인하고, 변경 사항을 검증하며, 오류 발생 시 무한 반복하지 않고 다른 접근 방식을 시도하도록 안내합니다. 특히 보안에 중점을 두어 RLS(행 수준 보안), JWT 클레임, API 키 노출, SECURITY DEFINER 함수 등 일반적인 보안 함정을 피하는 방법을 상세히 설명합니다. 또한 Supabase CLI 명령어, MCP 서버 설정 및 문제 해결, 문서 검색 방법, 스키마 변경 및 마이그레이션 모범 사례를 다룹니다. 이 스킬은 Claude Code, Cursor, Codex 등 모든 AI 에이전트에서 사용할 수 있으며, 개발자가 Supabase 프로젝트를 진행할 때 신뢰할 수 있는 참고 자료 역할을 합니다.

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

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Supabase은(는) 무엇을 하나요?

핵심 원칙

1. Supabase는 자주 변경됩니다 — 구현하기 전에 변경 로그와 최신 문서를 확인하세요. Supabase 기능에 대해 학습 데이터에 의존하지 마세요. 함수 시그니처, config.toml 설정, API 규칙은 버전 간에 변경됩니다.

먼저 https://supabase.com/changelog.md(가벼운 요약 인덱스 — 무거운 풀링이 아님)를 가져와서 작업과 관련된 breaking-change 태그를 스캔하고, 해당하는 경우 연결된 페이지를 따르세요. 그런 다음 아래 문서 접근 방법을 사용하여 관련 주제를 찾아보세요.

2. 작업을 검증하세요. 수정을 구현한 후에는 테스트 쿼리를 실행하여 변경 사항이 적용되었는지 확인하세요. 검증 없이 수정하는 것은 완료된 것이 아닙니다.

3. 오류에서 복구하고, 반복하지 마세요. 접근 방식이 2-3회 시도 후에도 실패하면 멈추고 다시 생각하세요. 다른 방법을 시도하고, 문서를 확인하고, 오류를 더 주의 깊게 검사하고, 가능한 경우 관련 로그를 검토하세요. Supabase 문제는 항상 같은 명령어를 재시도한다고 해결되는 것이 아니며, 답이 항상 로그에 있는 것도 아니지만, 진행하기 전에 로그를 확인하는 것이 종종 가치 있습니다.

4. Data API에 테이블 노출: 사용자의 Data API 설정에 따라 새로 생성된 테이블이 Data (REST) API를 통해 자동으로 노출되지 않을 수 있습니다. 이 경우 anon 및 authenticated 역할에 명시적으로 액세스 권한을 부여해야 합니다.

이는 RLS와 별개입니다. RLS는 테이블에 접근 가능할 때 어떤 행이 보이는지를 제어할 뿐, 테이블 자체에 접근 가능한지 여부를 제어하지는 않습니다.

사용자가 SQL로 생성한 테이블에 예기치 않게 접근할 수 없다고 보고하는 경우, Data API 설정과 명시적 GRANT SQL을 통해 역할에 액세스 권한이 부여되었는지 확인하세요. 공개(anon/authenticated) 액세스를 부여할 때는 항상 RLS도 활성화하세요. 전체 설정 워크플로는 Data API에 테이블 노출을 참조하세요.

5. 노출된 스키마의 RLS. 기본적으로 public을 포함한 노출된 스키마의 모든 테이블에 RLS를 활성화하세요. Supabase에서 anon/authenticated 역할에 액세스 권한이 있을 때 노출된 스키마의 테이블이 Data API를 통해 도달 가능할 수 있기 때문에 이것은 중요합니다 (Data API에 테이블 노출 참조). 비공개 스키마의 경우 심층 방어 차원에서 RLS를 선호하세요. RLS를 활성화한 후에는 모든 테이블을 동일한 auth.uid() 패턴으로 기본 설정하지 말고 실제 액세스 모델과 일치하는 정책을 만드세요.

6. 보안 체크리스트. 인증, RLS, 뷰, 스토리지 또는 사용자 데이터를 다루는 Supabase 작업을 할 때마다 이 체크리스트를 실행하세요. 이들은 자동으로 취약점을 생성하는 Supabase 특화 보안 함정입니다.

  • 인증 및 세션 보안

    • JWT 기반 권한 부여 결정에 user_metadata 클레임을 절대 사용하지 마세요. Supabase에서 raw_user_meta_data는 사용자가 편집 가능하며 auth.jwt()에 나타날 수 있으므로 RLS 정책이나 다른 권한 부여 로직에 안전하지 않습니다. 대신 권한 부여 데이터는 raw_app_meta_data / app_metadata에 저장하세요.
    • 사용자를 삭제해도 기존 액세스 토큰이 무효화되지 않습니다. 먼저 로그아웃하거나 세션을 취소하고, 민감한 애플리케이션의 경우 JWT 만료 시간을 짧게 유지하며, 엄격한 보장을 위해 민감한 작업 시 auth.sessions에 대해 session_id를 검증하세요.
    • 권한 부여에 app_metadata 또는 auth.jwt()를 사용하는 경우, 사용자 토큰이 새로 고쳐질 때까지 JWT 클레임이 항상 최신 상태가 아님을 기억하세요.
  • API 키 및 클라이언트 노출

    • service_role 또는 시크릿 키를 공개 클라이언트에 절대 노출하지 마세요. 프론트엔드 코드에는 게시 가능한 키를 선호하세요. 레거시 anon 키는 호환성을 위해서만 사용됩니다. Next.js에서 NEXT_PUBLIC_ 환경 변수는 브라우저로 전송됩니다.
  • RLS, 뷰 및 권한 있는 데이터베이스 코드

    • 뷰는 기본적으로 RLS를 우회합니다. Postgres 15 이상에서는 CREATE VIEW ... WITH (security_invoker = true)를 사용하세요. 이전 Postgres 버전에서는 anon 및 authenticated 역할의 액세스를 취소하거나 노출되지 않은 스키마에 넣어 뷰를 보호하세요.
    • UPDATE는 SELECT 정책이 필요합니다. Postgres RLS에서 UPDATE는 먼저 행을 SELECT해야 합니다. SELECT 정책이 없으면 업데이트는 자동으로 0개 행을 반환합니다 — 오류 없음, 변경 사항 없음.
    • auth.role()은 더 이상 사용되지 않습니다 — 대신 TO 절을 사용하세요. Supabase는 auth.role()을 더 이상 사용하지 않고 정책에서 대상 역할을 TO authenticated 또는 TO anon으로 직접 지정하는 방식을 권장합니다. 더 이상 사용되지 않는다는 점 외에도, auth.role() = 'authenticated'는 익명 로그인이 활성화되면 자동으로 중단됩니다. 익명 사용자는 authenticated Postgres 역할을 가지고 있으므로 사용자가 실제로 로그인했는지 여부와 관계없이 검사를 통과하기 때문입니다.
      -- 더 이상 사용되지 않음 (사용 금지)
      create policy "example" on table_name for select
      using ( auth.role() = 'authenticated' );
      
    • TO authenticated 만으로는 인증일 뿐, 권한 부여가 아닙니다 (BOLA / IDOR). TO authenticated를 사용하는 것은 역할만 확인할 뿐 — 사용자가 액세스할 수 있는 행을 제한하지 않습니다. 올바른 패턴은 TO authenticated를 USING의 소유권 조건과 결합하는 것입니다:
      create policy "example" on table_name for select
      to authenticated
      using ( (select auth.uid()) = user_id );
      
    • UPDATE 정책은 USING과 WITH CHECK가 모두 필요합니다. WITH CHECK가 없으면 사용자가 행의 user_id를 다른 사용자로 재할당할 수 있습니다:
      create policy "example" on table_name for update
      to authenticated
      using ( (select auth.uid()) = user_id )
      with check ( (select auth.uid()) = user_id );
      
    • SECURITY DEFINER 함수는 RLS를 우회합니다. SECURITY DEFINER 함수는 생성자의 권한으로 실행됩니다 — 일반적으로 bypassrls (예: postgres)가 있는 역할입니다. 권한 오류를 해결하기 위해 SECURITY DEFINER를 추가하지 마세요. 이는 근본적인 원인을 수정하지 않고 자동으로 액세스 제어를 제거합니다. SECURITY INVOKER를 선호하세요.
    • public의 SECURITY DEFINER 함수는 모든 역할이 호출할 수 있습니다. Postgres는 새 함수마다 기본적으로 PUBLIC에 EXECUTE를 부여하므로, public의 모든 SECURITY DEFINER 함수는 추가 권한 부여 없이 anon 및 authenticated(PUBLIC에서 상속)가 호출할 수 있는 공개 API 엔드포인트입니다. SECURITY DEFINER가 실제로 필요한 경우(예: 내부 조회 테이블에서 RLS 우회), 함수를 노출되지 않은 스키마에 유지하고, 함수 본문에 항상 auth.uid() 검사를 포함하며, 변경 후 supabase db advisors를 실행하세요.
  • 스토리지 액세스 제어

    • 스토리지 upsert에는 INSERT + SELECT + UPDATE가 필요합니다. INSERT만 부여하면 새 업로드는 가능하지만 파일 교체(upsert)는 자동으로 실패합니다. 세 가지 모두 필요합니다.

위에서 다루지 않은 보안 문제에 대해서는 Supabase 제품 보안 인덱스 https://supabase.com/docs/guides/security/product-security.md를 가져오세요.

Supabase CLI

항상 --help를 통해 명령어를 발견하세요 — 절대 추측하지 마세요. CLI 구조는 버전 간에 변경됩니다.

supabase --help                    # 모든 최상위 명령어
supabase <group> --help            # 하위 명령어 (예: supabase db --help)
supabase <group> <command> --help  # 특정 명령어의 플래그

Supabase CLI 알려진 문제점:

  • supabase db query는 CLI v2.79.0+ 가 필요합니다 → 대안으로 MCP execute_sql 또는 psql을 사용하세요.
  • supabase db advisors는 CLI v2.81.3+ 가 필요합니다 → 대안으로 MCP get_advisors를 사용하세요.
  • 새 마이그레이션 SQL 파일이 필요할 때는 항상 먼저 supabase migration new <name>으로 생성하세요. 마이그레이션 파일 이름을 직접 만들거나 예상 형식을 기억에 의존하지 마세요.

버전 확인 및 업그레이드: supabase --version을 실행하여 확인하세요. CLI 변경 로그 및 버전별 기능은 CLI 문서 또는 GitHub 릴리스를 참조하세요.

Supabase MCP 서버

설정 지침, 서버 URL 및 구성은 MCP 설정 가이드를 참조하세요.

연결 문제 해결 — 다음 단계를 순서대로 따르세요:

  1. 서버에 연결 가능한지 확인: curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp 401은 예상된 응답(토큰 없음)이며 서버가 작동 중임을 의미합니다. 시간 초과 또는 "connection refused"는 서버가 다운되었을 수 있음을 의미합니다.

  2. .mcp.json 구성 확인: 프로젝트 루트에 올바른 서버 URL이 포함된 유효한 .mcp.json이 있는지 확인하세요. 없으면 https://mcp.supabase.com/mcp를 가리키는 파일을 만드세요.

  3. MCP 서버 인증: 서버에 연결 가능하고 .mcp.json이 올바른데도 도구가 보이지 않으면 사용자가 인증해야 합니다. Supabase MCP 서버는 OAuth 2.1을 사용합니다 — 사용자에게 에이전트에서 인증 흐름을 트리거하고, 브라우저에서 완료한 다음, 세션을 다시 로드하도록 안내하세요.

Supabase 문서

Supabase 기능을 구현하기 전에 관련 문서를 찾으세요. 다음 방법을 우선 순위로 사용하세요:

  1. MCP search_docs 도구 (선호 — 관련 발췌문을 직접 반환)
  2. 문서 페이지를 마크다운으로 가져오기 — 모든 문서 페이지는 URL 경로에 .md를 추가하여 가져올 수 있습니다.
  3. 웹 검색 — 어떤 페이지를 봐야 할지 모르는 Supabase 관련 주제에 대해 검색하세요.

스키마 변경 사항 만들기 및 커밋하기

스키마 변경을 하려면 execute_sql (MCP) 또는 supabase db query (CLI)를 사용하세요. 이들은 데이터베이스에 마이그레이션 기록 항목을 생성하지 않고 직접 SQL을 실행하므로 자유롭게 반복하고 준비가 되면 깔끔한 마이그레이션을 생성할 수 있습니다.

로컬 데이터베이스 스키마를 변경하기 위해 apply_migration을 사용하지 마세요 — 호출할 때마다 마이그레이션 기록 항목을 기록하므로 반복할 수 없고, supabase db diff / supabase db pull이 빈 diff 또는 충돌하는 diff를 생성합니다. 사용하면 처음 시도한 SQL에 갇히게 됩니다.

변경 사항을 마이그레이션 파일에 커밋할 준비가 되면:

  1. 어드바이저 실행 → supabase db advisors (CLI v2.81.3+) 또는 MCP get_advisors. 문제를 수정하세요.
  2. 변경 사항에 뷰, 함수, 트리거 또는 스토리지가 포함된 경우 위의 보안 체크리스트를 검토하세요.
  3. 마이그레이션 생성 → supabase db pull <설명-이름> --local --yes
  4. 확인 → supabase migration list --local

참고 가이드

  • 스킬 피드백 → references/skill-feedback.md 사용자가 이 스킬이 잘못된 지침을 제공했거나 정보가 누락되었다고 보고하는 경우 반드시 읽어야 합니다.

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.

관련 스킬