OpenGemini Next.js Bestpractice Builder

Build and document a solo SaaS project using a fixed Next.js/Tailwind/Prisma stack, with FastAPI only for Python workloads and strict architecture rules.

Security Scan

The skill largely matches its stated purpose (scaffold/docs for a fixed Next.js/Prisma stack) but it omits declaring a critical runtime dependency (the Gemini CLI) and its runtime scripts will call an external AI CLI, which is a proportionality and instruction-scope mismatch the user should understand before running.

Purpose & Capability

The SKILL.md and scripts repeatedly rely on the Gemini CLI (and mention OpenClaw/ACP) as part of normal operation, but the skill metadata declares no required binaries or credentials. A declared dependency on the gemini binary (and any auth it needs) is expected for this skill's purpose; its absence is an incoherence. Otherwise, the files and scripts are consistent with scaffolding and docs-generation for the fixed stack.

Instruction Scope

Runtime scripts (generate_project_docs.sh) invoke 'gemini -p' with the project brief and write generated markdown to project files; bootstrap_tree.sh creates project directories/files. The instructions do not access unrelated system files or environment variables, but they do transmit the provided brief (and any content you pass) to an external AI via the Gemini CLI. The SKILL.md does warn 'verify Gemini CLI is installed and authenticated', but that warning is not reflected in declared requirements.

Install Mechanism

No install spec is present and included scripts only create files and call local binaries. There are no downloads or external installers in the bundle, which keeps install risk low.

Credentials

The skill declares no required environment variables or credentials, yet operation depends on an authenticated Gemini CLI and the broader publish/readiness notes mention external services (Vercel, GitHub, etc.) that typically require credentials. The lack of declared env vars or primary credential is a mismatch — you should assume you need Gemini credentials configured in your environment before use, and be cautious about any other credentials you supply when following the skill's workflows.

Persistence & Privilege

The skill does not request always:true and does not modify other skills or system-wide agent settings. Its scripts create project-local files and a skills/ tree for a scaffold — expected behavior for a project scaffolding skill.

What to consider before installing

This skill appears to be what it says (scaffolding and docs for a fixed Next.js/Prisma stack), but important runtime assumptions are not declared. Before installing or running: (1) ensure the gemini CLI is installed and authenticated — the scripts call 'gemini -p' and will send your project brief and prompts to an external AI service; do not include secrets or tokens in the brief or files you let the skill send. (2) Inspect scripts locally (bootstrap_tree.sh, generate_project_docs.sh) to confirm the file paths and that writing to your filesystem is acceptable. (3) Be aware the skill may prompt you to wire up external services (Vercel, Stripe, Clerk, etc.) which will require credentials; these are not requested by the skill metadata. If you want to reduce risk, run the bootstrap script in an isolated directory, review generated files before committing, and avoid passing any sensitive secrets into the gemini prompts.

Purpose

固定スタックの個人開発SaaSを、ブレない設計と実装ルールで立ち上げる。 技術説明ではなく、実装時の行動基準とプロジェクト構造を強制するための Skill。

Use when

• Next.js + FastAPI 境界を持つ SaaS を新規に作るとき
• 固定スタックで要件定義から scaffold まで一貫して進めたいとき
• Gemini CLI を使って docs・設計・実装計画を高速化したいとき
• 個人開発向けに現実的で保守しやすい構成を最初から敷きたいとき

Do not use when

• 技術選定を自由に変えたいとき
• Python が主役のバックエンドを作るとき
• 単なる小規模LPや静的サイトだけを作るとき
• この固定 stack を外す予定が強いとき

Project assumptions

• Frontend は Next.js App Router
• UI は Tailwind + shadcn/ui
• DB は Neon PostgreSQL
• ORM は Prisma 6
• Auth は Clerk
• Email は Resend
• Payments は Stripe
• Storage は Cloudflare R2
• Analytics は PostHog
• Error Monitoring は Sentry
• Deploy は Vercel
• FastAPI は Python-required workloads のみ

Rules

• docs を先に作り、実装を後追いさせる
• GEMINI.md に source of truth を明記する
• Next.js をデフォルト backend とし、FastAPI を乱用しない
• Clerk auth を Prisma に複製しない
• Stripe 成功判定は webhook 起点にする
• R2 にファイル本体を保存し、DBには metadata だけを置く
• 各 project-level skill は共通テンプレートの型にそろえる
• 各 skill は技術説明ではなく実装時の行動規範として書く
• Prisma は 6 系を固定で使う。7 系へ勝手に上げない
• 開発DBはローカル可だが、本番DBは Neon PostgreSQL を前提にする

Workflow

1. product goal と MVP を整理する
2. references/project-bootstrap-checklist.md を確認する
3. scripts/bootstrap_tree.sh で理想構成を作る
4. scripts/generate_gemini_md.sh で GEMINI.md を作る
5. scripts/generate_project_docs.sh で docs を生成する
6. docs を source of truth にして実装へ進む
7. project-level skills を必要に応じて補強する

