opencode-skills-collection 3.1.12 → 3.1.14

package/bundled-skills/styleseed-design-review/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: styleseed-design-review
+description: Reviews UI/frontend code and tells you exactly why it "looks AI-generated" — then how to fix it. Use it when a React/Tailwind/HTML interface looks off, generic, or unfinished, when you want a design score before shipping, or when asked to make UI look more professional, polished, or...
+risk: unknown
+source: https://github.com/bitjaru/styleseed/tree/main/skills/styleseed-design-review
+source_repo: bitjaru/styleseed
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/bitjaru/styleseed/blob/main/LICENSE
+---
+
+# StyleSeed Design Review
+
+## Overview
+
+A UI reads as "AI-generated" not because the components are ugly, but because the **parts
+don't agree with each other** — mixed corner radii, three accent colors, pure-black text,
+no hierarchy, missing states, robotic copy. This skill reviews a UI file (or a whole
+directory) against a concrete design rubric, scores it 0–100, and returns a prioritized
+fix list. It reviews and recommends; it never edits or deletes without you asking.
+
+Full rule set (74 rules) and components: https://github.com/bitjaru/styleseed
+
+## When to use
+
+- A React / Tailwind / HTML UI "looks off," generic, or unfinished and you can't say why.
+- You want a design score / pre-ship check.
+- The user asks to make UI "look professional / polished / designed, not AI-generated."
+- After generating UI, to verify it before shipping.
+
+## How to review
+
+Read the file(s). Score these **seven categories** (total 100); start each at full marks
+and subtract for violations you can cite by line. Be specific and evidence-based.
+
+### 1. Coherence — 20  (the #1 "AI-generated" tell)
+One choice per axis, applied everywhere. Deduct for each **mixed** axis:
+- mixed corner radii — e.g. a sharp card with pill buttons (−6)
+- two or more accent colors used for emphasis (−5)
+- **emoji used as UI icons** (🚗🧺⭐ as list/nav/status/category markers) — injects many uncontrolled hues; use one line-icon set in currentColor (−6)
+- mixed shadow languages / light directions (−3)
+- mixed icon families, fill modes, or stroke weights (−3)
+- inconsistent control heights (buttons/inputs differ) (−3)
+
+### 2. Color discipline — 16
+- pure black (`#000` / `text-black`) text — the refined black is ~`#2A2A2A` (−4 each, cap −8)
+- hardcoded hex where a semantic token exists (−2 each, cap −6)
+- **a normal / OK / default ("보통") state shown in a status color** instead of neutral grey (−4)
+- **status color on most/every row** (no severity hierarchy — color should mark the minority that needs attention) (−4)
+- **decorative hues** — gold stars, rainbow category dots, a different color per card — instead of accent/grey (−3)
+- status conveyed by color alone, no icon/text (−4)
+- contrast below WCAG AA (4.5:1 body, 3:1 large/UI) (−6)
+
+### 3. Hierarchy & typography — 16
+- number and its unit not ~2:1 (48px number / 24px unit) (−4)
+- everything the same size and weight, no clear primary (−5)
+- arbitrary font sizes; no scale (−4)
+- wrong line-height (loose on display, cramped on body) (−3)
+
+### 4. Layout & spacing — 12
+- content on a bare page background, not in cards (−6)
+- off-grid spacing (7/13/19px instead of an 8px scale) (−3)
+- the gap *around* a group not larger than the gap *inside* it (−3)
+- the same section type repeated in a row (−4)
+
+### 5. States — 12
+- missing empty / loading / error state on a data surface (−5 each, cap −10)
+- empty state with no next action; error that blames instead of helping (−4)
+
+### 6. UX writing — 12
+- buttons that don't name the action ("Submit" / "OK" instead of "Send $2,400") (−4)
+- error copy that blames or uses system-speak ("Invalid input", "An error occurred") (−4)
+- two terms for one concept (delete vs remove); filler words ("please", "successfully") (−2)
+
+### 7. Motion & polish — 12
+- ad-hoc fades instead of one consistent, named feel (−3)
+- motion that delays content or blocks an action (−4)
+- no `prefers-reduced-motion` handling on custom motion (−3)
+- a single hard black shadow instead of a layered, low-opacity, tinted one (−2)
+
+Clamp each category at 0; sum to a total. Bands: 90+ A · 80–89 B · 70–79 C · 60–69 D · <60 F.
+
+## Output format
+
+```
+## Design Score: 72 / 100   (src/Dashboard.tsx)   C
+
+Coherence            13/20   sharp cards (l.22) + pill buttons (l.48); 3 accent hues
+Color discipline     12/16   #000 headings (l.12, 40)
+Hierarchy & type     15/16   number/unit 1:1 on hero (l.18)
+Layout & spacing     10/12   two identical KPI rows (l.22-31)
+States                7/12   no empty/loading state on the orders list
+UX writing            8/12   "Submit" button (l.55); "Invalid input" (l.61)
+Motion & polish      10/12   one hard black shadow (l.22)
+
+### Fix first (highest score gain)
+1. Unify radius (pick soft 8–12px) + collapse to one accent   → +11 coherence/color
+2. Add empty + loading states to the orders list              → +7  states
+3. Rename "Submit" → "Send $2,400"; "Invalid input" → "Check the card number" → +6 copy
+
+Re-score after: ~90 / 100.
+```
+
+## Rules
+
+- Review from real evidence (cite line numbers); never guess.
+- Order the fix list by **score gain**, not severity alone — fastest path to a better number.
+- For a directory: one-line score per file, then the lowest file's full breakdown.
+- **Don't auto-edit.** This skill measures and recommends. Apply fixes only when asked.
+- Use it as a **quality gate**: review right after generating UI, apply the fix list, and
+  re-review until the score clears ~80 *before showing the user* — no first-draft, incoherent
+  UI (rainbow status lists, emoji icons, two accents, missing states) should reach them. The
+  bar is a floor, not a ceiling: clear 80 and ship; don't chase 100 to delay.
+
+---
+
+Based on **StyleSeed** — an open-source (MIT) design engine that gives Claude Code, Cursor,
+and Codex design judgment so AI-built UI stops looking generated. Full 74-rule reference,
+components, brand skins, and motion: https://github.com/bitjaru/styleseed
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/supabase/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## [0.1.4](https://github.com/supabase/agent-skills/compare/v0.1.3...v0.1.4) (2026-06-05)
+
+
+### Features
+
+* add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
+* add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
+* instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+* update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))
+
+## [0.1.3](https://github.com/supabase/agent-skills/compare/v0.1.2...v0.1.3) (2026-06-02)
+
+
+### Features
+
+* add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
+* add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
+* instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+* update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))

