supabase-python

supabase-python スキルの概要

supabase-python は何のためのスキルか

supabase-python スキルは、FastAPI、Supabase Auth、SQLAlchemy/SQLModel を使って Python バックエンドを構築するためのスキルです。Supabase の強みを必要な場面で活かしつつ、アプリの中核データには Python から直接、型安全にデータベースへアクセスしたいチームに最適です。

どんな人に向いているか

API を組み立てる、ログインやセッションの流れを追加する、あるいは認証・ストレージとリレーショナルデータへのアクセスを分けたい場合に supabase-python スキルを使ってください。単なる Supabase の一般論ではなく、実務で使える Supabase Python ガイドがほしい Python バックエンド開発に強くフィットします。

何を最適化するスキルか

基本パターンは明快です。クエリは SQLAlchemy/SQLModel、認証・ストレージ・リアルタイムは Supabase に任せます。そのため、このスキルは、保守しやすい API コード、予測しやすいデータベースアクセス、そして ORM の「魔法」による想定外を減らしたいときに役立ちます。

どんなときに向いていて、どんなときに向かないか

FastAPI アプリと Supabase バックエンドの組み合わせに最も向いています。アプリ全体が Supabase クライアント呼び出しの中で完結している場合や、フロントエンド主導のワークフローが必要な場合は、効果が薄くなります。FastAPI を使っていない、または Python 側のデータベースモデルを使いたくないなら、一般的な Supabase プロンプトよりも対象範囲は狭くなります。

supabase-python スキルの使い方

正しくインストールして接続する

リポジトリの skill install フローを使い、そのスキルを FastAPI の API レイヤーと Supabase ベースのワークフローを持つ Python プロジェクトに向けてください。典型的なインストールコマンドは次のとおりです。
npx skills add alinaqi/claude-bootstrap --skill supabase-python

最初の依頼文で必要な前提を伝える

supabase-python のインストールは、プロンプトで少なくとも 3 つを明示すると最も効果的です。技術スタック、データベースと認証の役割分担、そして作りたい機能です。たとえば「この FastAPI アプリに Supabase のメールログインを追加し、ユーザー記録は SQLModel に保持し、アップロードしたアバターは Supabase Storage に保存してほしい」と伝える形です。単に「Supabase をセットアップして」より、はるかに有効です。

最初に読むべきファイル

まず SKILL.md を読み、次に README.md やリポジトリ固有のドキュメントがあればそれも確認します。あわせて pyproject.toml、src/main.py、src/core/config.py、src/db/models.py、src/api/deps.py、そして supabase/ 配下の migration や config ファイルも見てください。このリポジトリには追加の rules フォルダや resources フォルダはないため、主な情報源はスキル本文とあなたのプロジェクトファイルです。

スキルに合った進め方を使う

supabase-python の良い進め方は、認証要件を定義し、データベースのエンティティを整理し、どのデータを Postgres に残し、どれを Supabase サービスに任せるかを決め、そのうえで route と dependency を実装する流れです。最初から全部を一気に頼むと、認証・ストレージ・データベースアクセスが一つの壊れやすいパターンに混ざってしまいやすくなります。

supabase-python スキルのFAQ

supabase-python は FastAPI プロジェクト専用ですか？

はい、そこが中心的な想定です。スキルは FastAPI のパターンを前提に書かれているため、Django、Flask、あるいは別の async スタックを使っている場合は、字面どおりに従うのではなく、ガイドを自分の構成に合わせて調整する必要があります。

普通のプロンプトより何が優れていますか？

一般的なプロンプトは「Supabase 統合」を求めるだけになりがちで、アーキテクチャが曖昧になったり混ざったりします。supabase-python スキルは、Supabase の認証・ストレージと Python 側のデータベースモデリングをきちんと分けて考えやすくしてくれます。ここが、導入時につまずきやすいポイントです。

SQLModel は必須ですか？

必須ではありません。ただし、このスキルは型安全なデータベースアクセスのために SQLAlchemy/SQLModel を前提に設計されています。すでに raw SQL や別の ORM を使っている場合でも概念的には役立ちますが、実装の細部はそのままではきれいに移せないことがあります。

初心者向けですか？

基本的な Python と FastAPI を知っていれば、初心者にも扱いやすいです。ただし、Supabase や SQLModel の完全な入門書ではないため、ある程度のプロジェクト背景を自分で補い、生成されたコードが既存のアプリ構成に合っているか確認する前提になります。

supabase-python スキルを改善するには

どのデータをどこに置くかを明確に伝える

最良の結果は、要件を認証、リレーショナルデータ、ファイルストレージに分けて伝えたときに得られます。たとえば「ログインとプロフィール画像のアップロードは Supabase、posts、comments、permissions は SQLModel」と指定します。こうすることで、supabase-python スキルがデータの置き場所について不適切な初期判断をするのを防げます。

スキーマとルートの意図を最初に渡す

使えるバックエンドコードがほしいなら、最初のプロンプトでモデル名、主要フィールド、ルートの動作を入れてください。「User に id、email、role がある。/auth/callback と /users/me の endpoints を作る。role ベースのアクセス制御を入れる」と伝えるほうが、一般的な統合依頼よりずっと実行可能です。

ありがちな失敗パターンに注意する

主な失敗は、本来はデータベース層で問い合わせるべきデータまで Supabase クライアント呼び出しに寄せすぎることです。最初の出力で model 定義や dependency の配線が薄いと感じたら、永続化は SQLAlchemy/SQLModel に寄せ、Supabase は auth、storage、realtime に限定するようリファクタリングを依頼してください。

プロジェクト制約を反映させながら反復する

既存の migrations、環境変数の命名規則、async session パターンがあるなら、2 回目の指示の前にそれを伝えてください。supabase-python スキルは、まったく新しいコードベースをでっち上げるのではなく、今あるコードに合わせるよう強制したときに精度が上がります。特にバックエンド開発では、サンプルコードより統合の細部のほうが重要だからです。