Checklist

• GEMINI.md があるか
• docs/requirements.md から docs/db-schema.md まで揃っているか
• skills/*/SKILL.md が共通テンプレートに沿っているか
• FastAPI を使う理由が説明できるか
• Stripe / Clerk / R2 の危険なアンチパターンを避けているか
• Vercel deploy 前提の env 設計が見えているか
• Prisma 6 を固定しているか
• 本番DBが Neon を前提に設計されているか

Common pitfalls

• Next.js で足りる処理まで FastAPI に逃がす
• docs を雑に作って source of truth が死ぬ
• skill を技術メモ化して、行動基準として使えなくする
• Clerk と Prisma の役割を混ぜる
• Stripe webhook を軽視して success redirect に依存する
• file upload を DB 中心で考える
• Prisma 7 に上げて接続・設定周りでハマる

Output expectations

• GEMINI.md
• docs 一式
• 理想ディレクトリ構成
• project-level skills 一式
• stack に沿った実装 plan または scaffold
• 必要なら GitHub / Vercel まで進めるための準備状態

Source of truth order

When generating or updating project files, treat these as the source of truth in order:

1. docs/requirements.md
2. docs/scope.md
3. docs/architecture.md
4. docs/conventions.md
5. docs/decisions/*.md
6. docs/notes/brainstorming.md is reference only

Fixed stack policy

• Frontend: Next.js App Router
• UI: Tailwind + shadcn/ui
• DB: Neon PostgreSQL
• ORM: Prisma 6
• Auth: Clerk
• Email: Resend
• Payments: Stripe
• Storage: Cloudflare R2
• Analytics: PostHog
• Error Monitoring: Sentry
• Deploy: Vercel
• Backend: FastAPI only for Python-required workloads

Backend boundary

Default backend logic lives in Next.js route handlers or server actions. FastAPI exists only for AI, batch jobs, heavy processing, or Python-specific integrations.

Never do

• Do not duplicate Clerk auth state into Prisma as a full auth system
• Do not treat Stripe success redirect as source of truth; use webhook state
• Do not store uploaded files in PostgreSQL
• Do not add FastAPI endpoints for simple CRUD unless explicitly required
• Do not upgrade to Prisma 7 by default

Target project structure

Generate or align toward this structure:

my-saas/
├─ GEMINI.md
├─ src/
│ ├─ app/
│ ├─ components/
│ ├─ features/
│ ├─ lib/
│ ├─ server/
│ ├─ hooks/
│ └─ types/
├─ backend/
│ └─ fastapi/
│ ├─ app/
│ ├─ tests/
│ └─ pyproject.toml
├─ prisma/
│ ├─ schema.prisma
│ ├─ migrations/
│ └─ seed.ts
├─ public/
├─ tests/
│ ├─ unit/
│ ├─ integration/
│ └─ e2e/
├─ docs/
│ ├─ requirements.md
│ ├─ scope.md
│ ├─ architecture.md
│ ├─ conventions.md
│ ├─ integrations.md
│ ├─ db-schema.md
│ ├─ decisions/
│ └─ notes/
│   └─ brainstorming.md
├─ .gemini/
│ └─ commands/
├─ skills/
│ ├─ nextjs/SKILL.md
│ ├─ clerk/SKILL.md
│ ├─ prisma/SKILL.md
│ ├─ shadcn/SKILL.md
│ ├─ stripe/SKILL.md
│ ├─ resend/SKILL.md
│ ├─ posthog/SKILL.md
│ ├─ sentry/SKILL.md
│ ├─ r2/SKILL.md
│ ├─ fastapi/SKILL.md
│ ├─ api-security/SKILL.md
│ └─ vercel/SKILL.md
└─ scripts/

What this skill should produce

For a new project, aim to create at least:

• GEMINI.md
• docs/requirements.md
• docs/scope.md
• docs/architecture.md
• docs/conventions.md
• docs/integrations.md
• docs/db-schema.md
• docs/notes/brainstorming.md
• prisma/schema.prisma
• base app structure under src/
• base FastAPI structure under backend/fastapi/
• .env.example
• integration or implementation plan for Clerk, Stripe, Resend, PostHog, Sentry, and R2

References

Read when needed:

• references/doc-templates.md
• references/integration-rules.md
• references/project-bootstrap-checklist.md
• references/project-skill-template.md

Publish readiness notes

This skill is strongest when used with Gemini CLI plus OpenClaw file and shell control, and optionally ACP for large implementation loops. The project-level skills/*/SKILL.md files should be implementation policies, not generic framework notes.

Before publishing or using this for a real project, verify:

• Gemini CLI is installed and authenticated
• the generated skills/*/SKILL.md files follow the shared template shape
• project docs are generated before major implementation starts
• FastAPI is only introduced when Python is actually required
• deployment assumptions match Vercel reality for the target project
• Prisma is pinned to 6.x
• production DB assumptions match Neon reality