Hi everyone,
A lot of zkApp code is now written with an AI assistant, but most of the o1js code those assistants learned from predates o1js 3 and the Mesa hard fork. So they reach for removed APIs, call Mina.Network(url) in a way that signs for devnet when you meant mainnet, or “upgrade” a contract by redeploying it, which resets its permissions.
I’ve put together an agent skill to close that gap: o1js-skills
What it is
A SKILL.md and 12 reference files that assistants such as Claude Code, Codex and Cursor read when they work on o1js code. It covers:
- the API changes from 0.x–2.x to 3.1;
- what Mesa changed, and how to upgrade a pre-Mesa contract with a signed verification-key update instead of a redeploy;
- a security checklist and common pitfalls, drawn from public audits and o1js-scan;
- tokens, actions and reducers,
OffchainState, transactions and fees, frontends with Web Workers and wallets, and common error messages.
Every claim is tested
The skill ships with a small o1js 3.1.0 project. Its 62 tests reproduce what the references say: removed exports, Mesa limits (16 segments, 32 state fields), the verification-key upgrade path, and attacks against tokens. CI runs them on every push. Once a week it runs them with real proofs and against the newest o1js release, so an o1js update that breaks a claim shows up as a red build.
Does it help?
I gave Claude Opus, Sonnet and Haiku the same tasks with and without the skill. It’s one run per case, so treat it as a demonstration, not a benchmark.
The clearest case: asked for a token where only the admin can mint, Sonnet without the skill wrote one that compiled and passed its own tests. An exploit test then let a stranger mint 1,000,000 of it, because the contract ended up with access: none. With the skill, Sonnet and Haiku both set access: proof(), and Haiku’s token, which compiled, rejected the same attack. Without the skill, Haiku’s mainnet upgrade script also signed for devnet.
Method and all outputs: o1js-skills/eval/README.md at main · izzetemredemir/o1js-skills · GitHub
Install
npx skills add izzetemredemir/o1js-skills
The README also has a Claude Code plugin and a manual install. Then ask for o1js work as usual, for example “write a token where only the admin can mint” or “upgrade my pre-Mesa zkApp on mainnet”.
Found along the way
Writing a test for every claim turned up an o1js bug in repeated range preconditions (issue #2917, fix in PR #2918) and docs examples that are wrong for o1js 3.1 (o1js-documentation-site PR #36).
Feedback
If your assistant still gets something wrong with the skill installed, or you know a pitfall that isn’t covered, please open an issue. Contributions are welcome; the one rule is no claim without a test.
It’s MIT licensed, and a community project, not affiliated with o1Labs or the Mina Foundation.