Skip to main content
supaschema ships optional agent context for consuming projects so an AI agent can make schema changes without reading the entire source repository or guessing the migration workflow. Default package setup does not activate that context. For a new project setup, copy the agent prompt from Installation. The important instruction is simple: install the package with the consuming project’s package manager, run supaschema init, inspect the generated config and install manifest, then run schema commands through that same manager’s local runner. Install the raw agent bundle only after the user explicitly approves AI-agent enforcement.

​
Agent workflow

1

Install the package

Install supaschema in the package or workspace that owns the schema workflow. Do not clone the supaschema repository into the project unless you are intentionally developing supaschema itself.
2

Review optional context

Default setup leaves raw agent files under node_modules/supaschema/agent-bundle/. Read agent-bundle/INSTALL.md and install them only when the user asks for AI-agent enforcement.
3

Edit schema intent

Change the configured declarative SQL tree, such as database/schemas/**, neon/schemas/**, aws-postgresql/schemas/**, or supabase/schemas/**.
4

Run one command

Run diff through the local runner from the install prompt. The command extracts both sides, plans the change, renders the migration, and refreshes configured TypeScript and Zod outputs.
5

Report the result

Summarize the generated migration, generated outputs, target runner expectations, and any SUPA_* diagnostic. Apply only through an explicit user request or a config-gated supaschema sync workflow with resolved targets and required remote approval.

​
Optional agent context

The public npm package includes the consumer-safe raw surfaces needed for that workflow:

Install prompt

Copyable setup instructions for another coding agent.

Rule

Durable migration policy: generated files are not hand-edited, destructive intent must be explicit, and apply is config-gated.

Skill

The repeatable schema-change workflow for agents that support skills.

Hooks

Write-time guardrails that block generated migration edits, run diff or config-gated sync after schema edits, and sync installed LLM surfaces.

​
Optional discovery surfaces

Use these only when the agent or documentation client supports them.

Hosted skill

Public agent skill metadata for clients that can read https://supaschema.com/docs/skill.md.

llms.txt

Compressed docs context for agents that load https://supaschema.com/docs/llms.txt.

MCP docs

Mintlify MCP endpoint for documentation-aware clients at https://supaschema.com/docs/mcp.

npx skills

Installs reusable skill context only; project setup still comes from the package manager plus supaschema init.
The npm package is the project integration path. npx skills is useful for reusable agent context, but it cannot replace project config, path-confirmation state, or the optional reviewed agent-bundle install.
Last modified on June 19, 2026