Agent Skill
This site publishes an agent skill: a package of instructions that teaches a coding agent how ezz actually works. Point your agent's installer at this domain and it picks up the framework's shape, its conventions, and the handful of behaviours that are easy to get wrong.
Install it
pnpx skills add https://ezz.sulv.org
npx skills add https://ezz.sulv.org does the same thing if you are not using pnpm.
The installer reads the discovery index at /.well-known/skills/index.json, which lists every skill this site publishes along with its files. There is one, named ezz.
Know what it contains
The skill leads with a short SKILL.md your agent always reads, and eleven reference files it loads only when the task calls for one. That split keeps the common case cheap: an agent writing a handler pulls in binding and validation, not the GoTrue proxy.
| File | Covers |
|---|---|
SKILL.md | Mental model, a complete runnable app, the traps, and a map to everything below |
references/routing-and-groups.md | Patterns, groups, nesting, route metadata |
references/handlers-and-binding.md | ezz.H, the tag table, validation rules, response rules |
references/context.md | Reading requests, writing responses, streaming, pooling |
references/errors.md | HTTPError, status mapping, panics |
references/middleware.md | Defaults, ordering, CORS, gzip, rate limiting |
references/auth.md | Providers, rules, precedence, custom credentials |
references/rbac.md | Resolvers, caching, hierarchies, audit logging |
references/gotrue.md | Proxy setup, endpoints, client IP, deployment |
references/openapi.md | Generation, Scalar UI, what is and is not emitted |
references/testing.md | TestApp, handler tests, auth tests, proxy tests |
references/api-reference.md | The full exported surface, signature-dense |
Understand what it corrects
A model that has never seen ezz will fall back on habits from other Go frameworks, and several of those habits produce code that compiles and then misbehaves quietly. The skill front-loads exactly those cases:
validatesupports six rules, not thego-playground/validatorset.uuid,gte, andoneofare ignored silently, so a field an agent believes is guarded is not. See Validation.- A zero-value return writes no body. A handler returning a nil pointer sends
200with nothing in it. See Handlers. - JSON bodies bind flat into the request struct, mixed with
pathandqueryfields, rather than into a nested body field. See Request binding. - Auth rules come from
ezz, providers fromauth.auth.Role(...)is a leftover from an earlier design and does not satisfyezz.AuthRule. See Auth rules. - Middleware and group rules are snapshotted at registration, so ordering matters. See Middleware.
Every code sample in the skill is checked against the source in the repository, and the app in SKILL.md is compiled as part of keeping it honest.
Keep it up to date
Re-run the install command to pull the current version. The skill is versioned with the docs site, so it describes the framework as of whatever is deployed here.
Publish it from your own build
The skill lives in docs-site/skills/ezz/ and is served by the Docus skills module, which scans a skills/ directory at the Nuxt root and needs no configuration. A local pnpm dev serves the same endpoints, so you can point an installer at http://localhost:3000 to test a change before it ships.
curl -s http://localhost:3000/.well-known/skills/index.json
curl -s http://localhost:3000/.well-known/skills/ezz/SKILL.md