supabase-postgres-best-practices (supabase/agent-skills)

Name: supabase-postgres-best-practices (supabase/agent-skills) review
Item: supabase-postgres-best-practices (supabase/agent-skills)
Rating: 24.4
Author: Agent Skills

Orienta o design de esquemas Postgres, migrações, RLS, índices e desempenho de consultas com Supabase.

Boas práticas de Postgres no Supabase: nenhum ganho sobre o Codex puro em tarefas de schema, revisão e índices (4.48 vs 4.54)

SituacionalSeguro

Codex CLI · gpt-6-astra

24.4 / 30

Ganho sobre sem skill: -0.06 · Situacional · 18 execuções

Situacional: o ganho -0.06 está abaixo de +1.0. Para ser recomendado, é preciso total de 22/30, qualidade da saída de 3.5 e ganho de +1.0.

SOTA

Aprovado

Testado com Codex.

Cobre Codex, Claude Code

Codex CLI 0.166 (nível SOTA): 18 execuções avaliadas. Uma aprovação aqui também vale para o Claude Code pela nossa regra de níveis; ela não diz nada sobre o segundo nível.

Notas

Cada dimensão vai de 0 a 5, e as seis somam o total de 30. 5 é melhor em todas as dimensões. Custo 5 significa barato e rápido. Instalação 5 significa fácil.

Confiabilidade do acionamento: 5.0
Ganho sobre sem skill: 1.9
Qualidade da saída: 4.5
Custo de tokens e tempo: 4.0
Instalação e portabilidade: 4.0
Segurança: 5.0

Revisão de segurança

Seguro

Varredura estática: 0 CRÍTICO / 4 ALTO / 0 MÉDIO. Revisão manual: seguro para executar em sandbox sem rede (achados do scanner explicados). Uma varredura limpa não prova que a skill é segura.

Instalar

npx skills@latest add supabase/agent-skills --skill supabase-postgres-best-practices

Fonte

Commit fixado: c9be0e931b7930f7d02126d04774d904c381e7d7

Testado: 2026-11-02

O que testamos