package/bundled-skills/supabase/SKILL.md

@@ -0,0 +1,149 @@
+---
+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,..."
+risk: unknown
+source: https://github.com/supabase/agent-skills/tree/main/skills/supabase
+source_repo: supabase/agent-skills
+source_type: official
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/supabase/agent-skills/blob/main/LICENSE
+---
+
+# Supabase
+## When to Use
+
+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,...
+
+
+## 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.
+
+- **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
+- When you need a new migration SQL file, **always** create it with `supabase migration new <name>` first. Never invent a migration filename or rely on memory for the expected format.
+
+**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.
+
+## 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
+
+**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`
+
+## 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.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream product or API scope.
+- Verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes.
+- Do not treat generated examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/supabase/assets/feedback-issue-template.md

@@ -0,0 +1,17 @@
+## What happened
+
+**Task:** <!-- e.g., "Set up MFA on patient records" -->
+
+**Skill said:** <!-- e.g., "Use auth.jwt()->'app_metadata' in the RLS policy" -->
+
+**Expected:** <!-- e.g., "The function also needs SECURITY DEFINER + grant to supabase_auth_admin" -->
+
+## Source
+
+**File:** <!-- e.g., references/security-model.md -->
+
+**Section:** <!-- e.g., "Trust Boundaries > user_metadata vs app_metadata" -->
+
+## Fix suggestion
+
+<!-- Leave blank if unsure -->

package/bundled-skills/supabase/references/skill-feedback.md

@@ -0,0 +1,17 @@
+# Skill Feedback
+
+Use this when the user reports that the skill gave incorrect guidance, is missing information, or could be improved. This is about the skill (agent instructions), not about Supabase the product.
+
+## Steps
+
+1. **Ask permission** — Ask the user if they'd like to submit feedback to the skill maintainers. If they decline, move on.
+
+2. **Draft the issue** — Use the template at [assets/feedback-issue-template.md](../assets/feedback-issue-template.md) to structure the feedback. Fill in the fields based on the conversation. Always identify which specific reference file and section caused the problem.
+
+3. **Submit** — Create a GitHub Issue on the `supabase/agent-skills` repository using the draft as the issue body. The title must follow this format: `user-feedback: <summary of the problem>`.
+
+4. **Share the result** — Share the issue URL with the user after submission. If submission fails, give the user this link to create the issue manually:
+
+```
+https://github.com/supabase/agent-skills/issues/new
+```

package/bundled-skills/supabase-postgres-best-practices/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [1.3.0](https://github.com/supabase/agent-skills/compare/v1.2.0...v1.3.0) (2026-06-05)
+
+
+### Features
+
+* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+
+## [1.2.0](https://github.com/supabase/agent-skills/compare/v1.1.1...v1.2.0) (2026-06-02)
+
+
+### Features
+
+* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))

package/bundled-skills/supabase-postgres-best-practices/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: supabase-postgres-best-practices
+description: Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
+risk: unknown
+source: https://github.com/supabase/agent-skills/tree/main/skills/supabase-postgres-best-practices
+source_repo: supabase/agent-skills
+source_type: official
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/supabase/agent-skills/blob/main/LICENSE
+---
+
+# Supabase Postgres Best Practices
+## When to Use
+
+Use this skill when you need postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
+
+
+Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing SQL queries or designing schemas
+- Implementing indexes or query optimization
+- Reviewing database performance issues
+- Configuring connection pooling or scaling
+- Optimizing for Postgres-specific features
+- Working with Row-Level Security (RLS)
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Query Performance | CRITICAL | `query-` |
+| 2 | Connection Management | CRITICAL | `conn-` |
+| 3 | Security & RLS | CRITICAL | `security-` |
+| 4 | Schema Design | HIGH | `schema-` |
+| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
+| 6 | Data Access Patterns | MEDIUM | `data-` |
+| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
+| 8 | Advanced Features | LOW | `advanced-` |
+
+## How to Use
+
+Read individual rule files for detailed explanations and SQL examples:
+
+```
+references/query-missing-indexes.md
+references/query-partial-indexes.md
+references/_sections.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect SQL example with explanation
+- Correct SQL example with explanation
+- Optional EXPLAIN output or metrics
+- Additional context and references
+- Supabase-specific notes (when applicable)
+
+## References
+
+- https://www.postgresql.org/docs/current/
+- https://supabase.com/docs
+- https://wiki.postgresql.org/wiki/Performance_Optimization
+- https://supabase.com/docs/guides/database/overview
+- https://supabase.com/docs/guides/auth/row-level-security
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream product or API scope.
+- Verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes.
+- Do not treat generated examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/supabase-postgres-best-practices/references/_contributing.md

