Communitygithub.com

Jo5i4swastaken/Skills-Locker

用于执行任何涉及 Supabase 的任务。触发条件:Supabase 产品(数据库、认证、边缘函数、实时、存储、向量、定时任务、队列);客户端库及 SSR 集成(supabase-js、@supabase/ssr)在 Next.js、React、SvelteKit、Astro、Remix 中;认证问题(登录、登出、会话、JWT、Cookies、getSession、getUser、getClaims、RLS);Supabase CLI 或 MCP 服务器;架构变更、迁移、安全审计、Postgres 扩展(pg_graphql、pg_cron、pg_vector)。

Skills-Locker 是什么?

本技能专门用于处理与 Supabase 相关的所有任务,涵盖了其核心产品(如数据库、认证、边缘函数、实时、存储、向量、定时任务和队列)以及与之配合的客户端库和 SSR 集成。它提供了一套关于 Supabase 工作方式的核心原则,包括验证变更、处理错误、确保数据 API 的安全性以及实施严格的行级安全(RLS)策略。技能还详细说明了 Supabase CLI 的使用技巧和 MCP 服务器的故障排除流程。此外,它提供了实施架构变更的推荐工作流,强调先用 `execute_sql` 或 `supabase db query` 直接迭代 SQL,最后通过 `supabase db pull` 生成干净的迁移文件。该技能适用于所有主要前端框架(如 Next.js、React、SvelteKit、Astro 和 Remix),并通过 Markdown 文档统一提供指导。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Supabase

核心原则

1. Supabase 变更频繁——在实施前务必对照变更日志和当前文档进行验证。 不要依赖训练数据中的 Supabase 功能。函数签名、config.toml 设置和 API 约定会随版本变化。

首先,获取 https://supabase.com/changelog.md(一个轻量级摘要索引——非重量级拉取),扫描与您的任务相关的 breaking-change 标签,并按照链接页面处理任何适用的变更。然后使用下面的文档访问方法查找相关主题。

2. 验证您的工作。 完成任何修复后,运行测试查询以确认更改有效。未经验证的修复是不完整的。

3. 从错误中恢复,不要循环。 如果一种方法在尝试 2-3 次后仍失败,请停下来重新考虑。尝试不同的方法,检查文档,更仔细地检查错误,并在可用时查看相关日志。Supabase 问题并非总能通过重试相同命令解决,答案也并不总是在日志中,但在继续之前检查日志通常值得一试。

4. 向数据 API 公开表: 取决于用户的数据 API 设置,新创建的表可能不会通过数据 (REST) API 自动公开。如果是这种情况,则需要显式授予 anon 和 authenticated 角色访问权限。

注意,这不同于 RLS,RLS 控制的是表可访问后哪些_行_可见,而不是表是否可访问。

当用户报告通过 SQL 创建的表意外不可访问时,请检查其数据 API 设置以及是否通过显式的 GRANT SQL 授予了角色访问权限。在授予公共(anon/authenticated)访问权限时,也要启用 RLS。有关完整的设置工作流,请参阅向数据 API 公开表。

5. 公开架构中的 RLS。 在任何公开架构(默认包括 public)的每个表上启用 RLS。这在 Supabase 中至关重要,因为当 anon/authenticated 角色拥有访问权限时,公开架构中的表可以通过数据 API 访问(请参阅向数据 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 是预期行为(无令牌)且表示服务器已启动。超时或“连接被拒绝”表示服务器可能已关闭。

  2. 检查 .mcp.json 配置: 验证项目根目录存在一个有效的 .mcp.json 文件,其中包含正确的服务器 URL。如果缺失,请创建一个指向 https://mcp.supabase.com/mcp 的文件。

  3. 认证 MCP 服务器: 如果服务器可达且 .mcp.json 正确,但工具不可见,则用户需要进行身份验证。Supabase MCP 服务器使用 OAuth 2.1 — 告诉用户在其代理中触发认证流程,在浏览器中完成,然后重新加载会话。

Supabase 文档

在实现任何 Supabase 功能之前,找到相关的文档。按优先顺序使用以下方法:

  1. MCP search_docs 工具(首选——直接返回相关代码片段)
  2. 以 Markdown 格式获取文档页面——任何文档页面都可以通过在 URL 路径后附加 .md 来获取。
  3. 网页搜索针对 Supabase 特定主题,当您不知道要查看哪个页面时。

制作和提交架构变更

要进行架构变更,请使用 execute_sql(MCP)或 supabase db query(CLI)。 这些命令直接在数据库上运行 SQL,而不会创建迁移历史记录条目,因此您可以自由迭代,并在准备就绪时生成干净的迁移。

不要使用 apply_migration 来更改本地数据库架构——它会在每次调用时写入迁移历史记录条目,这意味着您无法迭代,并且 supabase db diff / supabase db pull 会产生空或冲突的差异。如果您使用它,您将受困于第一次尝试时传递的任何 SQL。

准备提交您的更改为迁移文件时:

  1. 运行 advisors → supabase db advisors(CLI v2.81.3+)或 MCP get_advisors。修复所有问题。
  2. 查看上面的安全检查清单,如果您的更改涉及视图、函数、触发器或存储。
  3. 生成迁移 → supabase db pull <descriptive-name> --local --yes
  4. 验证 → supabase migration list --local

参考指南

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.

相关技能