Schema multi-tenant com RLS — Escreva schema.sql para um rastreador de projetos multi-tenant em Supabase (Postgres): organizations, memberships (um usuário do auth do Supabase pertence a uma organization com um role), projects, tasks (assignee, status, due date) e comments em tasks. Um usuário só pode ver e alterar…
Revisar um schema, queries e um worker — Revise schema.sql, queries.sql e worker.py (um app de suporte a tickets em Supabase/Postgres). Liste os problemas, do mais sério para o menos, cada um com a correção. Não altere nenhum arquivo. Escreva a lista na sua resposta final.
Índices para três queries lentas — As três queries em slow_queries.md estão lentas na tabela de schema.sql (120M linhas). Escreva migration.sql com as mudanças de índice que você faria (e nada mais), e notes.md (no máximo 120 palavras) dizendo qual índice atende qual query e qualquer ressalva. (Sem banco de dados…

Prós

A skill foi acionada sem ser nomeada: o arquivo da skill foi lido em 6/6 execuções de tratamento.

Contras

Nenhum ganho mensurável em relação ao grupo sem skill (-0.06, dentro do ruído).
Um prompt de uma frase marcou 4.75, contra 4.48 com a skill (-0.27).
n=2 por tarefa por braço; diferenças abaixo de cerca de 1 ponto são ruído.

Avaliação

Codex CLI 0.166 (gpt-6-astra, raciocínio baixo) em uma máquina de teste Mac, com um projeto temporário novo e HOME/TMPDIR/caches temporários a cada execução, skill instalada (tratamento) ou ausente (grupo de controle) ou ausente com o requisito central da skill comprimido em uma frase anexada ao prompt (grupo prompt de uma frase), 2 execuções por grupo por tarefa, rede desligada, gravações em /tmp bloqueadas. Os prompts nunca mencionam a skill (exceto pelo texto indicado abaixo). Três tarefas: escrever um schema Supabase multi-tenant com RLS (checagens: RLS em toda tabela, auth.uid() envolvido em um select, toda chave estrangeira indexada, timestamptz, chaves identity ou uuid, constraints, nomes em minúsculas), revisar um schema, queries e worker com defeitos em busca de 11 problemas plantados, e escrever migrations de índice mais notas para três queries lentas em uma tabela de 120M linhas (índice composto, índice parcial, CONCURRENTLY, no máximo 4 índices).

Comparação entre os braços

Braço	Nota média (0-5)	Tokens por execução
Sem a skill	4.54	77k
Prompt de uma frase	4.75	80k
Com a skill	4.48	93k

Medido com Codex CLI em 18 execuções, com pontuação por verificações baseadas em regras e sem juiz LLM. Total 24.4 / 30, veredito Situacional.

Veredito: Situacional (24.4 / 30). Fonte: supabase/agent-skills, skills/supabase-postgres-best-practices, fixada no commit c9be0e9. Instalação: npx skills@latest add supabase/agent-skills --skill supabase-postgres-best-practices. Licença: MIT (LICENSE do repositório).

O que é

A skill supabase-postgres-best-practices, de supabase/agent-skills, traz orientação de desempenho e schema do Postgres para projetos Supabase em cerca de 35 arquivos de referência (desempenho de consultas e índices, gestão de conexões, segurança e RLS, design de schema, concorrência e locking, padrões de acesso a dados, monitoramento), com um SKILL.md de 440 palavras que os indexa. Apenas Markdown, sem scripts.

Como testamos

Codex CLI 0.166 (gpt-6-astra, raciocínio baixo) em uma máquina de teste Mac, um projeto temporário novo e HOME/TMPDIR/caches temporários a cada execução, skill instalada (tratamento) ou ausente (controle) ou ausente com o requisito central da skill comprimido em uma frase anexada ao prompt (grupo de uma frase), 2 execuções por grupo por tarefa, rede desligada, gravações em /tmp bloqueadas. Os prompts nunca mencionam a skill (exceto pelo texto indicado abaixo).

Três tarefas: escrever um schema Supabase multi-inquilino com RLS (verificações: RLS em toda tabela, auth.uid() envolvido em um select, toda chave estrangeira indexada, timestamptz, chaves identity ou uuid, restrições, nomes em minúsculas), revisar um schema/consultas/worker com defeito em busca de 11 problemas plantados, e escrever migrações de índice mais notas para três consultas lentas em uma tabela de 120M linhas (índice composto, índice parcial, CONCURRENTLY, no máximo 4 índices).

Schema multi-inquilino com RLS — Escreva schema.sql para um rastreador de projetos multi-inquilino em Supabase (Postgres): organizações, associações (um usuário de autenticação do Supabase pertence a uma organização com um papel), projetos, tarefas (responsável, status, prazo) e comentários nas tarefas. Um usuário só pode ver e alter…
Revisar um schema, consultas e um worker — Revise schema.sql, queries.sql e worker.py (um app de tickets de suporte em Supabase/Postgres). Liste os problemas, do mais grave para o menos grave, cada um com a correção. Não altere nenhum arquivo. Escreva a lista na sua resposta final.
Índices para três consultas lentas — As três consultas em slow_queries.md estão lentas na tabela de schema.sql (120M linhas). Escreva migration.sql com as mudanças de índice que você faria (e nada mais), e notes.md (no máximo 120 palavras) dizendo qual índice atende qual consulta e qualquer ressalva. (Sem banco de dados…

A pontuação é programática (testes ocultos / detecção de problemas plantados / verificações de restrições / renderização+OCR quando aplicável), 0–5 por execução. Nenhum juiz LLM decidiu qualquer pontuação.

Resultados

O prompt de uma frase dado ao terceiro grupo: "Aplique as boas práticas do Postgres: indexe toda chave estrangeira e toda coluna usada em WHERE/ORDER BY (índices compostos com colunas de igualdade primeiro, índices parciais para status raros, CREATE INDEX CONCURRENTLY em tabelas grandes), ative RLS em toda tabela exposta e envolva auth.uid() em (select auth.uid()), use timestamptz, chaves identity ou uuid e nomes snake_case em minúsculas, pagine com keyset e não offset, e mantenha as transações curtas (sem chamadas externas dentro)."

Tarefa	Pontuação do controle	Uma frase	Com a skill	Tokens do controle	Tokens de uma frase	Tokens com a skill	Skill lida
t1-schema	4.52	4.79	4.16	104k	121k	124k	2/2
t2-review	4.09	4.46	4.28	64k	56k	70k	2/2
t3-indexes	5.0	5.0	5.0	60k	61k	84k	2/2

Pontuação média: 4.54 sem a skill vs 4.48 com ela (delta -0.06). Tokens por execução: 77k vs 93k (1.21x); tempo 78s vs 73s. Grupo de uma frase: 4.75 (ganho da skill sobre o prompt de uma frase: -0.27; ganho do próprio prompt de uma frase sobre nenhuma skill: +0.21); tokens do prompt de uma frase: 80k por execução, então a skill custa 1.16x o prompt de uma frase.

O que aconteceu

Nenhuma diferença: média 4.54 controle, 4.75 uma frase, 4.48 skill. A skill fica em -0.06 contra o controle com 93k tokens por execução contra 77k (1.2x).
A tarefa de índices é resolvida por todos os grupos em todas as execuções (as seis verificações de índice passam 6/6 em todos os grupos, incluindo CONCURRENTLY e manter no máximo 4 índices): o Codex sozinho já conhece esses fundamentos.
Na tarefa de schema, todos os grupos indexaram todas as chaves estrangeiras, ativaram RLS em todas as tabelas e usaram chaves uuid/identity. Envolver auth.uid() em (select auth.uid()) foi feito só em parte das políticas em todos os grupos: 3 de 5-6 ocorrências nas execuções de controle e com a skill, 5 de 5 em uma execução de uma frase. O grupo de uma frase foi o melhor nessa regra (1.6 de 2 contra 1.1 do controle e da skill). Uma execução com a skill usou uma coluna timestamp simples (3.86), a menor pontuação entre todas as execuções.
Na tarefa de revisão, todos os grupos encontraram 8-9 dos 11 problemas plantados (1.5-1.7 de 2 verificações); a skill não encontrou mais.
O teste foi reexecutado uma vez para a tarefa de índices: o primeiro lote não deu arquivos de entrada por causa de um erro de especificação (a lista de fixtures estava vazia), então todas as 6 execuções disseram que os arquivos estavam faltando. Corrigimos a especificação e reexecutamos essas 6 execuções; as anteriores não são contadas.

Pontuações por dimensão

Dimensão	Pontuação	Por quê
1_output_quality	4.48	Pontuação média 4.48/5 com a skill (verificações programáticas, veja a tabela por tarefa).
2_lift_vs_no_skill	1.94	-0.06 pontos vs 4.54 sem a skill (n=2 por tarefa; menos de ~1 ponto é ruído).
3_trigger	5.0	Arquivo da skill lido em 6/6 execuções com a skill.
4_instructions_portability	4	Arquivos de regras em Markdown simples; segue o layout aberto de skills.
5_efficiency	4	1.21x tokens (93k vs 77k por execução) e 0.93x tempo (73s vs 78s).
6_safety_hygiene	5	Apenas Markdown; os quatro hits HIGH do scanner são o nome de tabela `public.profiles` batendo com um padrão `.profile`.

Limites deste teste

Problemas de manual em arquivos pequenos; pontos específicos do Supabase além de RLS (pool de conexões, Realtime, storage) não foram testados.
Os itens são comparados por regex, então uma correção com outra redação conta como ausente.
As regras da skill sobre locking, monitoramento e padrões de acesso a dados não foram exercitadas.
n = 2 por grupo por tarefa: diferenças abaixo de cerca de 1 ponto são ruído.
A pontuação baseada em regras mede o que as verificações conseguem ver; não julga bom gosto nem se o resultado é o melhor possível.

Segurança

Veja security.md. Scan: 0 CRITICAL / 4 HIGH / 0 MEDIUM. Veredito: seguro para executar (sandbox sem rede). Um scan limpo não prova que uma skill é segura.

Conclusão

Em tarefas de design de schema, revisão e índices, o Codex sozinho já aplica as práticas que esta skill lista, e a skill não melhorou a pontuação, acrescentando cerca de 20% de tokens. Ainda pode ser uma referência útil para tópicos menos comuns do Supabase que estes testes não tocaram.

Transcrição

Log de execuções: supabase-postgres-best-practices (Codex CLI, network off, per-run temp HOME/TMPDIR, one row per graded run.)
Colunas: tarefa, grupo-execução, nota (0-5), tokens, segundos, verificações aprovadas, arquivos da skill abertos pelo agente.

t1-schema control-1: nota 4.57, tokens 105331, s 124.5, verificações 6/7, nada aberto
t1-schema control-2: nota 4.46, tokens 104624, s 130.1, verificações 6/7, nada aberto
t1-schema oneliner-1: nota 5.0, tokens 111153, s 140.4, verificações 7/7, nada aberto
t1-schema oneliner-2: nota 4.57, tokens 132693, s 145.1, verificações 6/7, nada aberto
t1-schema treatment-1: nota 3.86, tokens 123861, s 108.3, verificações 5/7, abriu supabase-postgres-best-practices
t1-schema treatment-2: nota 4.46, tokens 124377, s 129.6, verificações 6/7, abriu supabase-postgres-best-practices
t2-review control-1: nota 4.27, tokens 64780, s 65.4, verificações 2/2, nada aberto
t2-review control-2: nota 3.91, tokens 64695, s 71.5, verificações 2/2, nada aberto
t2-review oneliner-1: nota 3.91, tokens 45381, s 57.3, verificações 2/2, nada aberto

18 execuções, 3 artefatos

Resultado de exemplo

SOTA · With the skill: schema.sql (t1-schema, run 1, Codex)

-- Fresh Supabase database: run once as postgres (trusted BYPASSRLS owner). -- Members manage tenant content; admins also manage settings and memberships. -- service_role bypasses RLS: keep its credentials exclusively on the backend. begin; create schema if not exists private; revoke all on schema private from public, anon; grant usage on schema private to authenticated; -- Keep private out of the Data API's exposed schemas. create table public.organizations ( id uuid primary key default gen_random_uuid(), name text not null check (length(btrim(name)) between 1 and 200), created_at timestamptz not null default now(), updated_at timestamptz not null default now() ); create table public.memberships ( organization_id uuid not null references public.organizations(id) on delete cascade, user_id uuid not null references auth.users(id) on delete cascade, role text not null default 'member' check (role in ('admin', 'member')), created_at timestamptz not null default now(), primary key (organization_id, user_id) ); -- Reverse lookup for the caller's tenants, RLS, and auth user deletion. create index memberships_user_idx on public.memberships (user_id, organization_id) include (role); create table public.projects ( id uuid primary key default gen_random_uuid(), organization_id uuid not null references public.organizations(id) on delete cascade, name text not null check (length(btrim(name)) between 1 and 200), description text not null default '', created_at timestamptz not null default now(), updated_at timestamptz not null default now(), unique (organization_id, id) ); create index projects_list_idx on public.projects (organization_id, created_at desc, id desc); create table public.tasks ( id uuid primary key default gen_random_uuid(), organization_id uuid not null references public.organizations(id) on delete cascade, project_id uuid not null, title text not null check (length(btrim(title)) between 1 and 500), description text not null default '', assignee_id uuid, status text not null default 'todo' check (status in ('todo', 'in_progress', 'done', 'cancelled')), due_date date, created_at timestamptz not null default now(), updated_at timestamptz not null default now(), unique (organization_id, id), foreign key (organization_id, project_id) references public.projects (organization_id, id) on delete cascade, -- Unassign tasks before deleting a membership/auth user. Deferred checking -- permits deleting an entire organization and all its children atomically. foreign key (organization_id, assignee_id) references public.memberships (organization_id, user_id) on delete no action deferrable initially deferred ); create index tasks_project_list_idx on public.tasks (organization_id, project_id, created_at desc, id desc); create index tasks_board_idx on public.tasks (organization_id, project_id, status, created_at desc, id desc); create index tasks_assignee_idx on public.tasks (organization_id, assignee_id, status, due_date, id) where assignee_id is not null; create index tasks_open_due_idx on public.tasks (organization_id, due_date, id) where status in ('todo', 'in_progress') [... excerpt: first 3200 of 11674 characters]

Ver o Pro