supabase · 스킬 지원 에이전트
앱에 로그인, 데이터베이스, 파일 저장을 붙일 때 쓰는 Supabase 작업 스킬입니다.
앱에 로그인, 데이터베이스, 파일 저장을 붙일 때 쓰는 Supabase 작업 스킬입니다. 여러 제품의 설정과 개발 흐름을 한 프로젝트 안에서 연결해 살펴봅니다.
인증 방식이나 테이블 변경처럼 작업이 영향을 주는 범위를 먼저 정리하고 CLI·MCP·문서를 활용하는 방향을 안내합니다. 실제 앱과 프로젝트에 접근하려면 별도 설치와 권한이 필요합니다. 비밀키는 입력 자료에 넣지 않고 테스트 프로젝트로 시작하세요.
supabase 스킬로 이 앱의 이메일 로그인과 이미지 저장 기능을 설계해줘. 필요한 Auth·Storage 설정과 테이블, 권한 정책을 정리하고 구현 전에 확인할 질문을 알려줘.
받을 수 있는 결과설정·구현 계획과 점검 항목
Codex·Claude Code·Cursor 등 스킬 지원 에이전트가 필요해요. 일반 ChatGPT·Gemini 대화창에 설치되는 확장이 아닙니다. 스킬의 보조 파일과 연결 도구도 함께 확인하세요.
현재 사용 중인 스킬 지원 에이전트에 아래 요청을 붙여넣으세요. SKILL.md만 복사하면 보조 파일이 빠질 수 있어요.
https://github.com/supabase/agent-skills 에서 skills/supabase 스킬을 현재 에이전트의 스킬 폴더에 설치해줘. SKILL.md와 이 스킬이 참조하는 scripts·references·assets와 공통 파일을 함께 유지하고, 필요한 실행 환경과 추가 연결을 확인한 뒤 알려줘. 설치가 끝나면 supabase 스킬을 인식하는지 확인해줘.
“supabase 스킬을 사용해줘. 입력 자료: 프로젝트 구조·오류·사용할 Supabase 기능”처럼 요청하세요. 위의 예시를 내 자료에 맞게 바꿔도 좋아요.
예상 결과는 ‘설정·구현 계획과 점검 항목’입니다. 필요한 내용이 포함됐는지 확인하세요. 입력 자료의 사실·숫자와 결과를 대조하고, 부족한 부분을 이어서 요청하세요.
제작자 원본 2026-10-04 확인 · 설치 안내 2026-10-04 확인 · 실제 설치·실행 미검증
모델 사용 요금과 연결 앱 요금은 이용 중인 서비스의 정책을 따릅니다.
설치 안내 출처--- name: supabase description: "Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS); Supabase CLI or MCP server; schema changes, migrations, declarative schemas, security audits, Postgres extensions (pg_graphql, pg_cron, pg_vector); debugging and troubleshooting errors or unexpected behavior on Supabase projects (HTTP errors, Postgres errors, RLS surprises, permission denied, schema cache issues, timeouts, Edge Function crashes, Realtime drops, Storage failures) and reading or querying logs (Logs Explorer, ClickHouse)." metadata: author: supabase version: "0.1.2" --- # Supabase ## Core Principles **1. Supabase changes frequently — verify against changelog and current docs before implementing.** Do not rely on training data for Supabase features. Function signatures, config.toml settings, and API conventions change between versions. First, fetch `https://supabase.com/changelog.md` (a lightweight summary index — not a heavy pull), scan for `breaking-change` tags relevant to your task, and follow the linked page for any that apply. Then look up the relevant topic using the documentation access methods below. **2. Verify your work.** After implementing any fix, run a test query to confirm the change works. A fix without verification is incomplete. **3. Recover from errors, don't loop.** If an approach fails after 2-3 attempts, stop and reconsider. Try a different method, check documentation, inspect the error more carefully, and review relevant logs when available. Supabase issues are not always solved by retrying the same command, and the answer is not always in the logs, but logs are often worth checking before proceeding. **4. Exposing tables to the Data API:** Depending on the user's [Data API settings](https://supabase.com/dashboard/project/<ref>/integrations/data_api/settings), newly created tables may not be automatically exposed via the Data (REST) API. If this is the case, `anon` and `authenticated` roles will need to be explicitly granted access.--- name: supabase description: "Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS); Supabase CLI or MCP server; schema changes, migrations, declarative schemas, security audits, Postgres extensions (pg_graphql, pg_cron, pg_vector); debugging and troubleshooting errors or unexpected behavior on Supabase projects (HTTP errors, Postgres errors, RLS surprises, permission denied, schema cache issues, timeouts, Edge Function crashes, Realtime drops, Storage failures) and reading or querying logs (Logs Explorer, ClickHouse)." metadata: author: supabase version: "0.1.2" --- # Supabase ## Core Principles **1. Supabase changes frequently — verify against changelog and current docs before implementing.** Do not rely on training data for Supabase features. Function signatures, config.toml settings, and API conventions change between versions. First, fetch `https://supabase.com/changelog.md` (a lightweight summary index — not a heavy pull), scan for `breaking-change` tags relevant to your task, and follow the linked page for any that apply. Then look up the relevant topic using the documentation access methods below. **2. Verify your work.** After implementing any fix, run a test query to confirm the change works. A fix without verification is incomplete. **3. Recover from errors, don't loop.** If an approach fails after 2-3 attempts, stop and reconsider. Try a different method, check documentation, inspect the error more carefully, and review relevant logs when available. Supabase issues are not always solved by retrying the same command, and the answer is not always in the logs, but logs are often worth checking before proceeding. **4. Exposing tables to the Data API:** Depending on the user's [Data API settings](https://supabase.com/dashboard/project/<ref>/integrations/data_api/settings), newly created tables may not be automatically exposed via the Data (REST) API. If this is the case, `anon` and `authenticated` roles will need to be explicitly granted access. > Note that this is separate from RLS, which controls which _rows_ are visible once a table is accessible, not whether the table is accessible at all. When a user reports a SQL-created table is unexpectedly inaccessible, check their Data API settings and whether the roles have been granted access via explicit `GRANT` SQL. When granting public (`anon`/`authenticated`) access, always enable RLS too. See [Exposing a Table to the Data API](https://supabase.com/docs/guides/api/securing-your-api.md) for the full setup workflow. **5. RLS in exposed schemas.** Enable RLS on every table in any exposed schema, which includes `public` by default. This is critical in Supabase because tables in exposed schemas can be reachable through the Data API when the `anon`/`authenticated` roles have access (see [Exposing a Table to the Data API](https://supabase.com/docs/guides/api/securing-your-api.md)). For private schemas, prefer RLS as defense in depth. After enabling RLS, create policies that match the actual access model rather than defaulting every table to the same `auth.uid()` pattern. **6. Security checklist.** When working on any Supabase task that touches auth, RLS, views, storage, or user data, run through this checklist. These are Supabase-specific security traps that silently create vulnerabilities: - **Auth and session security** - **Never use `user_metadata` claims in JWT-based authorization decisions.** In Supabase, `raw_user_meta_data` is user-editable and can appear in `auth.jwt()`, so it is unsafe for RLS policies or any other authorization logic. Store authorization data in `raw_app_meta_data` / `app_metadata` instead. - **Deleting a user does not invalidate existing access tokens.** Sign out or revoke sessions first, keep JWT expiry short for sensitive apps, and for strict guarantees validate `session_id` against `auth.sessions` on sensitive operations. - **If you use `app_metadata` or `auth.jwt()` for authorization, remember JWT claims are not always fresh until the user's token is refreshed.** - **API key and client exposure** - **Never expose the `service_role` or secret key in public clients.** Prefer publishable keys for frontend code. Legacy `anon` keys are only for compatibility. In Next.js, any `NEXT_PUBLIC_` env var is sent to the browser. - **Use scoped personal access tokens for the Management API, CLI, and MCP server.** A classic personal access token carries the user's full account access, on every organization and project. For scripts, CI, and agents, have the user create a scoped token limited to the organizations, projects, and permissions the task needs. The [personal access tokens guide](https://supabase.com/docs/guides/platform/personal-access-tokens.md) lists the permission each Management API endpoint and MCP tool requires. Look permissions up there rather than guessing. - **RLS, views, and privileged database code** - **Views bypass RLS by default.** In Postgres 15 and above, use `CREATE VIEW ... WITH (security_invoker = true)`. In older versions of Postgres, protect your views by revoking access from the `anon` and `authenticated` roles, or by putting them in an unexposed schema. - **UPDATE requires a SELECT policy.** In Postgres RLS, an UPDATE needs to first SELECT the row. Without a SELECT policy, updates silently return 0 rows — no error, just no change. - **`auth.role()` is deprecated — use the `TO` clause instead.** Supabase has deprecated `auth.role()` in favour of specifying the target role directly on the policy with `TO authenticated` or `TO anon`. Beyond deprecation, `auth.role() = 'authenticated'` breaks silently when anonymous sign-ins are enabled, because anonymous users carry the `authenticated` Postgres role and pass the check regardless of whether the user is genuinely signed in. ```sql -- Deprecated (do not use) create policy "example" on table_name for select using ( auth.role() = 'authenticated' ); ``` - **`TO authenticated` alone is authentication without authorization (BOLA / IDOR).** Using `TO authenticated` only checks the role — it does not restrict which rows a user can access. The correct pattern combines `TO authenticated` with an ownership predicate in `USING`: ```sql create policy "example" on table_name for select to authenticated using ( (select auth.uid()) = user_id ); ``` - **UPDATE policies require both `USING` and `WITH CHECK`.** Without `WITH CHECK`, a user can reassign a row's `user_id` to another user: ```sql 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` functions bypass RLS.** A `SECURITY DEFINER` function runs with its creator's privileges — typically a role with `bypassrls` (e.g., `postgres`). Never add `SECURITY DEFINER` to resolve a permission error; it silently removes access control without fixing the underlying cause. Prefer `SECURITY INVOKER`. - **`SECURITY DEFINER` functions in `public` are callable by all roles.** Postgres grants `EXECUTE` to `PUBLIC` by default for every new function, so any `SECURITY DEFINER` function in `public` is a public API endpoint callable by `anon` and `authenticated` (which inherit from `PUBLIC`) without any additional grant. When `SECURITY DEFINER` is genuinely needed (e.g., bypassing RLS on an internal lookup table), keep the function in a non-exposed schema, always include an `auth.uid()` check in the function body, and run `supabase db advisors` after making changes. - **Storage access control** - **Storage upsert requires INSERT + SELECT + UPDATE.** Granting only INSERT allows new uploads but file replacement (upsert) silently fails. You need all three. - **Dependency and supply-chain security** - **Always pin package versions and commit lockfiles** when installing Supabase packages (`supabase-js`, `@supabase/ssr`, `supabase-py`, etc.). See the [npm security guide](https://supabase.com/docs/guides/security/npm-security.md) for the full checklist. For any security concern not covered above, fetch the Supabase product security index: `https://supabase.com/docs/guides/security/product-security.md` ## Supabase CLI Always discover commands via `--help` — never guess. The CLI structure changes between versions. ```bash supabase --help # All top-level commands supabase <group> --help # Subcommands (e.g., supabase db --help) supabase <group> <command> --help # Flags for a specific command ``` **Supabase CLI Known gotchas:** - `supabase db query` requires **CLI v2.79.0+** → use MCP `execute_sql` or `psql` as fallback - `supabase db advisors` requires **CLI v2.81.3+** → use MCP `get_advisors` as fallback - The browser flow of `supabase login` creates a classic token with full account access. In CI, set `SUPABASE_ACCESS_TOKEN` to a scoped personal access token instead. It takes precedence over any saved login. Commands that connect with the database password (`--password` or `SUPABASE_DB_PASSWORD`, for example `supabase db push`) aren't limited by the token's permissions. - In imperative migration projects, create new hand-authored migration files with `supabase migration new <name>` first. Never invent a migration filename or rely on memory for the expected format. Declarative schema projects generate migrations from `supabase/schemas/`; see "Making and Committing Schema Changes" below. **Version check and upgrade:** Run `supabase --version` to check. For CLI changelogs and version-specific features, consult the [CLI documentation](https://supabase.com/docs/reference/cli/introduction) or [GitHub releases](https://github.com/supabase/cli/releases). ## Supabase MCP Server For setup instructions, server URL, and configuration, see the [MCP setup guide](https://supabase.com/docs/guides/getting-started/mcp). **Troubleshooting connection issues** — follow these steps in order: 1. **Check if the server is reachable:** `curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp` A `401` is expected (no token) and means the server is up. Timeout or "connection refused" means it may be down. 2. **Check `.mcp.json` configuration:** Verify the project root has a valid `.mcp.json` with the correct server URL. If missing, create one pointing to `https://mcp.supabase.com/mcp`. 3. **Authenticate the MCP server:** If the server is reachable and `.mcp.json` is correct but tools aren't visible, the user needs to authenticate. The Supabase MCP server uses OAuth 2.1 — tell the user to trigger the auth flow in their agent, complete it in the browser, and reload the session. In CI or other environments where the browser flow can't run, pass a scoped personal access token in the `Authorization: Bearer` header instead. 4. **Check scoped token permissions:** If a tool fails with "You do not have permission to perform this action" while using a scoped personal access token, the token lacks that tool's permission or the project is outside the token's scope. Check the tool's required permission in the [personal access tokens guide](https://supabase.com/docs/guides/platform/personal-access-tokens.md#mcp-tools). ## Supabase Documentation Before implementing any Supabase feature, find the relevant documentation. Use these methods in priority order: 1. **MCP `search_docs` tool** (preferred — returns relevant snippets directly) 2. **Fetch docs pages as markdown** — any docs page can be fetched by appending `.md` to the URL path. 3. **Web search** for Supabase-specific topics when you don't know which page to look at. ## Making and Committing Schema Changes First decide which schema workflow the project uses. ### Option A: Declarative schemas Use this when `supabase/schemas/` exists or `config.toml` sets `schema_paths`. Edit the desired schema state in those files, then generate and review the migration. Do not start by hand-writing a migration. See the [Declarative database schemas guide](https://supabase.com/docs/guides/local-development/declarative-database-schemas). ### Option B: Imperative migrations Use this when the project does not use declarative schemas. **To make schema changes, use `execute_sql` (MCP) or `supabase db query` (CLI).** These run SQL directly on the database without creating migration history entries, so you can iterate freely and generate a clean migration when ready. Do NOT use `apply_migration` to change a local database schema — it writes a migration history entry on every call, which means you can't iterate, and `supabase db diff` / `supabase db pull` will produce empty or conflicting diffs. If you use it, you'll be stuck with whatever SQL you passed on the first try. **When ready to commit** your changes to a migration file: 1. **Run advisors** → `supabase db advisors` (CLI v2.81.3+) or MCP `get_advisors`. Fix any issues. 2. **Review the Security Checklist above** if your changes involve views, functions, triggers, or storage. 3. **Generate the migration** → `supabase db pull <descriptive-name> --local --yes` 4. **Verify** → `supabase migration list --local` ## Debugging When you get an error on a Supabase-related request, for example an error code from the Supabase REST API, Postgres database, or PostgREST, an empty result, getting blocked by RLS unexpectedly, or an error from a Supabase service like Auth, Realtime, Edge Functions, or Storage, you **must** fetch Supabase's [Monitoring and Debugging](https://supabase.com/docs/guides/monitoring-and-debugging.md) documentation before diagnosing or proposing a fix, rather than working from memory. The same docs also cover performance optimizations, such as slow queries and missing indexes. ## Reference Guides - **Skill Feedback** → [references/skill-feedback.md](references/skill-feedback.md) **MUST read when** the user reports that this skill gave incorrect guidance or is missing information.
Original skill: supabase/agent-skills/skills/supabase/SKILL.md Source: https://github.com/supabase/agent-skills/blob/c9be0e931b7930f7d02126d04774d904c381e7d7/skills/supabase/SKILL.md License: MIT MIT License Copyright (c) 2026 Supabase Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
SKILL.md 본문입니다. 원문에서 참조하는 스크립트·보조 파일은 원본 패키지에 포함되어 있습니다.