mildtomato/agent-skills
Overview
This skill is an internal development guide for building the Supabase CLI environments subsystem. It documents the three-environment model, variable resolution, pull/push workflows, secret handling, branch overrides, and local file conventions. Use it when implementing env CLI commands or the environment variable infrastructure.
How this skill works
The guide prescribes a flat, three-environment model (development, preview, production) with strict protections for defaults and no inheritance between environments. It defines pull and push semantics: pull is a full file replacement with server-side branch-override resolution; push displays a diff and performs a bulk upsert of base variable values. It also specifies secret handling (write-only secrets), local file layout (.env and .env.local), canonical variable naming, and branch-specific per-variable overrides.
When to use it
- Implementing env CLI commands (pull, push, list, set, unset, create, delete, seed)
- Designing variable resolution logic for local and deployed contexts
- Handling write-only secret variables and interactive push prompts
- Implementing branch-to-environment mapping and branch-specific overrides
- Designing pull/push workflows with diff displays and confirmation
Best practices
- Protect the three default environments: do not allow rename or delete of development/preview/production
- Treat environments as flat independent sets — avoid inheritance or fallback chains
- Make secrets write-only: exclude them from pull/list and require explicit interactive confirmation when pushing
- Push operations must show a clear diff and use bulk upsert API calls rather than one-at-a-time updates
- Keep only two local files (.env and .env.local), follow OS/.env.local/.env resolution order
Example use cases
- Implementing push: compute diff, display additions/changes/removals, request confirmation, send a single bulk upsert request
- Implementing pull: fetch server-resolved variables (including branch overrides), replace local .env file atomically
- Creating branch-specific overrides: use env set --branch to set per-variable overrides without affecting base values
- Seeding a new environment: run interactive keep/edit/skip flow to populate variables consistently
- Linking a project: prompt to push local variables to remote when transitioning from local-first to remote-first mode
FAQ
Secrets are write-only and excluded from pull outputs; the CLI should not show secret values when listing or pulling variables.
Can environments inherit values from other environments?
No. Environments are flat with no inheritance. Each environment holds an independent set of variables.
2 skills
This skill helps you implement and manage Supabase CLI environments across development, preview, and production with secure variable handling.
This skill helps you write, review, and edit documentation in apps/docs and all md or mdx files with clear, user-focused guidance.