@@ -0,0 +1,170 @@
+# Writing Guidelines for Postgres References
+
+This document provides guidelines for creating effective Postgres best
+practice references that work well with AI agents and LLMs.
+
+## Key Principles
+
+### 1. Concrete Transformation Patterns
+
+Show exact SQL rewrites. Avoid philosophical advice.
+
+**Good:** "Use `WHERE id = ANY(ARRAY[...])` instead of
+`WHERE id IN (SELECT ...)`" **Bad:** "Design good schemas"
+
+### 2. Error-First Structure
+
+Always show the problematic pattern first, then the solution. This trains agents
+to recognize anti-patterns.
+
+```markdown
+**Incorrect (sequential queries):** [bad example]
+
+**Correct (batched query):** [good example]
+```
+
+### 3. Quantified Impact
+
+Include specific metrics. Helps agents prioritize fixes.
+
+**Good:** "10x faster queries", "50% smaller index", "Eliminates N+1"
+**Bad:** "Faster", "Better", "More efficient"
+
+### 4. Self-Contained Examples
+
+Examples should be complete and runnable (or close to it). Include `CREATE TABLE`
+if context is needed.
+
+```sql
+-- Include table definition when needed for clarity
+CREATE TABLE users (
+  id bigint PRIMARY KEY,
+  email text NOT NULL,
+  deleted_at timestamptz
+);
+
+-- Now show the index
+CREATE INDEX users_active_email_idx ON users(email) WHERE deleted_at IS NULL;
+```
+
+### 5. Semantic Naming
+
+Use meaningful table/column names. Names carry intent for LLMs.
+
+**Good:** `users`, `email`, `created_at`, `is_active`
+**Bad:** `table1`, `col1`, `field`, `flag`
+
+---
+
+## Code Example Standards
+
+### SQL Formatting
+
+```sql
+-- Use lowercase keywords, clear formatting
+CREATE INDEX CONCURRENTLY users_email_idx
+  ON users(email)
+  WHERE deleted_at IS NULL;
+
+-- Not cramped or ALL CAPS
+CREATE INDEX CONCURRENTLY USERS_EMAIL_IDX ON USERS(EMAIL) WHERE DELETED_AT IS NULL;
+```
+
+### Comments
+
+- Explain _why_, not _what_
+- Highlight performance implications
+- Point out common pitfalls
+
+### Language Tags
+
+- `sql` - Standard SQL queries
+- `plpgsql` - Stored procedures/functions
+- `typescript` - Application code (when needed)
+- `python` - Application code (when needed)
+
+---
+
+## When to Include Application Code
+
+**Default: SQL Only**
+
+Most references should focus on pure SQL patterns. This keeps examples portable.
+
+**Include Application Code When:**
+
+- Connection pooling configuration
+- Transaction management in application context
+- ORM anti-patterns (N+1 in Prisma/TypeORM)
+- Prepared statement usage
+
+**Format for Mixed Examples:**
+
+````markdown
+**Incorrect (N+1 in application):**
+
+```typescript
+for (const user of users) {
+  const posts = await db.query("SELECT * FROM posts WHERE user_id = $1", [
+    user.id,
+  ]);
+}
+```
+````
+
+**Correct (batch query):**
+
+```typescript
+const posts = await db.query("SELECT * FROM posts WHERE user_id = ANY($1)", [
+  userIds,
+]);
+```
+
+---
+
+## Impact Level Guidelines
+
+| Level | Improvement | Use When |
+|-------|-------------|----------|
+| **CRITICAL** | 10-100x | Missing indexes, connection exhaustion, sequential scans on large tables |
+| **HIGH** | 5-20x | Wrong index types, poor partitioning, missing covering indexes |
+| **MEDIUM-HIGH** | 2-5x | N+1 queries, inefficient pagination, RLS optimization |
+| **MEDIUM** | 1.5-3x | Redundant indexes, query plan instability |
+| **LOW-MEDIUM** | 1.2-2x | VACUUM tuning, configuration tweaks |
+| **LOW** | Incremental | Advanced patterns, edge cases |
+
+---
+
+## Reference Standards
+
+**Primary Sources:**
+
+- Official Postgres documentation
+- Supabase documentation
+- Postgres wiki
+- Established blogs (2ndQuadrant, Crunchy Data)
+
+**Format:**
+
+```markdown
+Reference:
+[Postgres Indexes](https://www.postgresql.org/docs/current/indexes.html)
+```
+
+---
+
+## Review Checklist
+
+Before submitting a reference:
+
+- [ ] Title is clear and action-oriented
+- [ ] Impact level matches the performance gain
+- [ ] impactDescription includes quantification
+- [ ] Explanation is concise (1-2 sentences)
+- [ ] Has at least 1 **Incorrect** SQL example
+- [ ] Has at least 1 **Correct** SQL example
+- [ ] SQL uses semantic naming
+- [ ] Comments explain _why_, not _what_
+- [ ] Trade-offs mentioned if applicable
+- [ ] Reference links included
+- [ ] `pnpm test` passes