Use grate with a coding agent
The use-grate skill helps coding agents author, review, execute and troubleshoot grate migrations in projects that use grate. It covers script lifecycles, ordering, applied-script immutability, provider-specific transaction behavior and recovery.
Its authoring rule is one independently tracked DML statement or DDL operation per one-time migration file. grate can execute SQL batches; this rule makes individual changes easier to track and recover. A procedure definition is one DDL operation even when its body contains multiple statements.
Use the skill
The grate CLI bundles the complete skill: SKILL.md, references and example SQL. Install that bundled version after installing or updating grate. The commands copy files without contacting a database, downloading a skill, or executing SQL.
For a project-local .NET tool, run this from the project repository after dotnet tool install or dotnet tool restore:
dotnet tool run grate -- skills install --local
For Homebrew, winget, MSI, Chocolatey, Debian packages, global .NET tools and extracted self-contained binaries:
grate skills install --global
A global executable can also install into a single project with --local. Select an explicit project directory with grate skills install --local --path /path/to/project. Without --path, local installation finds the nearest parent containing a .git directory or worktree pointer file; outside a repository it uses the current directory. Global installation always uses the current user’s home directory. Run it as that user, without sudo or an elevated installer.
| Scope | Codex / agents | Claude Code |
|---|---|---|
--local | <project>/.agents/skills/use-grate | <project>/.claude/skills/use-grate |
--global | ~/.agents/skills/use-grate | ~/.claude/skills/use-grate |
These are the documented Codex skill locations and Claude Code skill locations. Commit the local copies if the team should share them. Agent discovery depends on the client; the skill itself has no vendor-specific tool dependency or metadata.
Installation is explicit: package managers and dotnet tool install do not run this command automatically, and normal grate migrations do not install skills. Both --local and --global require no additional .NET installation when using a self-contained grate executable. The skill adds no runtime or SDK requirement. The bundle is included in newly built releases; older installed versions of grate do not acquire this command automatically.
An identical installed skill is left untouched. A differing use-grate directory causes installation to fail before either client copy is modified. Back up local edits before using grate skills install --global --force (or --local --force): this replaces each entire use-grate directory, including extra files, with the current executable’s bundle. Other skills are preserved. Installation refuses symbolic links/reparse points within the agent directory paths and skill trees. To update the skill after upgrading grate, rerun the install command with --force after reviewing any local changes. To uninstall it, remove the two use-grate directories; uninstalling the CLI does not remove these user files.
For Docker, bind-mount the intended project and override the migration entrypoint so no database options or secrets are required. Use your project’s pinned image:
docker run --rm --entrypoint /app/grate \
-v "$PWD:/workspace" erikbra/grate:<version> \
skills install --local --path /workspace
Container execution writes as the container’s user; set --user as appropriate for your host’s permissions. Global installation inside a container affects its home, not the host’s home. The source directory docs/skills/use-grate can also be copied manually from a reviewed tag/commit when using an older grate CLI.
For example, ask your agent:
Use the use-grate skill to add a table, an index and initial reference data. Inspect this project’s pinned grate version and folder configuration, create ordered migrations, and verify them against a disposable database using our runner.
The skill does not upgrade grate or grant permission to deploy to a shared database. It uses existing project conventions and target authorization.
Examples and verification
- SQLite migration files separate table creation, index creation and seed inserts.
- Authoring reference explains batch separators, parallel-branch naming, environments and tokens.
- Transaction and recovery reference distinguishes requested transactions from effective rollback and explains preview limitations.
- Verification guidance explains how to check the project’s actual migrations with its pinned runner, provider and test tooling.
The skill contains no executable verifier or shell/PowerShell wrappers. It does not require an installed SDK when used with self-contained grate. SQLite examples illustrate file layout; they do not validate a consumer project’s migrations or establish another provider’s transaction behavior.
Maintaining the skill
The published skill and its bundled contents share one source directory: docs/skills/use-grate. Jekyll renders the same Markdown files that the CLI embeds; there is no generated copy to keep in sync. Site presentation is configured in docs/_config.yml; the authoring reference protects token examples with Liquid raw tags so they stay literal on GitHub Pages as well as in the installed file.
unittests/Sqlite/AgentSkill/MigrationExamplesTests.cs executes the exact bundled SQLite example SQL and checks its table, index, seed row and rerun behavior. This validates the example assets; it does not evaluate how an agent follows the instructions. General migration behavior is covered by the existing provider tests.
The Skill installation CI workflow builds a .NET tool package and a self-contained binary, then tests local and global installation on Windows, Linux and macOS. The tests compare every installed file against the canonical skill directory.