Anvil reference docs for AI agents

Show and Tell
1

I’ve put together a small Anvil reference repo for use with AI coding agents:

The goal is to give agents enough Anvil-specific context that they don’t have to rediscover the same framework details every time they work on an app.

The repo contains:

  • anvil_reference/: app-neutral notes on Anvil app structure, form YAML, component behavior, data bindings, CSS/layout quirks, server modules, Data Tables, custom components, dependencies, routing, and verification.
  • AGENTS.md: instructions for coding agents so they know when and how to consult the reference docs before editing an Anvil app.
  • A root README explaining how the pieces fit together.

It is meant to be portable and app-neutral. It does not contain arbitrary preferences, standards, or conventions that might go against your app’s coding standards.

It also has pointers to Anvil’s official docs and the open-source runtime repo for things that are not covered by these reference docs, or things that might have changed.

Most importantly, it emphasizes that your app’s own source code is always the source of truth.

The intended use is:

  1. Copy anvil_reference/ into your Anvil app repo.
  2. Copy AGENTS.md, or merge its instructions into your existing agent instructions.
  3. Let your coding agent inspect the actual app first, then use these docs as Anvil-specific context.

Feedback, corrections, and suggestions are very welcome, especially if anything in the reference docs is incomplete, unclear, or likely to drift across Anvil versions.

6 Likes
2

Assuming you’re using the anvil-cli, a skill you might want to consider adding would be

anvil validate <path>

We’ve just added it to the latest version of the anvil-cli and it should help with agent yaml edits to ensure they won’t break your app!

(should work for anvil.yaml and form_template.yaml edits)

3 Likes
3

Thanks Stu! :blush:

I hadn’t yet added the anvil-cli to the reference docs, but it very much makes sense to do so.

And anvil validate would be especially useful!

1 Like
4

yeah you shouldn’t have to say much else about anvil-cli, but it may be useful to mention that an anvil watch process is going on, something like

  • App edits are synced live to Anvil by a running anvil watch process.
  • Normal uncommitted change checks may not reflect local edits, because the working commit is typically amended during sync.

(I’ve found that agents can get confused if they try to look at the current uncommitted changes, which some agents like to do)

1 Like
5

Done, I integrated the cli into the reference docs

1 Like